Plug in CA certificates#

About plugging in CA certificates#

Introduction#

You can plug in your own custom CA certificates and private key, which Istiod (and Citadel, if installed) uses to create workload certificates.

Note

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

What happens if you don’t plug in CA certificates#

If you don’t plug in CA certificates, then:

Istiod creates a self-signed RSA root certificate and private key, which it uses to create workload certificates.
Citadel (if installed) won’t start.

When to plug in CA certificates#

Plug in CA certificates when any of the following is true:

Your organization’s security and compliance policies require the use of your centralized CA infrastructure as root for all issued certificates, including workload certificates created by Istiod (and Citadel, if installed).
You’re using Citadel (for example, because you’re using Packet Inspector 1)

Note

It’s recommended that you plug in CA certificates when you first install Aspen Mesh in case you later need to install Citadel, which requires that you plug in CA certificates.

Required CA credential files#

To plug in CA certificates, you need the following CA credential files, which you’ll include in the Kubernetes secret that Istiod (and Citadel, if installed) uses to create workload certificates:

File	Description
`ca-cert.pem`	The certificate associated with the private key found in `ca-key.pem` (the issuing certificate). Note: If the root private key is used to sign workload certificates (there are no intermediate certificates), include the root certificate found in `root-cert.pem`.
`ca-key.pem`	The private key that Istiod (and Citadel, if installed) uses to sign workload certificates
`cert-chain.pem`	The certificate chain of trust. Include the following: - If there are intermediate certificates: All intermediate certificates between the workload certificates and the root certificate. Note: Include the certificate found in `ca-cert.pem` (the issuing certificate). Do not include the root certificate found in `root-cert.pem`. - If there are no intermediate certificates: Nothing. This file must be empty.
`root-cert.pem`	The root certificate (that is, the trust anchor of the certificate found in `ca-cert.pem`)

Note

You may not use different filenames.
The type of each credential file can be either Rivest–Shamir–Adleman (RSA) or elliptic-curve cryptography (ECC).
Regardless of the types of the credential files, Istiod creates RSA workload certificates unless you enable ECC workload certificates for Istiod.
Citadel creates workload certificates whose type matches that of ca-cert.pem.

Plug in CA certificates and re-create workload certificates#

Plug in CA certificates#

In a terminal window on your computer, create a directory to hold the required CA credential files.
Change to the directory you created.
If the required CA credential files don’t already exist, create them.
If the istio-system namespace doesn’t exist, create it:
```
$ kubectl create namespace istio-system
```

Use the required CA credential files to create a Kubernetes secret named cacerts in the istio-system namespace:

$ kubectl create secret generic cacerts --namespace istio-system \
    --from-file=ca-cert.pem \
    --from-file=ca-key.pem \
    --from-file=root-cert.pem \
    --from-file=cert-chain.pem

Is Aspen Mesh already installed?

Note

Answer no if you were directed to this page while performing a clean installation of Aspen Mesh.
- Yes:
  - Go to step 7.
- No:
  - Stop. Continue performing the clean installation of Aspen Mesh.

Restart the Istiod pods:

$ kubectl rollout restart deployment istiod --namespace istio-system

If Citadel is installed, restart the Citadel pods:

$ kubectl rollout restart deployment istio-citadel --namespace istio-system

Log in to the appropriate artifact registry with Helm and set the repository address#

Re-create all workload certificates managed by Istiod and Citadel#

In each namespace in which sidecar injection (either automatic or manual) is being used, restart all pods with sidecars:
```
$ kubectl delete pods --namespace <namespaceName> \
    --selector security.istio.io/tlsMode=istio
```
If Citadel is installed, restart all off-mesh, on-cluster pods that are configured to use a service account’s Citadel workload certificate:

Example
```
$ kubectl rollout restart deployment <deploymentName> --namespace <namespaceName>
```
Set the AM_TAG environment variable to the version of Aspen Mesh that’s installed.

Example
```
$ export AM_TAG=1.21.6-am1
```

Reconfigure the Istio ingress gateway:

Kubernetes

$ helm upgrade istio-ingress oci://$AM_REPO/charts/gateways/istio-ingress --version $AM_TAG \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --wait

OpenShift

$ helm upgrade istio-ingress oci://$AM_REPO/charts/gateways/istio-ingress --version $AM_TAG \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

If you’re using the Istio egress gateway, reconfigure the Istio egress gateway:

Kubernetes

$ helm upgrade istio-egress oci://$AM_REPO/charts/gateways/istio-egress --version $AM_TAG \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml

OpenShift

$ helm upgrade istio-egress oci://$AM_REPO/charts/gateways/istio-egress --version $AM_TAG \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait