External Service

This policy allows services running inside the mesh to consume services that are not part of the mesh. The ExternalService resource allows you to declare specific external resources by name within the mesh, instead of implementing the default passthrough mode. Passthrough mode allows access to any non-mesh host by specifying its domain name or IP address, without the ability to apply any traffic policies. The ExternalService resource enables the same observability, security, and traffic manipulation for external traffic as for services entirely inside the mesh

When you enable this policy, you should also disable passthrough mode for the mesh and enable the data plane proxy builtin DNS name resolution.

Usage

A simple HTTPS external service can be defined:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: ExternalService
  3. mesh: default
  4. metadata:
  5.   name: httpbin
  6. spec:
  7.   tags:
  8.     kuma.io/service: httpbin
  9.     kuma.io/protocol: http
  10.   networking:
  11.     address: httpbin.org:443
  12.     tls: # optional
  13.       enabled: true
  14.       allowRenegotiation: false
  15.       sni: httpbin.org # optional
  16.       caCert: # one of inline, inlineString, secret
  17.         inline: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t... # Base64 encoded cert
  18.       clientCert: # one of inline, inlineString, secret
  19.         secret: clientCert
  20.       clientKey: # one of inline, inlineString, secret
  21.         secret: clientKey

Then apply the configuration with kubectl apply -f [..].

  1. type: ExternalService
  2. mesh: default
  3. name: httpbin
  4. tags:
  5.   kuma.io/service: httpbin
  6.   kuma.io/protocol: http
  7. networking:
  8.   address: httpbin.org:443
  9.   tls:
  10.     enabled: true
  11.     allowRenegotiation: false
  12.     sni: httpbin.org # optional
  13.     caCert: # one of inline, inlineString, secret
  14.       inline: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t... # Base64 encoded cert
  15.     clientCert: # one of inline, inlineString, secret
  16.       secret: clientCert
  17.     clientKey: # one of inline, inlineString, secret
  18.       secret: clientKey

Then apply the configuration with kumactl apply -f [..] or with the HTTP API.

Universal mode is best combined with transparent proxy. For backward compatibility only, you can consume an external service from within the mesh by filling the proper outbound section of the relevant data plane resource:

  1. type: Dataplane
  2. mesh: default
  3. name: redis-dp
  4. networking:
  5.   address: 127.0.0.1
  6.   inbound:
  7.   - port: 9000
  8.     tags:
  9.       kuma.io/service: redis
  10.   outbound:
  11.   - port: 10000
  12.     tags:
  13.       kuma.io/service: httpbin

Then httpbin.org is accessible at 127.0.0.1:10000.

Accessing the External Service

Consuming the defined service from within the mesh for both Kubernetes and Universal deployments (assuming transparent proxy) can be done:

  • With the .mesh naming of the service curl httpbin.mesh. With this approach, specify port 80.
  • With the real name and port, in this case curl httpbin.org:443. This approach works only with the data plane proxy builtin DNS name resolution.

Although the external service is HTTPS, it’s consumed as plain HTTP. This is possible because when networking.tls.enabled is set to true then Envoy is responsible for originating and verifying TLS.

To consume the service using HTTPS, set the service protocol to kuma.io/protocol: tcp and networking.tls.enabled=false. This way application itself is responsible for originating and verifying TLS and Envoy is just passing the connection to a proper destination.

The first approach has an advantage that we can apply HTTP based policies, because Envoy is aware of HTTP protocol and can apply request modifications before the request is encrypted. Additionally, we can modify TLS certificates without restarting applications.

Available policy fields

  • tags the external service can include an arbitrary number of tags, where kuma.io/service is mandatory. The special kuma.io/protocol tag is also taken into account and supports the standard Kuma protocol values. It designates the specific protocol for the service.
  • ` networking` describes the networking configuration of the external service
    • address is the address where the external service can be reached.
    • tls is the section to configure the TLS originator when consuming the external service
      • enabled turns on and off the TLS origination.
      • allowRenegotiation turns on and off TLS renegotiation. It’s not recommended enabling this for security reasons. However, some servers require this setting to fetch client certificate after TLS handshake. TLS renegotiation is not available in TLS v1.3.
      • sni overrides the default Server Name Indication. Set this value to empty string to disable SNI.
      • caCert the CA certificate for the external service TLS verification
      • clientCert the client certificate for mTLS
      • clientKey the client key for mTLS

As with other services, avoid duplicating service names under kuma.io/service with already existing ones. A good practice is to derive the tag value from the domain name or IP of the actual external service.

External Services and Locality Aware Load Balancing

There are might be scenarios when a particular external service should be accessible only from the particular zone. In order to make it work we should use kuma.io/zone tag for external service. When this tag is set and locality aware load balancing is enabled then the traffic from the zone will be redirected only to external services associated with the zone using kuma.io/zone tag.

Example:

  1. type: ExternalService
  2. mesh: default
  3. name: httpbin-for-zone-1
  4. tags:
  5.   kuma.io/service: httpbin
  6.   kuma.io/protocol: http
  7.   kuma.io/zone: zone-1
  8. networking:
  9.   address: zone-1.httpbin.org:80
  10. ---
  11. type: ExternalService
  12. mesh: default
  13. name: httpbin-for-zone-2
  14. tags:
  15.   kuma.io/service: httpbin
  16.   kuma.io/protocol: http
  17.   kuma.io/zone: zone-2
  18. networking:
  19.   address: zone-2.httpbin.org:80

In this example, when locality aware load balancing is enabled, if the service in zone-1 is trying to set connection with httpbin.mesh it will be redirected to zone-1.httpbin.org:80. Whereas the same request from zone-2 will be redirected to zone-2.httpbin.org:80.