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.
Currently MeshExternalService
resource only supports targeting by MeshTrafficPermission with Zone Egress.
This limitation will be lifted in the next release.
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:
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: