Understanding TLS Configuration
One of Istio’s most important features is the ability to lock down and secure network traffic to, from, and within the mesh. However, configuring TLS settings can be confusing and a common source of misconfiguration. This document attempts to explain the various connections involved when sending requests in Istio and how their associated TLS settings are configured. Refer to TLS configuration mistakes for a summary of some the most common TLS configuration problems.
Sidecars
Sidecar traffic has a variety of associated connections. Let’s break them down one at a time.
Sidecar proxy network connections
External inbound traffic This is traffic coming from an outside client that is captured by the sidecar. If the client is inside the mesh, this traffic may be encrypted with Istio mutual TLS. By default, the sidecar will be configured to accept both mTLS and non-mTLS traffic, known as
PERMISSIVE
mode. The mode can alternatively be configured toSTRICT
, where traffic must be mTLS, orDISABLE
, where traffic must be plaintext. The mTLS mode is configured using a PeerAuthentication resource.Local inbound traffic This is traffic going to your application service, from the sidecar. This traffic will always be forwarded as-is. Note that this does not mean it’s always plaintext; the sidecar may pass a TLS connection through. It just means that a new TLS connection will never be originated from the sidecar.
Local outbound traffic This is outgoing traffic from your application service that is intercepted by the sidecar. Your application may be sending plaintext or TLS traffic. If automatic protocol selection is enabled, Istio will automatically detect the protocol. Otherwise you should use the port name in the destination service to manually specify the protocol.
External outbound traffic This is traffic leaving the sidecar to some external destination. Traffic can be forwarded as is, or a TLS connection can be initiated (mTLS or standard TLS). This is controlled using the TLS mode setting in the
trafficPolicy
of a DestinationRule resource. A mode setting ofDISABLE
will send plaintext, whileSIMPLE
,MUTUAL
, andISTIO_MUTUAL
will originate a TLS connection.
The key takeaways are:
PeerAuthentication
is used to configure what type of mTLS traffic the sidecar will accept.DestinationRule
is used to configure what type of TLS traffic the sidecar will send.- Port names, or automatic protocol selection, determines which protocol the sidecar will parse traffic as.
Auto mTLS
As described above, a DestinationRule
controls whether outgoing traffic uses mTLS or not. However, configuring this for every workload can be tedious. Typically, you want Istio to always use mTLS wherever possible, and only send plaintext to workloads that are not part of the mesh (i.e., ones without sidecars).
Istio makes this easy with a feature called “Auto mTLS”. Auto mTLS works by doing exactly that. If TLS settings are not explicitly configured in a DestinationRule
, the sidecar will automatically determine if Istio mutual TLS should be sent. This means that without any configuration, all inter-mesh traffic will be mTLS encrypted.
Gateways
Any given request to a gateway will have two connections.
Gateway network connections
The inbound request, initiated by some client such as
curl
or a web browser. This is often called the “downstream” connection.The outbound request, initiated by the gateway to some backend. This is often called the “upstream” connection.
Both of these connections have independent TLS configurations.
Note that the configuration of ingress and egress gateways are identical. The istio-ingress-gateway
and istio-egress-gateway
are just two specialized gateway deployments. The difference is that the client of an ingress gateway is running outside of the mesh while in the case of an egress gateway, the destination is outside of the mesh.
Inbound
As part of the inbound request, the gateway must decode the traffic in order to apply routing rules. This is done based on the server configuration in a Gateway resource. For example, if an inbound connection is plaintext HTTP, the port protocol is configured as HTTP
:
apiVersion: networking.istio.io/v1beta1
kind: Gateway
...
servers:
- port:
number: 80
name: http
protocol: HTTP
Similarly, for raw TCP traffic, the protocol would be set to TCP
.
For TLS connections, there are a few more options:
What protocol is encapsulated? If the connection is HTTPS, the server protocol should be configured as
HTTPS
. Otherwise, for a raw TCP connection encapsulated with TLS, the protocol should be set toTLS
.Is the TLS connection terminated or passed through? For passthrough traffic, configure the TLS mode field to
PASSTHROUGH
:apiVersion: networking.istio.io/v1beta1
kind: Gateway
...
servers:
- port:
number: 443
name: https
protocol: HTTPS
tls:
mode: PASSTHROUGH
In this mode, Istio will route based on SNI information and forward the connection as-is to the destination.
Should mutual TLS be used? Mutual TLS can be configured through the TLS mode
MUTUAL
. When this is configured, a client certificate will be requested and verified against the configuredcaCertificates
orcredentialName
:apiVersion: networking.istio.io/v1beta1
kind: Gateway
...
servers:
- port:
number: 443
name: https
protocol: HTTPS
tls:
mode: MUTUAL
caCertificates: ...
Outbound
While the inbound side configures what type of traffic to expect and how to process it, the outbound configuration controls what type of traffic the gateway will send. This is configured by the TLS settings in a DestinationRule
, just like external outbound traffic from sidecars, or auto mTLS by default.
The only difference is that you should be careful to consider the Gateway
settings when configuring this. For example, if the Gateway
is configured with TLS PASSTHROUGH
while the DestinationRule
configures TLS origination, you will end up with double encryption. This works, but is often not the desired behavior.
A VirtualService
bound to the gateway needs care as well to ensure it is consistent with the Gateway
definition.