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.

Status fields

Status is managed by Kuma:

Field Description
addresses Generated hostnames from HostnameGenerators.
vip.ip Virtual IP address allocated from mesh external service CIDR (default 242.0.0.0/8, configurable via KUMA_IPAM_MESH_EXTERNAL_SERVICE_CIDR).
hostnameGenerators Status of hostname generation from each HostnameGenerator.

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

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