External Service

    When you enable this policy, you should also disable passthrough mode for the mesh and enable the name resolution.

    Simple configuration of external service requires name of the resource, kuma.io/service: service-name, and address. By default, a protocol used for communication is TCP. It’s possible to change that by configuring kuma.io/protocol tag. Apart from that, it’s possible to define TLS configuration used for communication with external services. More information about configuration options can be found .

    Below is an example of simple HTTPS external service:

    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 # optional, one of http, http2, tcp, grpc, kafka
    7. networking:
    8.   address: httpbin.org:443
    9.   tls:
    10.     enabled: true
    11.     allowRenegotiation: false
    12.     serverName: httpbin.org # optional
    13.     caCert: # one of inline, inlineString, secret
    14.       inline: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t... # Base64 encoded cert
    15.     clientCert: # one of inline, inlineString, secret
    16.     clientKey: # one of inline, inlineString, secret
    17.       secret: clientKey

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

    Universal mode is best combined with . 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:

    Then httpbin.org is accessible at 127.0.0.1:10000.

    • 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 name resolution.

    It’s possible to define TLS origination and validation at 2 different layers:

    • Envoy is responsible for originating and verifying TLS.
    • Application itself is responsible for originating and verifying TLS and Envoy is just passing the connection to a proper destination.

    In the first case, the external service is defined as HTTPS, but 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.

    The second approach allows consuming the service using HTTPS. It’s possible when kuma.io/protocol: tcp and are set in the configuration of the external service.

    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.

    • tags the external service can include an arbitrary number of tags, where:
      • kuma.io/service is mandatory.
      • kuma.io/protocol tag is also taken into account and supports the standard Kuma protocol values. It designates the specific protocol for the service (one of: http, https, tcp, grpc, kafka, default: tcp).
      • kuma.io/zone tag is taken into account when is enabled or external service should be accessible only from the specific zone.
    • ` 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 . However, some servers require this setting to fetch client certificate after TLS handshake. TLS renegotiation is not available in TLS v1.3.
        • serverName 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.

    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 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/zone: zone-1
    7. networking:
    8.   address: zone-1.httpbin.org:80
    9. ---
    10. type: ExternalService
    11. mesh: default
    12. name: httpbin-for-zone-2
    13. tags:
    15.   kuma.io/protocol: http
    16.   kuma.io/zone: zone-2
    17. networking:
    18.   address: zone-2.httpbin.org:80

    In scenarios when traffic to external services needs to be sent through a unique set of hosts you will .

    For example when there is:

    • disabled passthrough mode
    • ZoneEgress deployed

    • ExternalService configuration that allows communicating with https://example.com.

    When application makes a request to https://example.com, it will be first routed to ZoneEgress and then to https://example.com. You can completely block your instances to communicate to things outside the mesh by . In this setup, applications will only be able to communicate with other applications in the mesh or external-services via the ZoneEgress.

    There are might be scenarios when a specific ExternalService might be accessible only through the specific zone. To make it work we should use the kuma.io/zone tag for external service. In order to make it work, we need a multi-zone setup with ZoneIngress and ZoneEgress deployed. Also, needs to be enabled.

    Example:

    1. type: ExternalService
    2. mesh: default
    3. name: httpbin-only-in-zone-2
    4. tags:
    5.  kuma.io/service: httpbin
    6.  kuma.io/protocol: http
    7.  kuma.io/zone: zone-2
    8. networking:

    In this example, when all the conditions mentioned above are fulfilled if the service in zone-1 is trying to set a connection with httpbin.mesh it will be redirected to the ZoneEgress instance within the zone-1. Next, this request goes to the ZoneIngress instance in zone-2 which redirects it to the ZoneEgress cluster instance from where it goes outside to the ExternalService.

    Builtin Gateway support