Installing Istio CSR using the Venafi CLI tool¶

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¶

1. 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.

   Venafi RegistryOwn Registry

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

   Regional registries

   The example above uses the Venafi US registry address. If you want to use a different Venafi registry replace --region us with the relevant regional repository value:

   • EU registry - --region eu
   • UK registry - --region uk
   • Australian registry - --region au

   For more information on Venafi OCI registries, see Configuring access to a Venafi OCI Registry.

   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
   

2. 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: Verify the installation¶

1. Verify whether Istio CSR is successfully installed by running the following command:

   kubectl get venafiinstall,pods --namespace venafi
   

   Sample output:

   NAME                                                   STATUS   LAST SYNC
   venafiinstall.installer.venafi.com/venafi-components   Synced   2m14s
   
   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: 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.

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

Step 6: Install Istio¶

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

2. Copy and save the following sample manifest as istio-install-config.yaml. This manifest creates an istio-system namespace and configures the install:

   istio-install-config.yaml

   apiVersion: install.istio.io/v1alpha1
   kind: IstioOperator
   metadata:
     namespace: istio-system
   spec:
     profile: cert-manager-istio-csr #  (1)!
     hub: gcr.io/istio-release
     meshConfig:
       # Change the following line to configure the trust domain of the Istio cluster.
       trustDomain: cluster.local #  (2)!
     values:
       global:
         # The address of the Istio CSR gRPC server
         caAddress: cert-manager-istio-csr.venafi.svc:443
     components:
       pilot:
         k8s:
           env:
             # Disable istiod CA Sever functionality
           - name: ENABLE_CA_SERVER
             value: "false"
   

   1. Read more about Installation Configuration Profiles.
   2. Use the same Istio trust domain as you used for Istio CSR in the previous step.

3. Use the istioctl install command to install Istio and apply the manifest:

   istioctl install \
       --set components.cni.enabled=true \
       --set components.cni.namespace=kube-system \
       --set values.global.platform=openshift \
       -f istio-install-config.yaml
   

Step 7: Verify that Istio is working¶

1. Verify that your Pods have the istio-proxy sidecar container and that it is using Istio CSR as CA. For example, to check the "details" Pod in the bookinfo sample application:

   kubectl logs deploy/details-v1 istio-proxy -n bookinfo
   

   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
   ...
   

2. Inspect the certificate being used in memory by istio-proxy. This one liner should return you the certificate being used:

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