Istio

Follow these steps to get certificates from DigiCert® Trust Lifecycle Manager for Istio's mutual TLS (mTLS) authentication feature, using the cert-manager utility and ACMEv2 protocol.

Before you begin

Certificate profile

In DigiCert® Trust Lifecycle Manager, use the following base template to create a certificate profile for issuing mTLS certificates for the service mesh via ACME.

Template name	Trust type	Issuing CA	Seat type	Enrollment method
`CA Manager Private mTLS Certificate`	Private	DigiCert® CA Manager	Server	mTLS over ACME

The profile defines the general certificate properties and provides the required ACME URL and external account binding (EAB) credentials:

ACME Directory URL: The ACME server URL to request certificates from Trust Lifecycle Manager.
Key identifier (KID): Identifies the certificate profile in your Trust Lifecycle Manager account.
HMAC key: Used to encrypt and authenticate your account key during certificate requests.

Root CA certificate

In DigiCert® CA Manager, download the root CA certificate for the issuing CA selected in the Trust Lifecycle Manager certificate profile. You will use this root CA certificate to establish trust in the service mesh environment.

Open the managers menu in the top-right area of DigiCert ONE and select CA.
Select Manage CAs > Roots from the CA Services menu. Locate the root of the issuing CA for the Trust Lifecycle Manager certificate profile.
Hover the name of the root CA, open the actions (three dots) menu for it, and select the option to Download certificate .pem.

cert-manager

On the Istio end, set up the cert-manager utility to get certificates from Trust Lifecycle Manager via its ACME service.

Use the following command to install cert-manager in your service mesh environment.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.yaml

Create the namespace used by Istio. By default this is istio-system.
```
kubectl create namespace istio-system 
```
Use the following command to create a Kubernetes secret for DigiCert ACME external account binding (EAB).
```
kubectl create secret generic <eab_secret_name> --from-literal secret=<eab_hmac> -n <namespace>
```
Supply a name for the secret in the eab_secret_name parameter. For the eab_hmac parameter, supply the HMAC key for your certificate profile in Trust Lifecycle Manager. For the namespace parameter, supply the Istio namespace name (istio-system). For example:
```
kubectl create secret generic digicert_acme --from-literal secret=MWJiMjQ5MDQ5YWUzOTFiN2JlOWNmODBmNDY2NWNhM2U2MTgyYzI2ZDMxZDNhNmJmNzliZTZlNzE5MzIxODk1Yg -n istio-system
```

Integration workflow

Step 1: Download the integration package

Download the Istio integration package to get the following sample file to help set up the integration:

sample-issuer.yaml: Sample configuration file to add an ACME-based issuer in cert-manager.

Note

The downloadable sample file is also available from the Integrations > Connectors page in Trust Lifecycle Manager by selecting Add connector > Infrastructure automation > Istio.

Step 2: Add the ACME-based issuer in cert-manager

Use the sample file to enable DigiCert ACME issuance in the service mesh environment:

Update the sample-issuer.yaml file to supply values for the following parameters:
- metadata section:
  - name: ACME-based issuer name.
  - namespace: Istio namespace name.
- spec > acme section:
  - email: Email address of the technical contact for issued certificates.
  - server: ACME Directory URL for the target certificate profile in Trust Lifecycle Manager.
  - externalAccountBinding > keyID: ACME EAB key identifier (KID) for the target certificate profile.
  - externalAccountBinding > keySecretRef > name: Name of the Kubernetes secret for DigiCert ACME external account binding (EAB).
  - externalAccountBinding > privateKeySecretRef > name: Kubernetes secret name to use for storing the private key for DigiCert ACME EAB.
Run the following command and wait for the ACME account to be created. If you renamed the sample issuer configuration file, supply the new name as the final argument.
```
kubectl apply -f sample-issuer.yaml
```
Use the following command to verify the ACME account has been registered to the DigiCert ACME server.
```
kubectl describe issuer <issuer_name> -n <namespace>
```
Supply the issuer name you configured in the sample-issuer.yaml file and the Istio namespace name (istio-system). For example:
```
kubectl describe issuer digicert-acme-issuer -n istio-system 
```

