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.
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.
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.
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 by KUMA_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.
MeshExternalService works on Universal mode without Transparent Proxy, but you need to manually define an outbound that targets the correct MeshExternalService:
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:
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.
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.
Endpoints defines a list of destinations to send traffic to.
Hide Child Parameters
addressstringrequired
Address defines an address to which a user want to send a request. Is possible to provide domain, ip.
>= 1 characters
Example:example.com
portintegerrequired
Port of the endpoint
>= 1<= 65535
extensionobject
Extension struct for a plugin configuration, in the presence of an extension endpoints and tls are not required anymore - it’s up to the extension to validate them independently.
Hide Child Parameters
config
Config freeform configuration for the extension.
typestringrequired
Type of the extension.
matchobjectrequired
Match defines traffic that should be routed through the sidecar.
Hide Child Parameters
portintegerrequired
Port defines a port to which a user does request.
>= 1<= 65535
protocolstring
Protocol defines a protocol of the communication. Possible values: tcp, grpc, http, http2.
Allowed values:tcpgrpchttphttp2
Default:tcp
typestring
Type of the match, only HostnameGenerator is available at the moment.
Allowed values:HostnameGenerator
Default:HostnameGenerator
tlsobject
Tls provides a TLS configuration when proxy is resposible for a TLS origination
Hide Child Parameters
allowRenegotiationboolean
AllowRenegotiation defines if TLS sessions will allow renegotiation.
Setting this to true is not recommended for security reasons.
Default:false
enabledboolean
Enabled defines if proxy should originate TLS.
Default:false
verificationobject
Verification section for providing TLS verification details.
Hide Child Parameters
caCertobject
CaCert defines a certificate of CA.
Hide Child Parameters
inlinestring(byte)
Data source is inline bytes.
inlineStringstring
Data source is inline string`
secretstring
Data source is a secret with given Secret key.
clientCertobject
ClientCert defines a certificate of a client.
Hide Child Parameters
inlinestring(byte)
Data source is inline bytes.
inlineStringstring
Data source is inline string`
secretstring
Data source is a secret with given Secret key.
clientKeyobject
ClientKey defines a client private key.
Hide Child Parameters
inlinestring(byte)
Data source is inline bytes.
inlineStringstring
Data source is inline string`
secretstring
Data source is a secret with given Secret key.
modestring
Mode defines if proxy should skip verification, one of SkipSAN, SkipCA, Secured, SkipAll. Default Secured.
Allowed values:SkipSANSkipCASecuredSkipAll
Default:Secured
serverNamestring
ServerName overrides the default Server Name Indicator set by Kuma.
subjectAltNamesarray[object]
SubjectAltNames list of names to verify in the certificate.
Hide Child Parameters
typestring
Type specifies matching type, one of Exact, Prefix. Default: Exact
Allowed values:ExactPrefix
Default:Exact
valuestringrequired
Value to match.
versionobject
Version section for providing version specification.
Hide Child Parameters
maxstring
Max defines maximum supported version. One of TLSAuto, TLS10, TLS11, TLS12, TLS13.
Allowed values:TLSAutoTLS10TLS11TLS12TLS13
Default:TLSAuto
minstring
Min defines minimum supported version. One of TLSAuto, TLS10, TLS11, TLS12, TLS13.