このページは、まだ日本語ではご利用いただけません。翻訳中です。
Configuring built-in listeners
For configuring built-in gateway listeners, use the MeshGateway
resource.
These are Kong Mesh policies so if you are running on multi-zone they need to be created on the Global CP. See the dedicated section for using builtin gateways on multi-zone.
The MeshGateway
resource specifies what network ports the gateway should listen on and how network traffic should be accepted.
A builtin gateway Dataplane can have exactly one MeshGateway
resource bound to it.
This binding uses standard, tag-based Kong Mesh matching semantics:
Heads up! In previous versions of Kong Mesh, setting the
kuma.io/service
tag directly within aMeshGatewayInstance
resource was used to identify the service. However, this practice is deprecated and no longer recommended for security reasons since Kong Mesh version 2.7.0.We’ve automatically switched to generating the service name for you based on your
MeshGatewayInstance
resource name and namespace (format:{name}_{namespace}_svc
).
apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
name: edge-gateway
spec:
selectors:
- match:
kuma.io/service: edge-gateway_default_svc
A MeshGateway
can have any number of listeners, where each listener represents an endpoint that can accept network traffic.
Note that the MeshGateway
doesn’t specify which IP addresses are listened on; the Dataplane
resource specifies that.
To configure a listener, you need to specify at least the port number and network protocol. Each listener may also have its own set of Kong Mesh tags so that Kong Mesh policy configuration can be targeted to specific listeners.
apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
name: edge-gateway
spec:
selectors:
- match:
kuma.io/service: edge-gateway_default_svc
conf:
listeners:
- port: 8080
protocol: HTTP
tags:
port: http-8080
Hostname
An HTTP or HTTPS listener can also specify a hostname
.
Note that listeners can share both port
and protocol
but differ on hostname
.
This way routes can be attached to requests to specific hostnames but share
the port/protocol with other routes attached to other hostnames.
apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
name: edge-gateway
spec:
selectors:
- match:
kuma.io/service: edge-gateway_default_svc
conf:
listeners:
- port: 8080
protocol: HTTP
hostname: foo.example.com
tags:
port: http-8080
In the above example, the gateway proxy listens for HTTP protocol connections on TCP port 8080 but restricts the Host
header to foo.example.com
.
apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
name: edge-gateway
spec:
selectors:
- match:
kuma.io/service: edge-gateway_default_svc
conf:
listeners:
- port: 8080
protocol: HTTP
hostname: foo.example.com
tags:
vhost: foo.example.com
- port: 8080
protocol: HTTP
hostname: bar.example.com
tags:
vhost: bar.example.com
Above shows a MeshGateway
resource with two HTTP listeners on the same port.
In this example, the gateway proxy will be configured to listen on port 8080, and accept HTTP requests for both hostnames.
Note that because each listener entry has its own Kong Mesh tags, policy can still be targeted to a specific listener.
Kong Mesh generates a set of tags for each listener by combining the tags from the listener, the MeshGateway
and the Dataplane
.
Kong Mesh matches policies against this set of combined tags.
Dataplane tags |
Listener tags | Final Tags |
---|---|---|
kuma.io/service=edge-gateway_default_svc | vhost=foo.example.com | kuma.io/service=edge-gateway_default_svc,vhost=foo.example.com |
kuma.io/service=edge-gateway_default_svc | kuma.io/service=example,domain=example.com | kuma.io/service=example,domain=example.com |
kuma.io/service=edge_default_svc,location=us | version=2 | kuma.io/service=edge_default_svc,location=us,version=2 |
TLS Termination
TLS sessions are terminated on a Gateway by specifying the “HTTPS” protocol, and providing a server certificate configuration. Below, the gateway listens on port 8443 and terminates TLS sessions.
apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
name: edge-gateway
spec:
selectors:
- match:
kuma.io/service: edge-gateway_default_svc
conf:
listeners:
- port: 8443
protocol: HTTPS
hostname: foo.example.com
tls:
mode: TERMINATE
certificates:
- secret: foo-example-com-certificate
tags:
name: foo.example.com
The server certificate is provided through a Kong Mesh datasource reference, in this case naming a secret that must contain both the server certificate and the corresponding private key.
Server Certificate Secrets
A TLS server certificate secret is a collection of PEM objects in a Kong Mesh datasource (which may be a file, a Kong Mesh secret, or inline data).
There must be at least a private key and the corresponding TLS server certificate. The CA certificate chain may also be present, but if it is, the server certificate must be the first certificate in the secret.
Kong Mesh gateway supports serving both RSA and ECDSA server certificates.
To enable this support, generate two server certificate secrets and provide them both to the listener TLS configuration.
The kumactl
tool supports generating simple, self-signed TLS server certificates. The script below shows how to do this.
apiVersion: v1
kind: Secret
metadata:
name: foo-example-com-certificate
namespace: kong-mesh-system
labels:
kuma.io/mesh: default
data:
value: "$(kumactl generate tls-certificate --type=server --hostname=foo.example.com --key-file=- --cert-file=- | base64 -w0)"
type: system.kuma.io/secret
Cross-mesh
The Mesh
abstraction allows users
to encapsulate and isolate services
inside a kind of sub-mesh with its own CA.
With a cross-mesh MeshGateway
,
you can expose the services of one Mesh
to other Mesh
es by defining an API with MeshHTTPRoute
s.
All traffic remains inside the Kong Mesh data plane protected by mTLS.
All meshes involved in cross-mesh communication must have mTLS enabled.
To enable cross-mesh functionality for a MeshGateway
listener,
set the crossMesh
property.
apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
name: cross-mesh-gateway
labels:
kuma.io/mesh: default
spec:
selectors:
- match:
kuma.io/service: cross-mesh-gateway_default_svc
conf:
listeners:
- port: 8080
protocol: HTTP
crossMesh: true
hostname: default.mesh
Hostname
If the listener includes a hostname
value,
the cross-mesh listener will be reachable
from all Mesh
es at this hostname
and port
.
In this case, the URL http://default.mesh:8080
.
Otherwise it will be reachable at the host:
internal.<gateway-name>.<mesh-of-gateway-name>.mesh
.
Without transparent proxy
If transparent proxy isn’t set up, you’ll have to add the listener explicitly as
an outbound to your Dataplane
objects if you want to access it:
...
outbound:
- port: 8080
tags:
kuma.io/service: cross-mesh-gateway
kuma.io/mesh: default
Limitations
The only protocol
supported is HTTP
.
Like service to service traffic,
all traffic to the gateway is protected with mTLS
but appears to be HTTP traffic
to the applications inside the mesh.
In the future, this limitation may be relaxed.
There can be only one entry in selectors
for a MeshGateway
with crossMesh: true
.
All options
$schema: http://json-schema.org/draft-04/schema#
$ref: #/definitions/MeshGateway
definitions
MeshGateway
- ## Mesh Gateway
- MeshGateway is a virtual proxy. Each MeshGateway is bound to a set of builtin gateway dataplanes. Each builtin dataplane instance can host exactly one Gateway proxy configuration. Gateway aligns with the Kubernetes Gateway API. See that spec for detailed documentation.
- Type:
object
- This schema accepts additional properties.
- Properties
- selectors
- Selectors is a list of selectors that are used to match builtin gateway dataplanes that will receive this MeshGateway configuration.
- Type:
array
- Items
- $ref: #/definitions/kuma.mesh.v1alpha1.Selector
- tags
- Tags is the set of tags common to all of the gateway's listeners. This field must not include a
kuma.io/service
tag (the service is always defined on the dataplanes). - Type:
object
- This schema accepts additional properties.
- Properties
- Tags is the set of tags common to all of the gateway's listeners. This field must not include a
- conf
- The desired configuration of the MeshGateway.
- $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.Conf
- selectors
kuma.mesh.v1alpha1.MeshGateway.Conf
- ## Conf
- Conf defines the desired state of MeshGateway. Aligns with MeshGatewaySpec.
- Type:
object
- This schema accepts additional properties.
- Properties
- listeners
- Listeners define logical endpoints that are bound on this MeshGateway's address(es).
- Type:
array
- listeners
kuma.mesh.v1alpha1.MeshGateway.Listener
- ## Listener
- Type:
object
- This schema accepts additional properties.
- Properties
- hostname
- Hostname specifies the virtual hostname to match for protocol types that define this concept. When unspecified, "", or
*
, all hostnames are matched. This field can be omitted for protocols that don't require hostname based matching. - Type:
string
- Hostname specifies the virtual hostname to match for protocol types that define this concept. When unspecified, "", or
- port
- Port is the network port. Multiple listeners may use the same port, subject to the Listener compatibility rules.
- Type:
integer
- protocol
- #### Protocol
- The value is restricted to the following:
- "NONE"
0
- "TCP"
1
- "TLS"
3
- "HTTP"
4
- "HTTPS"
5
- tls
- TLS is the TLS configuration for the Listener. This field is required if the Protocol field is "HTTPS" or "TLS" and ignored otherwise.
- $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.TLS.Conf
- tags
- Tags specifies a unique combination of tags that routes can use to match themselves to this listener. When matching routes to listeners, the control plane constructs a set of matching tags for each listener by forming the union of the gateway tags and the listener tags. A route will be attached to the listener if all of the route's tags are preset in the matching tags
- Type:
object
- This schema accepts additional properties.
- Properties
- crossMesh
- CrossMesh enables traffic to flow to this listener only from other meshes.
- Type:
boolean
- resources
- Resources is used to specify listener-specific resource settings.
- $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.Listener.Resources
- hostname
kuma.mesh.v1alpha1.MeshGateway.Listener.Resources
- ## Resources
- Type:
object
- This schema accepts additional properties.
- Properties
- connection_limit
- Type:
integer
- Type:
- connection_limit
kuma.mesh.v1alpha1.MeshGateway.TLS.Conf
- ## Conf
- Aligns with MeshGatewayTLSConfig.
- Type:
object
- This schema accepts additional properties.
- Properties
- mode
- #### Mode
- The value is restricted to the following:
- "NONE"
0
- "TERMINATE"
1
- "PASSTHROUGH"
2
- certificates
- Certificates is an array of datasources that contain TLS certificates and private keys. Each datasource must contain a sequence of PEM-encoded objects. The server certificate and private key are required, but additional certificates are allowed and will be added to the certificate chain. The server certificate must be the first certificate in the datasource. When multiple certificate datasources are configured, they must have different key types. In practice, this means that one datasource should contain an RSA key and certificate, and the other an ECDSA key and certificate.
- Type:
array
- Items
- $ref: #/definitions/kuma.system.v1alpha1.DataSource
- options
- Options should eventually configure how TLS is configured. This is where cipher suite and version configuration can be specified, client certificates enforced, and so on.
- $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.TLS.Options
- mode
kuma.mesh.v1alpha1.MeshGateway.TLS.Options
- ## Options
- TODO(jpeach)
- Type:
object
- This schema accepts additional properties.
- Properties
kuma.mesh.v1alpha1.Selector
- ## Selector
- Selector defines structure for selecting tags for given dataplane
- Type:
object
- This schema accepts additional properties.
- Properties
- match
- Tags to match, can be used for both source and destinations
- Type:
object
- This schema accepts additional properties.
- Properties
- match
kuma.system.v1alpha1.DataSource
- ## Data Source
- DataSource defines the source of bytes to use.
- Type:
object
- This schema accepts additional properties.
- Properties
- secret
- Data source is a secret with given Secret key.
- Type:
string
- file
- Data source is a path to a file. Deprecated, use other sources of a data.
- Type:
string
- inline
- Data source is inline bytes.
- Type:
string
- inlineString
- Data source is inline string
- Type:
string
- secret
Generated with json-schema-md-doc