MeshExternalService
This resource is experimental!
This resource allows services running inside the mesh to consume services that are not part of the mesh.
The MeshExternalService
resource allows you to declare external resources instead of relying on MeshPassthrough or passthrough mode.
What is the difference between MeshPassthrough
and MeshExternalService
?
The main difference is that MeshExternalService
assigns a custom domain and can be targeted by policies.
MeshPassthrough
does not alter the address of the original host and cannot be targeted by policies.
Currently you can not configure granular MeshTrafficPermission for MeshExternalService. You can only enable or disable whole traffic to MeshExternalService from Mesh by Mesh resource configuration. More on this in Controlling MeshExternalService access from Mesh section.
Configuration
Match
This section specifies the rules for matching traffic that will be routed to external resources defined in endpoints
section.
The only type
supported is HostnameGenerator
(this field is optional so can be omitted) and it means that it will match traffic directed to a hostname created by the hostname generator.
The port
field when omitted means that all traffic will be matched.
Protocols that are supported are: tcp
, grpc
, http
, http2
.
Endpoints
This section specifies the destination of the matched traffic. It’s possible to define IPs, DNS names and unix domain sockets.
TLS
This section describes the TLS and verification behaviour.
TLS origination happens on the sidecar, so if your application is already using TLS you might want to use MeshPassthrough.
You can define TLS version requirements, option to allow renegotiation, verification of SNI, SAN, custom CA and client certificate and key for server verification.
To disable parts of the verification you can set different mode
- SkipSAN
, SkipCA
, SkipAll
, Secured
(default).
When TLS is enabled but caCert
is not set, the sidecar uses the autodetected OS-specific CA.
The user can override the default CA by setting the path in the environment variable KUMA_DATAPLANE_RUNTIME_DYNAMIC_SYSTEM_CA_PATH
for the sidecar.
DNS setup
To be able to access MeshExternalService
via a hostname you need to define a HostnameGenerator
with a meshExternalService
selector.
In the future release a default HostnameGenerator
will be provided.
Once a HostnameGenerator
and a MeshExternalService
is in place the following will happen:
- a hostname (or multiple hostnames if there are many
HostnameGenerators
matching) are generated using the specified templates - a VIP is allocated from
242.0.0.0/8
range (can be changed byKUMA_IPAM_MESH_EXTERNAL_SERVICE_CIDR
environment variable) - Envoy cluster is created which will use endpoints defined in
spec.endpoints
as the cluster endpoints
Do not hijack original addresses like httpbin.com (the way it was done with External Service). Hijacking the original address is like performing a man-in-the-middle attack so there is a high chance of something breaking. If you need to transparently pass traffic through the Mesh without modifying it use MeshPassthrough.
For accessing entire subdomains, take a look at Wildcard DNS matching in MeshPassthrough.
Universal mode without Transparent Proxy
MeshExternalService
works on Universal mode without Transparent Proxy, but you need to manually define an outbound that targets the correct MeshExternalService
:
The whole command will look something like this:
Controlling MeshExternalService access from Mesh
At this moment you cannot configure MeshTrafficPermission for MeshExternalService. But you can configure access to all external services on Mesh level. For example, you can disable outgoing traffic to all MeshExternalServices:
Examples
TCP examples use https://tcpbin.com/ service which is a TCP echo service, check out the website for more details. HTTP examples use https://httpbin.org/ service which is a website for inspecting and debugging HTTP requests. GRPC examples use https://grpcbin.test.k6.io/ service which is a gRPC Request & Response Service. You can use grpcurl as a client, it is available in netshoot debug image alongside other tools used in later sections.
For the examples below we’re using a single-zone deployment and the following HostnameGenerator
:
If you’re in multi-zone deployment and you’re applying resources on the global control plane you’d need a second HostnameGenerator
with matchLabels: kuma.io/origin: global
for resources applied on the global Control Plane and to adjust the URLs accordingly to match the template.
TCP
This is a simple example of accessing tcpbin.com
service without TLS that echos back bytes sent to it.
Running this should result in printing ‘echo this’ in the terminal:
TCP with TLS
This example builds up on the previous example adding TLS verification with default system CA.
Notice that we’re using a TLS port 4243
.
Running this should result in printing ‘echo this’ in the terminal:
TCP with mTLS
This example builds up on the previous example adding client cert and key.
Notice that we’re using an mTLS port 4244
.
In a real world scenario you should use secret
and refer to it through it’s name and store sensitive information as a Kubernetes secret instead of using inline
.
This example is purposefully simplified to make it easy to try out.
Running this should result in printing ‘echo this’ in the terminal:
HTTP
This is a simple example using plaintext HTTP.
Running this should result in printing httpbin.org HTML in the terminal:
HTTPS
This example builds up on the previous example adding TLS verification with default system CA.
Running this should result in printing httpbin.org HTML in the terminal:
gRPC
This is a simple example using plaintext gRPC.
Running this should result in printing grpcbin.test.k6.io available methods:
gRPCS
This example builds up on the previous example adding TLS verification with default system CA.
Notice that we’re using a different port 9001
.
Running this should result in printing grpcbin.test.k6.io available methods:
All policy configuration settings
Spec is the specification of the Kuma MeshExternalService resource.
Type: object
Properties
- endpoints
- Endpoints defines a list of destinations to send traffic to.
- Type:
array
- Items
- Type:
object
- Properties
- address
required
- Address defines an address to which a user want to send a request. Is possible to provide
domain
,ip
. - Type:
string
- Length: ≥ 1
- Address defines an address to which a user want to send a request. Is possible to provide
- port
required
- Port of the endpoint
- Type:
integer
- Range: between 1 and 65535
- address
- extension
- Extension struct for a plugin configuration, in the presence of an extension
endpoints
andtls
are not required anymore - it's up to the extension to validate them independently. - Type:
object
- Properties
- config
required
- Config freeform configuration for the extension.
- type
required
- Type of the extension.
- Type:
string
- config
- Extension struct for a plugin configuration, in the presence of an extension
- match
required
- Match defines traffic that should be routed through the sidecar.
- Type:
object
- Properties
- port
required
- Port defines a port to which a user does request.
- Type:
integer
- Range: between 1 and 65535
- protocol
- Protocol defines a protocol of the communication. Possible values:
tcp
,grpc
,http
,http2
. - Type:
string
- The value is restricted to the following:
- "tcp"
- "grpc"
- "http"
- "http2"
- Default: "tcp"
- Protocol defines a protocol of the communication. Possible values:
- type
- Type of the match, only
HostnameGenerator
is available at the moment. - Type:
string
- The value is restricted to the following:
- "HostnameGenerator"
- Default: "HostnameGenerator"
- Type of the match, only
- port
- tls
- Tls provides a TLS configuration when proxy is resposible for a TLS origination
- Type:
object
- Properties
- allowRenegotiation
- AllowRenegotiation defines if TLS sessions will allow renegotiation.Setting this to true is not recommended for security reasons.
- Type:
boolean
- Default: false
- enabled
- Enabled defines if proxy should originate TLS.
- Type:
boolean
- Default: false
- verification
- Verification section for providing TLS verification details.
- Type:
object
- Properties
- caCert
- CaCert defines a certificate of CA.
- Type:
object
- Properties
- inline
- Data source is inline bytes.
- Type:
string
- String format must be a "byte"
- inlineString
- Data source is inline string`
- Type:
string
- secret
- Data source is a secret with given Secret key.
- Type:
string
- inline
- clientCert
- ClientCert defines a certificate of a client.
- Type:
object
- Properties
- inline
- Data source is inline bytes.
- Type:
string
- String format must be a "byte"
- inlineString
- Data source is inline string`
- Type:
string
- secret
- Data source is a secret with given Secret key.
- Type:
string
- inline
- clientKey
- ClientKey defines a client private key.
- Type:
object
- Properties
- inline
- Data source is inline bytes.
- Type:
string
- String format must be a "byte"
- inlineString
- Data source is inline string`
- Type:
string
- secret
- Data source is a secret with given Secret key.
- Type:
string
- inline
- mode
- Mode defines if proxy should skip verification, one of
SkipSAN
,SkipCA
,Secured
,SkipAll
. DefaultSecured
. - Type:
string
- The value is restricted to the following:
- "SkipSAN"
- "SkipCA"
- "Secured"
- "SkipAll"
- Default: "Secured"
- Mode defines if proxy should skip verification, one of
- serverName
- ServerName overrides the default Server Name Indicator set by Kuma.
- Type:
string
- subjectAltNames
- SubjectAltNames list of names to verify in the certificate.
- Type:
array
- Items
- Type:
object
- Properties
- type
- Type specifies matching type, one of
Exact
,Prefix
. Default:Exact
- Type:
string
- The value is restricted to the following:
- "Exact"
- "Prefix"
- Default: "Exact"
- Type specifies matching type, one of
- value
required
- Value to match.
- Type:
string
- type
- caCert
- version
- Version section for providing version specification.
- Type:
object
- Properties
- max
- Max defines maximum supported version. One of
TLSAuto
,TLS10
,TLS11
,TLS12
,TLS13
. - Type:
string
- The value is restricted to the following:
- "TLSAuto"
- "TLS10"
- "TLS11"
- "TLS12"
- "TLS13"
- Default: "TLSAuto"
- Max defines maximum supported version. One of
- min
- Min defines minimum supported version. One of
TLSAuto
,TLS10
,TLS11
,TLS12
,TLS13
. - Type:
string
- The value is restricted to the following:
- "TLSAuto"
- "TLS10"
- "TLS11"
- "TLS12"
- "TLS13"
- Default: "TLSAuto"
- Min defines minimum supported version. One of
- max
- allowRenegotiation
Generated with json-schema-md-doc