Installing Istio CSR using the Venafi CLI tool¶

Important

Use Istio CSR with cert-manager's built-in "default" approver. For simplicitiy's sake, it's not recommended to use Istio CSR with Approver Policy or Approver Policy Enterprise, as this may introduce too many moving parts, and may make it difficult to diagnose problems and difficult to plan upgrades. Specifically, Istio generates the certificate signing requests (CSRs), and so Istio upgrades might force the need for new or updated CertificateRequestPolicy resources.

Istio CSR must be installed before Istio because Istio depends on a ConfigMap named istio-ca-root-cert which Istio CSR creates when it starts up.

Learn how to install Istio CSR using the Venafi CLI tool.

Step 1: Configure access to the Venafi OCI registry¶

Configure access to the Venafi OCI registry. Follow the instructions in Configuring access to the Venafi OCI Registry to enable access to the artifacts required for this component (cert-manager Components is the default scope for cert-manager). Use venafi as the namespace and create a Kubernetes image pull secret in the namespace as outlined.

You must create a docker-registry secret for Kubernetes to use when pulling container images in-cluster. This secret must be available in the installation namespace.

The default secret name is venafi-image-pull-secret unless you configure a different name.

Step 2: Create the Required Namespace¶

Istio CSR, by default, uses two namespaces; the installation namespace (into which Istio CSR will be installed) and the Istio namespace (where certificates will be created and Istio will be installed after Istio CSR).

By default, the installation namespace for Venafi components (including Istio CSR) is venafi. The default Istio namespace is istio-system.

While it's possible to configure the Istio namespace using the app.certmanager.namespace and app.istio.namespace Helm values, the simplest approach is to use the default.

If you haven't already, you must create the installation namespace and Istio namespace before installing Istio CSR.

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

Step 3: Generate the Venafi Kubernetes manifest¶

Issue the following command to generate a Venafi Kubernetes manifest which, when applied, will install the default versions of cert-manager and Istio CSR:

Note

These commands will install cert-manager with the default approver enabled, because Istio CSR doesn't interact well with Approver Policy currently.

US RegionEU RegionOwn Registry

venctl components kubernetes manifest generate --region us --cert-manager --istio-csr --default-approver > venafi-components.yaml

venctl components kubernetes manifest generate --region eu --cert-manager --istio-csr --default-approver > venafi-components.yaml

venctl components kubernetes manifest generate \
    --region custom \
    --cert-manager-custom-chart-repository oci://myregistry.example.com/charts \
    --cert-manager-custom-image-registry myregistry.example.com \
    --cert-manager \
    --istio-csr \
    --default-approver > venafi-components.yaml

Define a variable to be set for the trust domain, and apply the manifest using the following command. Replace example.com in the following example with your trust domain:

ISTIO_TRUST_DOMAIN=example.com venctl components kubernetes manifest tool sync --file venafi-components.yaml

Important

Istio CSR has special logic to handle health checks in this situation. Until an issuer is configured for the first time, the health checks will report as healthy so that the install will complete without hanging. Once an issuer is configured, the health checks will operate as usual.

Step 4: Configure an Issuer or ClusterIssuer¶

Istio CSR needs an issuer to be configured, which it will use to sign workload certificates as well as the serving certificate and the istiod certificate.

Note

If using a namespace-scoped issuer, it must be located in the Istio installation namespace, which by default is istio-system as used below.

A sample issuer is provided below.

# This is an example using in-cluster private PKI
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

Take note of the kind, group, and name of the issuer you want to use, so it can be passed into the runtime configuration ConfigMap that tells Istio CSR which issuer to use:

kubectl create configmap istio-csr-ca -n venafi \
    --from-literal=issuer-name=istio-ca \
    --from-literal=issuer-kind=Issuer \
    --from-literal=issuer-group=cert-manager.io

Important

Although a self-signed CA can be useful in development environments, its use is not recommended for production environments. Venafi recommends that you use Venafi Firefly in production environments.