TCP connections

In addition to managing HTTP, GRPC, and Websockets at layer 7, Ambassador Edge Stack can also manage TCP connections at layer 4. The core abstraction used to support TCP connections is the TCPMapping.

TCPMapping

An Ambassador Edge Stack TCPMapping associates TCP connections with Kubernetes services. Cleartext TCP connections are defined by destination IP address and/or destination TCP port; TLS TCP connections can also be defined by the hostname presented using SNI. A service is exactly the same as in Kubernetes.

TCPMapping configuration

Ambassador Edge Stack supports a number of attributes to configure and customize mappings.

If both enable_ipv4 and enable_ipv6 are set, Ambassador Edge Stack will prefer IPv6 to IPv4. See the ambassador Module documentation for more information.

Ambassador Edge Stack can manage TCP connections using TLS:

Ambassador Edge Stack supports multiple deployment patterns for your services. These patterns are designed to let you safely release new versions of your service while minimizing its impact on production users.

The name of the mapping must be unique.

TCPMapping and TLS

The host attribute of a TCPMapping determines whether Ambassador Edge Stack will terminate TLS when a client connects. The service prefix (if any) and the tls attribute work together to determine whether Ambassador Edge Stack will originate TLS. The two are independent.

This leaves four cases:

host is not set, and the service does not state https://

In this case, Ambassador Edge Stack simply proxies bytes between the client and the upstream. TLS may or may not be involved, and Ambassador Edge Stack doesn't care. You should specify the port to use for the upstream connection; if you don't, Ambassador Edge Stack will guess port 80.

Examples:

could be used to relay an SSH connection on port 2222, or

could proxy a CockroachDB connection.

host is set, but the service has no https:// prefix

In this case, Ambassador Edge Stack will terminate the TLS connection, require that the host offered with SNI match the host attribute, and then make a cleartext connection to the upstream host. You should specify the port to use for the upstream connection; if you don't, Ambassador Edge Stack will guess port 80.

This can be useful for doing host-based TLS proxying of arbitrary protocols, allowing the upstream to not have to care about TLS.

Note that this case requires that you have created a termination TLSContext, and that the termination TLSContext has a host that matches the host in the TCPMapping. (This is the same rule as TLS termination with SNI in an HTTP Mapping.)

Example:

The example above will accept a TLS connection with SNI on port 2222. If the client requests SNI host my-host-1, the decrypted traffic will be relayed to upstream-host-1, port 9999. If the client requests SNI host my-host-2, the decrypted traffic will be relayed to upstream-host-2, port 9999. Any other SNI host will cause the TLS handshake to fail.

host is set, and service has an https:// prefix

In this case, Ambassador Edge Stack will terminate the incoming TLS connection, require that the host offered with SNI match the host attribute, and then make a TLS connection to the upstream host. If tls is also set, Ambassador Edge Stack will use to determine the certificate offered to the upstream service. You should specify the port to use for the upstream connection; if you don't, Ambassador Edge Stack will guess port 443.

This is useful for doing host routing while maintaining end-to-end encryption.

Note that this case requires that you have created a termination TLSContext, and that the termination TLSContext has a host that matches the host in the TCPMapping. (This is the same rule as TLS termination with SNI in an HTTP Mapping.)

Example:

The example above will accept a TLS connection with SNI on port 2222.

If the client requests SNI host my-host-1, the traffic will be relayed over a TLS connection to upstream-host-1, port 9999. No client certificate will be offered for this connection.

If the client requests SNI host my-host-2, the decrypted traffic will be relayed to upstream-host-2, port 9999. The client certificate from origination-context will be offered for this connection.

Any other SNI host will cause the TLS handshake to fail.

host is not set, but service has an https:// prefix

Here, Ambassador Edge Stack will accept the connection without terminating TLS, then relay traffic over a TLS connection upstream. This is probably useful only to accept unencrypted traffic and force it to be encrypted when it leaves Ambassador Edge Stack.

Example:

The example above will accept any connection to port 2222 and relay it over a TLS connection to upstream-host port 9999. No client certificate will be offered.

Summary

• To get a TCPMapping to terminate TLS, configure Ambassador Edge Stack with a termination TLSContext and list a host in the TCPMapping.

• To get a TCPMapping to originate TLS, use an http:// prefix for the TCPMapping's service. Use the tls attribute as well if you want to offer a certificate to the upstream service.

• You can mix and match as long as you think about how the protocols interact.

Required attributes for TCPMappings

• name is a string identifying the Mapping (e.g. in diagnostics)
• port is an integer specifying which port to listen on for connections
• service is the name of the service handling the resource; must include the namespace (e.g. myservice.othernamespace) if the service is in a different namespace than Ambassador Edge Stack

Note that the service in a TCPMapping should include a port number, and may include a scheme of https.

Namespaces and Mappings

Given that AMBASSADOR_NAMESPACE is correctly set, Ambassador Edge Stack can map to services in other namespaces by taking advantage of Kubernetes DNS:

• service: servicename will route to a service in the same namespace as Ambassador Edge Stack, and
• service: servicename.namespace will route to a service in a different namespace.