Skip to content

Installing Istio CSR using the Venafi Control Plane Operator

Important

Use Istio CSR with cert-manager's built-in "default" approver. For simplicity'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.

Follow the steps below to deploy the default version of cert-manager and Istio CSR using the Venafi Control Plane Operator.

Prerequisites

To install Istio CSR using the Venafi Control Plane Operator, you'll need the following:

  • Access to the Venafi OCI registry (or your own mirror).
  • The Venafi Control Plane Operator already installed on your system.
  • The Red Hat OpenShift CLI tool oc installed on your system.

Step 1: Configure access to the Venafi OCI registry

Important

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.

For the example below, it's assumed that you created the following Kubernetes Secret:

  • namespace: venafi
  • name: venafi-image-pull-secret

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.

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

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

Step 3: Create and apply the Istio CSR manifest

Note

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

  1. Create a manifest venafi-components.yaml. You can use one of the samples below as a base:

    venafi-components.yaml
    apiVersion: installer.venafi.com/v1alpha1
kind: VenafiInstall
metadata:
  name: venafi-components
spec:
  globals: 
    enableDefaultApprover: true # Istio CSR works best with the cert-manager default approver.
    imagePullSecretNames: [venafi-image-pull-secret] 
    namespace: venafi 
    useFIPSImages: false 
    vcpRegion: US 
    region: US 
  certManager: 
    install: true
  certManagerIstioCSR:
    install: true
    trustDomain: cluster.local # (1)!
    runtimeConfigMapName: istio-csr-ca # (2)!
    version: v0.13.0
    1. Provide the name of the Istio trust domain.
    2. This is the default name of the ConfigMap from which Istio CSR loads runtime configuration. You will create this ConfigMap in the next steps, in the venafi namespace, where Istio CSR is deployed.
    venafi-components.yaml
    apiVersion: installer.venafi.com/v1alpha1
kind: VenafiInstall
metadata:
  name: venafi-components
spec:
  globals:
    enableDefaultApprover: true # Istio CSR works best with the cert-manager default approver.
    imagePullSecretNames: [venafi-image-pull-secret] 
    namespace: venafi 
    useFIPSImages: false 
    vcpRegion: EU 
    region: EU 
  certManager: 
    install: true
  certManagerIstioCSR:
    install: true
    trustDomain: cluster.local # (1)!
    runtimeConfigMapName: istio-csr-ca # (2)!
    version: v0.13.0
    1. Provide the name of the Istio trust domain.
    2. This is the default name of the ConfigMap from which Istio CSR loads runtime configuration. You will create this ConfigMap in the next steps, in the venafi namespace, where Istio CSR is deployed.
    venafi-components.yaml
    apiVersion: installer.venafi.com/v1alpha1
kind: VenafiInstall
metadata:
  name: venafi-components
spec:
  globals: 
    customChartRepository: oci://myregistry.example.com/charts
    customImageRegistry: myregistry.example.com
    enableDefaultApprover: true # Istio CSR works best with the cert-manager default approver.
    imagePullSecretNames: [venafi-image-pull-secret] 
    namespace: venafi 
    useFIPSImages: false 
  certManager: 
    install: true
  certManagerIstioCSR:
    install: true
    trustDomain: cluster.local # (1)!
    runtimeConfigMapName: istio-csr-ca # (2)!
    version: v0.13.0
    1. Provide the name of the Istio trust domain.
    2. This is the default name of the ConfigMap from which Istio CSR loads runtime configuration. You will create this ConfigMap in the next steps, in the venafi namespace, where Istio CSR is deployed.

    Notes

    Set the spec.certManager.skip parameter to true and the spec.certManager.install parameter to false if you have already installed and configured cert-manager.

    Use the trustDomain field to specify the Istio trust domain.

    Tip

    For a complete list of Venafi Control Plane Operator configuration parameters, refer to the Venafi Control Plane Operator API reference.

  2. Apply the manifest by running the following command:

    oc apply -f venafi-components.yaml

Step 4: Verify the installation

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

    oc 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
pod/vcp-operator-86c7d996d6-85km5              1/1     Running   0          8m40s

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.

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.

  1. Create a manifest istio-ca.yaml:

    istio-ca.yaml
    # 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

---

# The runtime configuration ConfigMap that tells Istio CSR which issuer to use.
# This is installed in the **venafi** namespace.
# The name must match the name given in the VenafiInstall resource earlier.
apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-csr-ca
  namespace: venafi
data:
  issuer-name: istio-ca
  issuer-kind: Issuer
  issuer-group: cert-manager.io

  2. Apply the manifest by running the following command:

    oc apply -f istio-ca.yaml

  3. Verify that the CA certificate has been created

    After applying the resources in the previous step, there will be a flurry of activity. cert-manager will create a CA key and certificate in a Secret called istio-ca. istio-csr will then create a cert-manager Certificate referencing the CA issuer, which cert-manager will reconcile and place the resulting leaf certificate in a Secret called istiod-tls. Istio CSR will use that signed certificate for its gRPC server.

    oc -n istio-system get cert-manager,configmap,secret

    You should see something like this

    NAME                                                  APPROVED   DENIED   READY   ISSUER       REQUESTOR                                   AGE
certificaterequest.cert-manager.io/istio-ca-1         True                True    selfsigned   system:serviceaccount:venafi:cert-manager   13m
certificaterequest.cert-manager.io/istiod-dynamic-1   True                True    istio-ca     system:serviceaccount:venafi:cert-manager   13m

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

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

NAME                                 DATA   AGE
configmap/istio-ca-root-cert         1      13m
configmap/kube-root-ca.crt           1      51m
configmap/openshift-service-ca.crt   1      51m

NAME                              TYPE                      DATA   AGE
secret/builder-dockercfg-b65xn    kubernetes.io/dockercfg   1      51m
secret/default-dockercfg-ds8x5    kubernetes.io/dockercfg   1      51m
secret/deployer-dockercfg-hvdgx   kubernetes.io/dockercfg   1      51m
secret/istio-ca                   kubernetes.io/tls         3      13m
secret/istiod-tls                 kubernetes.io/tls         3      13m

    Then istio-csr will create a ConfigMap called istio-ca-root-cert in every namespace. It contains the CA certificate for the gRPC server, so that when Istio is installed, Istio can connect to Istio CSR gRPC server to request workload certificates. You can see these ConfigMap resources using the following command:

    oc get configmap -l istio.io/config --all-namespaces

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.

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: demo #  (1)!
  meshConfig:
    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:

    oc 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