Installing Istio CSR using Helm¶

In this tutorial, you'll install Istio CSR on a Kubernetes cluster using Helm. Istio CSR replaces Istio's built-in certificate authority, allowing Istio to use cert-manager to issue and manage workload certificates.

You must install Istio CSR before Istio. Istio depends on a ConfigMap named istio-ca-root-cert that Istio CSR creates when it starts.

Important

Use Istio CSR with cert-manager's built-in default approver. Using Istio CSR with Approver Policy is not recommended, as Istio generates certificate signing requests (CSRs) and Istio upgrades may require new or updated CertificateRequestPolicy resources.

Prerequisites¶

Before you install Istio CSR, make sure you have:

cert-manager already installed on your cluster.
As described in Configuring Next-Gen Trust Security registry access, private registry access through a Built-in Account with the OCI Registry Use Case and cert-manager Components Scope, using kubectl to create a pull secret.
kubectl and helm installed on your local machine.
A trust domain for Istio decided. The default is cluster.local. See Istio trust domain for details.

Step 1: Create the namespaces¶

Istio CSR uses two namespaces: the installation namespace, venafi and the Istio namespace, istio-system.

Create both namespaces if they do not already exist:

kubectl create namespace venafi || :
kubectl create namespace istio-system || :

Step 2: Configure an issuer¶

Configure an issuer for Istio CSR so that it can sign workload certificates, the serving certificate, and the istiod certificate.

If you use a namespace-scoped issuer, it must be in the istio-system namespace.

Warning

The following example uses a self-signed CA, which is useful for development environments but is not recommended for production. In production, use Distributed Issuer or another trusted CA.

Create a file named istio-ca.yaml with the following content:

istio-ca.yaml

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned
  namespace: istio-system
spec:
  selfSigned: {}

---

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: istio-ca
  namespace: istio-system
spec:
  isCA: true
  duration: 87600h # 10 years
  secretName: istio-ca
  commonName: istio-ca
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: selfsigned
    kind: Issuer
    group: cert-manager.io

---

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: istio-ca
  namespace: istio-system
spec:
  ca:
    secretName: istio-ca

---

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-csr-ca
  namespace: venafi
data:
  issuer-name: istio-ca
  issuer-kind: Issuer
  issuer-group: cert-manager.io

Apply the manifest:
```
kubectl apply -f istio-ca.yaml
```

Verify that the CA certificate has been created:

kubectl -n istio-system get certificates,issuers,secrets

Example output:

NAME                                         READY   SECRET       AGE
certificate.cert-manager.io/istio-ca         True    istio-ca     2m
certificate.cert-manager.io/istiod-dynamic   True    istiod-tls   2m

NAME                                READY   AGE
issuer.cert-manager.io/istio-ca     True    2m
issuer.cert-manager.io/selfsigned   True    2m

NAME                  TYPE                DATA   AGE
secret/istio-ca       kubernetes.io/tls   3      2m
secret/istiod-tls     kubernetes.io/tls   3      2m

Step 3: Install Istio CSR¶

Run the following command to install Istio CSR Be sure to replace cluster.local with your Istio trust domain. Use of a separate trust domain is recommended.

If you mirror images to your own registry, replace registry.ngts.paloaltonetworks.com with your registry URL in the command.
For FIPS-compliant images, append -fips to the chart name and each image path, for example oci://registry.ngts.paloaltonetworks.com/charts/cert-manager-istio-csr-fips.
The Istio CSR images are in a private registry. The imagePullSecrets value references the pull secret you created in the prerequisites.

zsh users

If using zsh, wrap arguments containing square brackets in single quotes to avoid glob errors, for example --set 'imagePullSecrets[0].name=ngts-image-pull-secret'.

helm upgrade cert-manager-istio-csr oci://registry.ngts.paloaltonetworks.com/charts/cert-manager-istio-csr \
        --install \
        --namespace venafi \
        --wait \
        --set 'imagePullSecrets[0].name=ngts-image-pull-secret' \
        --set app.tls.trustDomain=cluster.local \
        --version v0.16.0

Step 4: Verify the installation¶

Verify that Istio CSR is running:

kubectl get pods --namespace venafi

Example output:

NAME                                           READY   STATUS    RESTARTS   AGE
pod/cert-manager-586bf54fc-j72bq               1/1     Running   0          5m37s
pod/cert-manager-cainjector-555597db44-vdvrs   1/1     Running   0          5m37s
pod/cert-manager-istio-csr-76dddc799c-qnjw9    1/1     Running   0          2m36s
pod/cert-manager-webhook-6c86fd9696-5wdkp      1/1     Running   0          5m37s

Step 5: Install Istio¶

If you have not already done so, download istioctl, the Istio command-line tool.

Create a file named istio-install-config.yaml with the following content:

istio-install-config.yaml

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  namespace: istio-system
spec:
  profile: minimal # (1)!
  hub: gcr.io/istio-release
  meshConfig:
    trustDomain: cluster.local # (2)!
  values:
    global:
      caAddress: cert-manager-istio-csr.venafi.svc:443 # (3)!
  components:
    pilot:
      k8s:
        env:
        - name: ENABLE_CA_SERVER
          value: "false" # (4)!

Read more about Installation Configuration Profiles.
Use the same trust domain you specified when installing Istio CSR.
The namespace in the address must match the namespace where you installed Istio CSR.
Disables Istio's built-in CA server, since Istio CSR replaces it.

Install Istio:

istioctl install -f istio-install-config.yaml

Step 6: Verify that Istio is working¶

Verify that your pods have the istio-proxy sidecar container and that it is using Istio CSR as the CA. Replace <deployment> with a deployment in your mesh:

kubectl logs deploy/<deployment> istio-proxy

The output should contain:

...
info    CA Endpoint cert-manager-istio-csr.venafi.svc:443, provider Citadel
info    Using CA cert-manager-istio-csr.venafi.svc:443 cert with certs: var/run/secrets/istio/root-cert.pem
...

Inspect the certificate being used in memory by istio-proxy:

istioctl proxy-config secret deployment/details-v1 -o=json \
| jq -r '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' \
| base64 -d \
| openssl x509 -noout -text