Use the HTTP ALPN annotation#

Background#

For an on-mesh non-gateway server workload that needs to accept both plaintext and mTLS traffic from off-mesh, on-cluster non-gateway client workloads, the server’s Istio peer-authentication mTLS mode must be set to PERMISSIVE. Normally, in PERMISSIVE mode, the server’s sidecar accepts mTLS traffic that uses only Istio HTTP ALPN protocol IDs (for example, istio-http/1.1), which are not standard. Therefore, the server rejects mTLS traffic that uses standard HTTP ALPN protocol IDs (http/1.0, http/1.1, and h2).

About the HTTP ALPN annotation#

You can use the HTTP ALPN annotation to configure an on-mesh non-gateway workload that has a peer-authentication mTLS mode of PERMISSIVE so it accepts mTLS traffic from off-mesh, on-cluster non-gateway workloads that use standard HTTP ALPN protocol IDs.

Assumptions#

The instructions below assume that you have already:

Use the HTTP ALPN annotation on a namespace#

Note

Perform this task when you want all on-mesh non-gateway workloads in a namespace that have a peer-authentication mTLS mode of PERMISSIVE to accept mTLS traffic from off-mesh, on-cluster non-gateway workloads that use standard HTTP ALPN protocol IDs.

  • Modify the peer-authentication policy for the namespace so it includes the following field:

    .metadata.annotations.http-alpns.aspenmesh.io: “true”

    Example

    apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: foo
  annotations:
    http-alpns.aspenmesh.io: "true"
spec:
  mtls:
    mode: PERMISSIVE

Use the HTTP ALPN annotation on an on-mesh non-gateway workload#

Note

Perform this task when you want an on-mesh non-gateway workload that has a peer-authentication mTLS mode of PERMISSIVE to accept mTLS traffic from off-mesh, on-cluster non-gateway workloads that use standard HTTP ALPN protocol IDs.

  1. Modify the peer-authentication policy for the on-mesh non-gateway workload so it includes the following field:

    .metadata.annotations.http-alpns.aspenmesh.io: “true”

    Example

    apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: foo
  annotations:
    http-alpns.aspenmesh.io: "true"
spec:
  selector:
    matchLabels:
      app: finance
  mtls:
    mode: PERMISSIVE

  2. If the peer authentication policy already exists, delete and re-create it.

Restrictions#

When using the HTTP ALPN annotation, the following restrictions apply:

  • The HTTP ALPN annotation has an effect only when the peer-authentication policy’s mTLS mode is set to PERMISSIVE. The annotation has no effect when the mTLS mode is STRICT or NONE.

  • Use of the HTTP ALPN annotation in the istio-system namespace is not supported.

  • If you use the HTTP ALPN annotation on both a namespace and an on-mesh non-gateway workload in that namespace, the workload annotation overrides the namespace annotation. For example, if a namespace HTTP ALPN annotation is set to “true” but the annotation for an on-mesh non-gateway workload in that namespace is set to “false”, the workload won’t accept mTLS traffic from off-mesh, on-cluster workloads using standard ALPN protocol IDs, but other on-mesh non-gateway workloads in that namespace will.