Installing istio-csr

istio-csr is an agent that allows for Istio workload and control plane components to be secured using cert-manager.

Running istio-csr requires a few steps and preconditions in order:

1. A cluster without Istio already installed
2. cert-manager installed in the cluster
3. An Issuer or ClusterIssuer which will be used to issue Istio certificates
4. istio-csr installed (likely via helm)
5. Istio installed with some custom configuration required, e.g. using the example configuration from the repository.

Why Custom Istio Install Manifests?

If you take a look at the contents of the example Istio install manifests there are a few custom configuration options which are important.

Required changes include setting ENABLE_CA_SERVER to false and setting the caAddress from which Istio will request certificates; replacing the CA server is the whole point of istio-csr!

Mounting and statically specifying the root CA is also an important recommended step. Without a manually specified root CA, istio-csr defaults to trying to discover root CAs automatically which could theoretically lead to a signer hijacking attack if for example a signer's token was stolen (such as the cert-manager controller's token).

Issuer or ClusterIssuer?

Unless you know you need a ClusterIssuer we'd recommend starting with an Issuer, since it should be easier to reason about the access controls for an Issuer; they're namespaced and so naturally a little more limited in scope.

That said, if you view your entire Kubernetes cluster as being a trust domain itself, then a ClusterIssuer is the more natural fit. The best choice will depend on your specific situation.

Which Issuer Type?

Whether you choose to use an Issuer or a ClusterIssuer, you'll also need to choose the type of issuer you want such as:

• CA
• Vault
• Venafi
• or an external issuer

The key requirement is that arbitrary values can be placed into the subjectAltName (SAN) X.509 extension, since Istio places SPIFFE IDs there.

That means that the ACME issuer will not work — publicly trusted certificates such as those issued by Let's Encrypt don't allow arbitrary entries in the SAN, for very good reasons.

Installation

Upload Root CA

While it's possible to configure istio-csr such that it can automatically "discover" the root CA, this can be dangerous in some specific scenarios involving other security holes, enabling signer hijacking attacks.

If you plan to use a static root CA continue here or skip to Installing istio-csr.

Export your Root CA and configure istio-csr later using that static cert.

# Add our CA to a secret assuming your root CA is in the file ca.pem
kubectl create secret generic -n jetstack-secure istio-root-ca --from-file=ca.pem=ca.pem

Installing istio-csr

istio-csr is best installed via Helm, and it should be simple and quick to start.

helm repo add jetstack https://charts.jetstack.io
helm repo update

# Use the following helm install if you are using a static Root CA
# (recommended).
helm install -n jetstack-secure cert-manager-istio-csr jetstack/cert-manager-istio-csr \
	--set app.certmanager.issuer.name=istio-ca \
	--set app.certmanager.kind.name=Issuer \
	--set app.certmanager.group.name=cert-manager.io \
	--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"

# Use the following helm install if you are _not_ using a static Root CA.
helm install -n jetstack-secure cert-manager-istio-csr jetstack/cert-manager-istio-csr \
	--set app.certmanager.issuer.name=istio-ca \
	--set app.certmanager.kind.name=Issuer \
	--set app.certmanager.group.name=cert-manager.io \

# Check to see that the istio-csr pod is running and ready
kubectl get pods -n jetstack-secure
NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-aaaaaaaaaa-11111              1/1     Running   0          9m46s
cert-manager-cainjector-aaaaaaaaaa-22222   1/1     Running   0          9m46s
cert-manager-istio-csr-bbbbbbbbbb-00000    1/1     Running   0          63s
cert-manager-webhook-aaaaaaaaa-33333       1/1     Running   0          9m46s

Installing Istio

If you're not running on kind, you may need to do some additional setup tasks before installing Istio.

We use the istioctl CLI to install Istio, configured using a custom IstioOperator manifest.

The custom manifest does the following:

• Disables the CA server in istiod,
• Ensures that Istio workloads request certificates from istio-csr,
• Ensures that the istiod certificates and keys are mounted from the Certificate created when installing istio-csr.

First we download our demo manifest and then we apply it. You can find the correct Istio configuration for your Istio version here.

You may wish to inspect and tweak the configuration file if you know what you're doing, but this manifest should work for example purposes as-is.

If you set a custom app.tls.trustDomain when installing istio-csr via helm earlier, you'll need to ensure that value is repeated in the Istio configuration file.

This final command will install Istio; the exact command you need might vary on different platforms, and will certainly vary on OpenShift.

# This takes a little time to complete
istioctl install -f istio-install-config.yaml

# If you're on OpenShift, you need a different profile:
istioctl install --set profile=openshift -f istio-install-config.yaml

You will be prompted for input to confirm your choice of Istio profile:

This will install the Istio 1.14.1 demo profile with ["Istio core" "Istiod" "Ingress gateways" "Egress gateways"] components into the cluster. Proceed? (y/N)

Confirm your selection by entering y into the console to proceed with installation.

Installing istio-csr After Istio

This is unsupported because it's exceptionally difficult to do safely. It's likely that installing istio-csr after Istio isn't possible to do without downtime, since installing istio-csr second would require a time period where all Istio sidecars trust both the old Istio-managed CA and the new cert-manager controlled CA.

How Does istio-csr Work?

istio-csr implements the gRPC Istio certificate service which authenticates, authorizes, and signs incoming certificate signing requests from Istio workloads, routing all certificate handling through cert-manager installed in the cluster.

This seamlessly matches the behavior of istiod in a typical installation, while allowing certificate management through cert-manager.

There are also FIPS compliant Docker images available at eu.gcr.io/jetstack-secure-enterprise/istio-csr-fips and these have the same version tags as the main Docker images.

Next steps

• Image flags