Perform a clean installation#

Overview#

Introduction#

The following instructions describe how to perform a clean installation of Citadel.

If you want to perform an upgrade instead, see Perform an upgrade.

Note

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

When to install Citadel#

Install Citadel when any of the following is true:

  • You require an encrypted (TLS or mTLS) connection between one off-mesh, on-cluster non-gateway workload (for example, the Packet Inspector 1 aggregator service) and another (for example, the analysis service).

  • You require an encrypted (TLS or mTLS) connection between an off-mesh, on-cluster non-gateway workload (for example, the Packet Inspector 1 aggregator service) and an on-mesh non-gateway workload.

  • You require an encrypted (TLS or mTLS) connection between an off-mesh, on-cluster non-gateway workload and an Istio gateway.

  • You require an encrypted (TLS or mTLS) connection between an off-mesh, off-cluster workload and an Istio gateway.

Prepare to install#

Before you begin#

  • Make sure Aspen Mesh is installed.

Plug in CA certificates#

Why you must plug in CA certificates#

There are two reasons you must plug in CA certificates:

  • Citadel (if installed) won’t start if you don’t plug in CA certificates.

  • For two peers to communicate over an encrypted connection, one (TLS) or both (mTLS) must trust the other’s certificate chain. Because Citadel creates certificates for off-mesh items so they can communicate with on-mesh items (whose certificates are created by Istiod), the off-mesh and on-mesh items must trust each other’s certificate chain. Plugging in CA certificates ensures that both Citadel and Istiod have the same root certificate, which means the off-mesh and on-mesh items can trust each other’s certificate chain.

Plug in CA certificates#

Enable traditional SAN names for Istiod#

Why you should enable traditional SAN names for Istiod#

Learn why you should enable traditional SAN names for Istiod.

Enable traditional SAN names for Istiod#

Install Citadel#

About Citadel configuration#

The Helm chart for Citadel includes a values.yaml file that contains fields that Helm uses to generate the manifest files during an installation or an upgrade. You can change the default value of a field by doing both of the following:

  • Include the field in the override values file for Citadel and specify a different value.

  • Specify the override values file and a namespace when installing or upgrading Citadel.

Create an override values file for Citadel#

  1. Change to the Aspen Mesh release directory.

  2. Change to the directory for Citadel:

    $ cd manifests/charts/security

  3. Create an override values file for Citadel by copying the Citadel values.yaml file to a new file (for example, citadel-override-values.yaml):

    $ cp values.yaml <citadelOverrideValuesFilename>

  4. Open the override values file for Citadel in a text editor.

  5. Read the comments for each field and comment out or remove any unrequired fields that you don’t want to override.

  6. Change the values of the remaining fields.

  7. Save and close the file.

  8. Move the override values file for Citadel to a permanent location.

    You’ll need access to this file when installing or upgrading Citadel, and you should keep the file under version control.

Install Citadel#

  1. If you want to enable ECC workload certificates for Citadel, do that now. For instructions and information on when you might want to do this, see Enable ECC workload certificates.

  2. Change to the Aspen Mesh release directory.

  3. Install Citadel:

    $ helm install citadel manifests/charts/security \
    --namespace istio-system \
    --values <citadelOverrideValuesFilename> \
    --wait

    Citadel is now installed. Before a Citadel workload certificate is available for use by an off-mesh workload, you must configure the off-mesh workload to use a service account’s Citadel workload certificate.

    Before an on-mesh workload whose peer-authentication policy’s mTLS mode is PERMISSIVE can accept mTLS traffic from off-mesh, on-cluster workloads that use standard ALPN protocol IDs, you must use the HTTP ALPN annotation on the on-mesh workload.

    If you have an off-mesh application that needs to validate the identity of a pod (or pod interface) whose workload certificate is created by one of the Aspen Mesh CAs, you may want to add traditional SAN names to workload certificates.