Kuma Star

Careful!

You are browsing documentation for the next version of Kuma. Use this version at your own risk.

MeshExternalService

This resource is experimental.

MeshExternalService enables services inside the mesh to consume services outside the mesh. Unlike MeshPassthrough which allows transparent traffic to external services, MeshExternalService declares external destinations as first-class resources with custom hostnames, virtual IPs, and policy targeting support.

Kuma performs TLS origination at the sidecar proxy, allowing plaintext communication from applications while establishing secure connections to external endpoints. This enables centralized TLS management, certificate validation, and mTLS client authentication.

For usage patterns, configuration examples, and differences from MeshPassthrough, see the MeshExternalService guide.

Prerequisites

Spec fields

Field Description
match Defines traffic routing rules. Required.
match.type Match type, must be HostnameGenerator. Default: HostnameGenerator.
match.port Port number for incoming requests (1-65535). Required.
match.protocol Protocol: tcp (default), grpc, http, http2.
endpoints Destination addresses for traffic. Optional if extension is configured.
endpoints[].address IP address, domain name, or unix socket (unix:///path/to/socket).
endpoints[].port Destination port number (1-65535, not used for unix sockets).
tls TLS origination configuration. Optional.
tls.enabled Enable TLS origination at sidecar. Default: false.
tls.version TLS version constraints.
tls.version.min Minimum TLS version: TLSAuto (default), TLS10, TLS11, TLS12, TLS13.
tls.version.max Maximum TLS version: TLSAuto (default), TLS10, TLS11, TLS12, TLS13.
tls.allowRenegotiation Allow TLS renegotiation (not recommended). Default: false.
tls.verification TLS verification settings.
tls.verification.mode Verification mode: Secured (default), SkipSAN, SkipCA, SkipAll.
tls.verification.serverName Override SNI server name.
tls.verification.subjectAltNames List of SANs to verify in certificate.
tls.verification.subjectAltNames[].type Match type: Exact (default) or Prefix.
tls.verification.subjectAltNames[].value Value to match against SAN.
tls.verification.caCert CA certificate data source (inline, inlineString, or secret reference).
tls.verification.clientCert Client certificate for mTLS (inline, inlineString, or secret reference).
tls.verification.clientKey Client private key for mTLS (inline, inlineString, or secret reference).
extension Plugin configuration for custom behavior. Optional.
extension.type Extension type identifier.
extension.config Freeform extension configuration.

TLS verification modes

  • Secured: Full verification (CA + SAN). Default and recommended.
  • SkipSAN: Verify CA only, skip SAN matching.
  • SkipCA: Verify SAN only, skip CA validation.
  • SkipAll: No verification (insecure, for testing only).

When caCert is not specified, the sidecar uses OS-specific system CA certificates. Override with KUMA_DATAPLANE_RUNTIME_DYNAMIC_SYSTEM_CA_PATH environment variable.

Access control

MeshExternalService access is controlled at the Mesh level (MeshTrafficPermission not supported):

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  routing:
    defaultForbidMeshExternalServiceAccess: true

Examples

HTTP external service

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: httpbin
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 80
    protocol: http
  endpoints:
    - address: httpbin.org
      port: 80

HTTPS with TLS origination

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: httpbin-tls
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 80
    protocol: http
  endpoints:
    - address: httpbin.org
      port: 443
  tls:
    enabled: true
    verification:
      mode: Secured
      serverName: httpbin.org

TCP external service with mTLS

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: database
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 5432
    protocol: tcp
  endpoints:
    - address: postgres.external.example.com
      port: 5432
  tls:
    enabled: true
    version:
      min: TLS12
      max: TLS13
    verification:
      mode: Secured
      serverName: postgres.external.example.com
      clientCert:
        secret: postgres-client-cert
      clientKey:
        secret: postgres-client-key

gRPC external service

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: grpc-api
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 9000
    protocol: grpc
  endpoints:
    - address: grpcbin.test.k6.io
      port: 9001
  tls:
    enabled: true
    verification:
      serverName: grpcbin.test.k6.io

Multiple endpoints with load balancing

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: api-gateway
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 443
    protocol: http
  endpoints:
    - address: api1.example.com
      port: 443
    - address: api2.example.com
      port: 443
    - address: 203.0.113.10
      port: 443
  tls:
    enabled: true
    verification:
      serverName: api.example.com

unix domain socket

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: local-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 8080
    protocol: http
  endpoints:
    - address: unix:///var/run/service.sock

TLS with custom certificate authority

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: private-api
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 443
    protocol: http
  endpoints:
    - address: internal.corp.example.com
      port: 443
  tls:
    enabled: true
    verification:
      mode: Secured
      serverName: internal.corp.example.com
      caCert:
        secret: corporate-ca-cert

Verifying SAN with prefix matching

apiVersion: kuma.io/v1alpha1
kind: MeshExternalService
metadata:
  name: spiffe-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  match:
    type: HostnameGenerator
    port: 443
    protocol: http
  endpoints:
    - address: service.example.com
      port: 443
  tls:
    enabled: true
    verification:
      mode: Secured
      serverName: service.example.com
      subjectAltNames:
        - type: Exact
          value: service.example.com
        - type: Prefix
          value: "spiffe://example.com/ns/production"

Universal mode without transparent proxy

Configure outbound explicitly:

type: Dataplane
mesh: default
name: backend
networking:
  address: 127.0.0.1
  inbound:
    - port: 8080
      servicePort: 8080
      tags:
        kuma.io/service: backend
  outbound:
    - port: 10080
      backendRef:
        kind: MeshExternalService
        name: httpbin

See also

All options

apiVersion string
APIVersion defines the versioned schema of this representation of an object. Servers should convert ...
kind string
Kind is a string value representing the REST resource this object represents. Servers may infer this...
metadata object
spec object
Spec is the specification of the Kuma MeshExternalService resource.
Endpoints defines a list of destinations to send traffic to.
address string required
Address defines an address to which a user want to send a request. Is possible to provide `domain`, ...
port integer required
Port of the endpoint
Extension struct for a plugin configuration, in the presence of an extension `endpoints` and `tls` a...
config any
Config freeform configuration for the extension.
type string required
Type of the extension.
Match defines traffic that should be routed through the sidecar.
port integer required
Port defines a port to which a user does request.
protocol enum
Protocol defines a protocol of the communication. Possible values: `tcp`, `grpc`, `http`, `http2`.
Values: tcp | grpc | http | http2
Default: "tcp"
type enum
Type of the match, only `HostnameGenerator` is available at the moment.
Values: HostnameGenerator
Default: "HostnameGenerator"
Tls provides a TLS configuration when proxy is resposible for a TLS origination
allowRenegotiation boolean
AllowRenegotiation defines if TLS sessions will allow renegotiation. Setting this to true is not rec...
enabled boolean
Enabled defines if proxy should originate TLS.
Verification section for providing TLS verification details.
CaCert defines a certificate of CA.
inline string
Data source is inline bytes.
inlineString string
Data source is inline string`
secret string
Data source is a secret with given Secret key.
ClientCert defines a certificate of a client.
inline string
Data source is inline bytes.
inlineString string
Data source is inline string`
secret string
Data source is a secret with given Secret key.
ClientKey defines a client private key.
inline string
Data source is inline bytes.
inlineString string
Data source is inline string`
secret string
Data source is a secret with given Secret key.
mode enum
Mode defines if proxy should skip verification, one of `SkipSAN`, `SkipCA`, `Secured`, `SkipAll`. De...
Values: SkipSAN | SkipCA | Secured | SkipAll
Default: "Secured"
serverName string
ServerName overrides the default Server Name Indicator set by Kuma.
SubjectAltNames list of names to verify in the certificate.
type enum
Type specifies matching type, one of `Exact`, `Prefix`. Default: `Exact`
Values: Exact | Prefix
Default: "Exact"
value string required
Value to match.
Version section for providing version specification.
max enum
Max defines maximum supported version. One of `TLSAuto`, `TLS10`, `TLS11`, `TLS12`, `TLS13`.
Values: TLSAuto | TLS10 | TLS11 | TLS12 | TLS13
Default: "TLSAuto"
min enum
Min defines minimum supported version. One of `TLSAuto`, `TLS10`, `TLS11`, `TLS12`, `TLS13`.
Values: TLSAuto | TLS10 | TLS11 | TLS12 | TLS13
Default: "TLSAuto"
status object
Status is the current status of the Kuma MeshExternalService resource.
Addresses section for generated domains
hostname string
coreName string required
origin string
Conditions is an array of hostname generator conditions.
message string required
message is a human readable message indicating details about the transition. This may be an empty st...
reason string required
reason contains a programmatic identifier indicating the reason for the condition's last transition....
status enum required
status of the condition, one of True, False, Unknown.
Values: True | False | Unknown
type string required
type of condition in CamelCase or in foo.example.com/CamelCase.
coreName string required
Vip section for allocated IP
ip string
Value allocated IP for a provided domain with `HostnameGenerator` type in a match section.