Certificates facilitating mTLS — both inter and intra-cluster — will be signed, delivered and renewed using cert-manager issuers.
Following the guide is the best way to see istio-csr in action.
If you've already seen istio-csr in action or if you're experienced with running Istio and just want quick installation instructions, read on for more details.
⚠️ The getting started guide is a better place if you just want to try istio-csr out!
Running istio-csr requires a few steps and preconditions in order:
- A cluster without Istio already installed
- cert-manager installed in the cluster
ClusterIssuerwhich will be used to issue Istio certificates
- istio-csr installed (likely via helm)
- Istio installed with some custom config required, e.g. using the example config from the repository.
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
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).
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.
Our getting started guide uses an
Whether you choose to use an
Issuer or a
ClusterIssuer, you'll also need to choose the type of issuer you want such as:
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.
If you're already using HashiCorp Vault then the Vault issuer is an obvious choice. If you want to control your own PKI entirely, we'd recommend the CA issuer. The choice is ultimately yours.
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.
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.