Step 3: Install istio-csr and Istio

Set up istio-csr and Istio to get certificates in the service mesh via the ACME-based issuer in cert-manager.

For this part, refer to the official istio-csr installation guide for more details.

Warning

These steps require Helm and must be completed in the given order. The istio-csr utility must be installed before installing Istio. If Istio is already installed, uninstall it first.

Use the root CA certificate downloaded from DigiCert® CA Manager to create a Kubernetes secret. This establishes trust for the issued certificates within the service mesh.
For example, if the root CA certificate downloaded from DigiCert is named ca.pem:
```
kubectl create secret generic -n cert-manager istio-root-ca --from-file=ca.pem=ca.pem
```
For more details, refer to step 4 in the istio-csr installation guide.
If it's not already present, add the Jetstack repository to Helm to get the cert-manager charts:
```
helm repo add jetstack https://charts.jetstack.io
```
After adding Jetstack, update the Helm chart repository cache:
```
 helm repo update
```

Install istio-csr via Helm, with the following parameters. Supply the name of the ACME-based issuer in cert-manager for the ACME_issuer_name parameter. The app.tls.rootCAFile variable specifies the complete path to the root CA certificate from the Kubernetes secret in the first step above.

helm install -n cert-manager cert-manager-istio-csr jetstack/cert-manager-istio-csr \
	--set "app.certmanager.issuer.name=<ACME_issuer_name>" \
	--set "app.tls.rootCAFile=/var/run/secrets/istio-csr/ca.pem" \
	--set "volumeMounts[0].name=root-ca" \
	--set "volumeMounts[0].mountPath=/var/run/secrets/istio-csr" \
	--set "volumes[0].name=root-ca" \
	--set "volumes[0].secret.secretName=istio-root-ca"

For more details, refer to step 5 in the istio-csr installation guide.

Install Istio. For example, to install Istio using the istioctl utility:

Download the Istio deployment manifest:

curl -sSL https://raw.githubusercontent.com/cert-manager/website/7f5b2be9dd67831574b9bde2407bed4a920b691c/content/docs/tutorials/istio-csr/example/istio-config-getting-started.yaml > istio-install-config.yaml

Install the manifest:

istioctl install -f istio-install-config.yaml

For more details, refer to the Istio getting started guide or step 6 in the istio-csr installation guide.

Additional requirements

Istio automatically requests mutual TLS (mTLS) certificates from DigiCert under the following conditions:

Istio injection: The pod must be running in a namespace with Istio injection enabled, or the pod must have an annotation sidecar.istio.io/inject: "true" to explicitly enable Istio injection.
Service registration: The pod must be registered as a service in the Istio service registry. This typically involves creating a Kubernetes Service resource that selects the pod.
Destination rule: There must be a destination rule that specifies the TLS settings for the service. Istio provides a default destination rule that enables mTLS for all services.
Pod identity: The pod must have a valid identity, which is used to generate the certificate. This identity is typically derived from the pod's service account and namespace.
Certificate authority (CA): Istio must be configured with a CA that can issue certificates. By default, Istio uses a built-in CA.

Certificate lifecycle events

When an mTLS certificate is needed for client or server authentication in the Istio service mesh:

The Istio daemon (istiod) generates the CSR.
The istio-csr utility picks up the CSR and creates a CertificateRequest resource for cert-manager.
cert-manager sends the request to the DigiCert ACME service and downloads the resulting certificate from Trust Lifecycle Manager.
The istio-csr utility returns the issued certificate to the Istio daemon, which distributes it into the service mesh.

You can run the following command at any time to see detailed status information about all certificate resources in Kubernetes. Supply the Istio namespace name (istio-system) as the final argument.

kubectl describe certificate -n <namespace>

The certificates also appear in the Trust Lifecycle Manager Inventory view so you can monitor them and set up notifications.