Configure off-mesh workloads to use a service account’s Citadel workload certificate#

Introduction#

The instructions below describe how to configure the following items to use a service account’s Citadel workload certificate so they can participate in encrypted (TLS or mTLS) communication:

The pods in an off-mesh, on-cluster non-gateway workload
The off-mesh interfaces of the pods in an Istio gateway workload

Note

If you haven’t already done so, learn about the Aspen Mesh certificate authorities (CAs) and the types of pods they support.

Before you begin#

Make sure Aspen Mesh and Citadel are installed.

Configure the pods in an off-mesh, on-cluster non-gateway workload to use a service account’s Citadel workload certificate#

Note

Perform this task when you want to allow certificate and identity validation of the pods in an off-mesh, on-cluster non-gateway workload.
This task only configures the pods, which results in Kubernetes mounting credential files from the service account’s Citadel workload certificate in the pods and making them available to the application containers. The application itself is responsible for serving certificates using those files. For more information, see the last step of this task.

Make sure Citadel workload certificates are enabled for the off-mesh, on-cluster non-gateway workload’s namespace.
Open the manifest for the off-mesh, on-cluster non-gateway workload in a text editor.
In the pod spec for the workload, add an istio-certs volume and set .spec.volumes[].secret.secretName for that volume to istio.<serviceAccountName>, where istio.<serviceAccountName> is a service account’s Citadel workload certificate (in the form of a secret) that’s in the same namespace as the workload:
```
volumes:
- name: istio-certs
  secret:
    defaultMode: 420
    optional: true
    secretName: istio.<serviceAccountName>
```
Note

Although it’s not recommended, you can specify any Citadel workload certificate (istio.<serviceAccountName>) in the non-gateway workload’s namespace, not just the certificate whose service account the non-gateway workload is configured to use.
In the container spec for the application, add a volume mount that references the istio-certs volume and mounts it at the directory in which the application expects to find the credential files from the Citadel workload certificate (for example, /etc/certs):

Example
```
volumeMounts:
- name: istio-certs
  mountPath: /etc/certs
```
Save and close the manifest.

If the workload is already running, restart all pods in the workload:

Example

$ kubectl rollout restart deployment <deploymentName> --namespace <namespaceName>

For each pod in the off-mesh, on-cluster non-gateway workload (assuming it’s running), Kubernetes retrieves the credentials in the specified Citadel workload certificate—three for use by gateway workloads and three for use by non-gateway workloads—and stores them in individual files in the istio-certs volume. For each application container in the pod, Kubernetes mounts that volume at the directory specified by the value of mountPath (for example, /etc/certs).

Important

For encrypted (TLS or mTLS) communication with other workloads, the application itself is responsible for serving certificates using the non-gateway credential files that Kubernetes mounted in the application container.

This table describes each of the non-gateway credential files:

File	Description
`cert-chain.pem`	The pod’s certificate chain of trust that includes all intermediate certificates between the pod and the root CA
`key.pem`	The pod’s private key
`root-cert.pem`	The root CA certificate for the pod’s certificate

You can ignore the gateway credential files (cacert, cert, and key).

Configure the off-mesh interfaces of the pods in an Istio gateway workload to use a service account’s Citadel workload certificate#

Note

Perform this task when you want to allow certificate and identity validation of the off-mesh interfaces of the pods in an Istio gateway workload.

Make sure Citadel workload certificates are enabled for the gateway workload’s namespace.
Open the manifest you’ve created for the Istio gateway (not the Istio gateway workload) in a text editor.
For each server that needs a certificate, set .spec.servers[].tls.credentialName to istio.<serviceAccountName>, where istio.<serviceAccountName> is a service account’s Citadel workload certificate (in the form of a secret) that’s in the same namespace as the Istio gateway workload.

Example: Istio ingress gateway configured so the server shown uses the httpbin service account’s Citadel workload certificate
```
apiVersion: networking.istio.io/v1alpha3
kind: Gateway
...
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    tls:
      mode: SIMPLE
      credentialName: istio.httpbin
```
Note

You can specify any Citadel workload certificate (istio.<serviceAccountName>) in the Istio gateway workload’s namespace. However, it’s recommended that you don’t specify the certificate whose service account the Istio gateway workload is configured to use; instead, create your own service account and specify its certificate.

During an upgrade of Aspen Mesh, Helm overwrites the service account that the Istio gateway workload is configured to use. If you specify that service account’s certificate and you specify custom traditional SAN names for the Istio gateway’s workload (by modifying that service account), the traditional SAN names will be lost when you upgrade Aspen Mesh.
Save and close the manifest.
If the gateway is already running, apply the changes:
```
$ kubectl apply -f <gatewayManifestFilename> --namespace <namespaceName>
```
For each servers section that you configured to use a Citadel workload certificate (assuming the gateway is running), the off-mesh interfaces of the gateway workload’s pods will present the specified service account’s Citadel workload certificate for encrypted (TLS or mTLS) communication for that server with off-mesh, off-cluster workloads.

Enable Citadel workload certificates for a namespace#

Note

Perform this task only when other instructions tell you to do so.
Make sure yq 4.18.1 or later is installed before performing this task.

Add the Citadel-certificate label to the namespace:
```
$ kubectl label namespace <namespaceName> \
    ca.istio.io/override=true --overwrite
```
Citadel creates and maintains a unique workload certificate (in the form of a secret named istio.<serviceAccountName>) for each service account in the namespace.

Verify that Citadel has created a certificate for the default service account in the namespace:

$ kubectl get secret istio.default --namespace <namespaceName> --output yaml | \
    yq '.data.cert' | base64 --decode | openssl x509 -noout -text