Installing Venafi Kubernetes Agent using the Venafi Control Plane Operator¶

Venafi Control Plane Operator for Red Hat OpenShift is designed to assist customers in installing, maintaining, and upgrading Venafi cluster components.

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

Prerequisites¶

To install Venafi Kubernetes Agent using the Venafi Control Plane Operator, you'll need to ensure you have the following:

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

Connecting a cluster using worker identity federation¶

Connecting a cluster and authenticating it using workload identity federation involves four steps:

1. Install Venafi Kubernetes Agent.
2. Obtaining the OIDC Issuer URL and JWKS URI.
3. Creating a service account in the Venafi Control Plane UI.
4. Configuring Kubernetes resources.

Step 1: Install the Venafi Kubernetes Agent¶

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

   US RegionEU RegionOwn Registry

   venafi-components.yaml

   apiVersion: installer.venafi.com/v1alpha1
   kind: VenafiInstall
   metadata:
     name: venafi-components
   spec:
     globals:
       enableDefaultApprover: false 
       imagePullSecretNames: [venafi-image-pull-secret] 
       namespace: venafi 
       useFIPSImages: false 
       vcpRegion: US 
       region: US 
     certManager: 
       install: true
       skip: false 
       version: v1.16.1
     venafiKubernetesAgent:
       install: true
       values: 
         tolerations: 
         - key: node-role.kubernetes.io/infra
           operator: Exists
           effect: NoSchedule
         - key: node-role.kubernetes.io/private
           operator: Exists
           effect: NoSchedule
         config:
           clusterName: "replace-with-your-cluster-name" # (1)!
           clusterDescription: "replace-with-your-cluster-description" # (2)!
         authentication:
           venafiConnection:
             enabled: true
       version: 1.3.0
   

   1. Friendly name for the cluster resource in Venafi Control Plane.
   2. The textual description for the cluster resource.

   venafi-components.yaml

   apiVersion: installer.venafi.com/v1alpha1
   kind: VenafiInstall
   metadata:
     name: venafi-components
   spec:
     globals:
       enableDefaultApprover: false 
       imagePullSecretNames: [venafi-image-pull-secret] 
       namespace: venafi 
       useFIPSImages: false 
       vcpRegion: EU 
       region: EU 
     venafiKubernetesAgent:
       install: true
       values: 
         tolerations: 
         - key: node-role.kubernetes.io/infra
           operator: Exists
           effect: NoSchedule
         - key: node-role.kubernetes.io/private
           operator: Exists
           effect: NoSchedule
         config:
           clusterName: "replace-with-your-cluster-name" # (1)!
           clusterDescription: "replace-with-your-cluster-description" # (2)!
         authentication:
           venafiConnection:
             enabled: true
       version: 1.3.0
   

   1. Friendly name for the cluster resource in Venafi Control Plane.
   2. The textual description for the cluster resource.

   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: false 
       imagePullSecretNames: [venafi-image-pull-secret] 
       namespace: venafi 
       useFIPSImages: false 
     certManager: 
       install: true
       skip: false 
       version: v1.16.1
     venafiKubernetesAgent:
       install: true
       values: 
         tolerations: 
         - key: node-role.kubernetes.io/infra
           operator: Exists
           effect: NoSchedule
         - key: node-role.kubernetes.io/private
           operator: Exists
           effect: NoSchedule
         config:
           clusterName: "replace-with-your-cluster-name" # (1)!
           clusterDescription: "replace-with-your-cluster-description" # (2)!
         authentication:
           venafiConnection:
             enabled: true
       version: 1.3.0
   

   1. Friendly name for the cluster resource in Venafi Control Plane.
   2. The textual description for the cluster resource.

   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 2: Obtaining the OIDC Issuer URL and JWKS URI¶

Before creating a service account in Venafi Control Plane, you must complete the following tasks on your Kubernetes cluster.

1. Obtain the OIDC Issuer URL: To get the OIDC Issuer URL, run the command below

   kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'
   

2. Obtain the OIDC JWKS URI: To get the OIDC JWKS URI, run the command below

   ISSUER_URL=$(kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer')
   curl -fsSL "${ISSUER_URL}/.well-known/openid-configuration" | jq -r '.jwks_uri
   

   IMPORTANT!

   The JWKS URI must be a publicly accessible HTTPS endpoint, without authentication. This allows Venafi Control Plane to retrieve authentication information. If the JWKS URI isn't publicly accessible or if it is protected, you must establish an alternative location that is kept in constant synchronization with the original JWKS URI of your cluster.

   For example, on a Google GKE cluster, the public JWKS URI can be found in the public discovery document rather than the in-cluster discovery document:

   https://container.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/clusters/${CLUSTER_NAME}/.well-known/openid-configuration. Learn more

Step 3: Create a service account in the Venafi Control Plane UI¶

If you haven't already done so, create a service account in the Venafi Control Plane UI and obtain the tenant ID.

1. Sign in to Venafi Control Plane.

2. Click Settings > Service Accounts.

3. Click New.

4. Select the Kubernetes Agent radio button in the Use Case list, and click Continue.

5. Enter a Name for your new service account.

6. Select an Owning Team. This team owns the machine you want to create the service account for.

7. Enter the Validity period in days for the service account.

8. Select Kubernetes Discovery for the Scope if not already selected.

9. Select Workload Identity Federation as the authentication method, and then click Continue.

10. Fill in the credentials with the specific information required for authentication, and then click Finish:

    • Issuer URL: Enter the OIDC Issuer URL of the cluster obtained in the previous section.

      • Example: https://kubernetes.default.svc

    • JWKS URI: Enter the OIDC JWKS URI of the cluster or the public location where the JSON Web Key Set (JWKS) data is replicated.

      • Example: https://www.example.com:6443/.well-known/jwks.json

    • Subject Identifier: Enter the unique identifier for the subject within the issuing authority's namespace. Kubernetes uses the format system:serviceaccount:<NAMESPACE>:<SERVICE ACCOUNT NAME> for the Subject Identifier field.

      • Example: system:serviceaccount:venafi:venafi-components

    • Audience: Enter the intended audience for the token, which is usually the API or resource that the token is intended to access.

      • Examples: https://api.venafi.cloud or https://api.venafi.eu

11. Create the venafi namespace in your cluster:

    kubectl create namespace venafi
    

12. Retrieve your tenant ID in the Venafi Control Plane UI by navigating to Settings > Licensing. Your Tenant ID will be displayed under Account information on the Licensing page.

    

13. Create a Venafi Connection resource in YAML. For example:

    US RegionEU Region

    apiVersion: jetstack.io/v1alpha1
    kind: VenafiConnection
    metadata:
      name: venafi-components
      namespace: venafi
    spec:
      vcp:
        url: https://api.venafi.cloud
        accessToken:
        - serviceAccountToken:
            name: venafi-components
            audiences: ["https://api.venafi.cloud"]
        - vcpOAuth:
            tenantID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # (1)!
    

    1. Add the tenant ID here that you retrieved in the previous step.

    apiVersion: jetstack.io/v1alpha1
    kind: VenafiConnection
    metadata:
      name: venafi-components
      namespace: venafi
    spec:
      vcp:
        url: https://api.venafi.eu
        accessToken:
        - serviceAccountToken:
            name: venafi-components
            audiences: ["https://api.venafi.eu"]
        - vcpOAuth:
            tenantID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # (1)!
    

    1. Add the tenant ID here that you retrieved in the previous step.

Step 4: Configuring Kubernetes resources¶

1. Create a Kubernetes service account that the Venafi Connection can use to authenticate to Venafi Control Plane.

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: venafi-components
     namespace: venafi
   

2. Give the Venafi Connection the permission to acquire tokens for this service account:

   1. Create a role that allows the creation of service account tokens for venafi-components:

      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        name: venafi-components-create-token
        namespace: venafi
      rules:
      - apiGroups: [ "" ]
        resources: [ "serviceaccounts/token" ]
        verbs: [ "create" ]
        resourceNames: [ "venafi-components" ]
      

   2. Link the Venafi Connection service account (which is used by Venafi Kubernetes Agent for authentication) to the venafi-components-create-token role:

      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: venafi-components-create-token
        namespace: venafi
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: venafi-components-create-token
      subjects:
      - kind: ServiceAccount
        name: venafi-connection
        namespace: venafi
      

Connecting a cluster using key pair service account authentication¶

Step 1: Configure access to the Venafi OCI registry¶

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

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

Step 2: Create a service account in the Venafi Control Plane UI¶

If you haven't already done so, create a service account in the Venafi Control Plane UI and obtain both the private key and client ID.

1. Sign in to Venafi Control Plane.

2. Click Settings > Service Accounts.

3. Click New.

4. Choose the Kubernetes Agent option from the Use case list, and click Continue.

   The use cases available for you to choose depend on which Venafi Control Plane components you have licenses for.

5. Enter a Name for your new service account.

6. Select an Owning Team. This team owns the machine you want to create the service account for.

7. (Conditional) Enter the number of days for which you want the account to remain valid in the Validity (days) field. You can select any number from 1 to 365 days. This step doesn't apply when creating a Custom API Integration service account.

8. Select the Kubernetes Discovery option from the Scope drop-down, and click Continue. Learn more

9. Select one of the following key generation options as required:

   Click the Auto-generate a keypair and download the private key radio button, and click Create.

   In the Credentials section, copy the public and private keys.

   Important

   Copy and store this private key securely as it cannot be recovered if lost. This is your only opportunity to copy this private key.

   Store the private key as a venafi-agent-private-key.pem file, so it can be later imported to the cluster.

   Or:

   Click the Generate your own keypair and upload the public key radio button, and click Continue.

   In the Credentials section, provide the public key corresponding to the private key that your service will use. For your public key to be valid, it must be in PEM format and no longer than 2000 characters. The supported key algorithms are:

   - RSA in 2048, 3072, or 4096 key lengths
   - ECDSA: P256, P384, or P521
   - EDDSA: ED25519
   

10. Click Finish to create the service account and return to the Service Accounts page.

11. In the Service Account inventory page, locate the service account you just created. At the far right side of the screen, click the more icon, then click Copy Client ID.

    Paste the client ID to a location you will be able to access later as it will be required as part of the Helm install command.

12. Create the venafi namespace, and a Kubernetes secret containing the private key of the desired service account.

    oc create namespace venafi
    

13. Import the private key you created and stored earlier in to the cluster:

    oc create secret generic agent-credentials \
      --namespace=venafi \
      --from-file=privatekey.pem=venafi-agent-private-key.pem
    

Step 3: Create and apply the manifest¶

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

   US RegionEU RegionOwn Registry

   venafi-components.yaml

   apiVersion: installer.venafi.com/v1alpha1
   kind: VenafiInstall
   metadata:
     name: venafi-components
   spec:
     globals:
       enableDefaultApprover: false 
       imagePullSecretNames: [venafi-image-pull-secret] 
       namespace: venafi 
       useFIPSImages: false 
       vcpRegion: US 
       region: US 
     certManager: 
       install: true
       skip: false 
       version: v1.16.1
     venafiKubernetesAgent:
       install: true
       clientID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
       values: 
         securityContext:
           runAsUser: xxxxxxxxxx
         tolerations: 
         - key: node-role.kubernetes.io/infra
           operator: Exists
           effect: NoSchedule
         - key: node-role.kubernetes.io/private
           operator: Exists
           effect: NoSchedule
       version: 1.3.0
   

   venafi-components.yaml

   apiVersion: installer.venafi.com/v1alpha1
   kind: VenafiInstall
   metadata:
     name: venafi-components
   spec:
     globals:
       enableDefaultApprover: false 
       imagePullSecretNames: [venafi-image-pull-secret] 
       namespace: venafi 
       useFIPSImages: false 
       vcpRegion: EU 
       region: EU 
     certManager: 
       install: true
       skip: false 
       version: v1.16.1
     venafiKubernetesAgent:
       install: true
       clientID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
       values: 
         securityContext:
           runAsUser: xxxxxxxxxx
         tolerations: 
         - key: node-role.kubernetes.io/infra
           operator: Exists
           effect: NoSchedule
         - key: node-role.kubernetes.io/private
           operator: Exists
           effect: NoSchedule
       version: 1.3.0
   

   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: false 
       imagePullSecretNames: [venafi-image-pull-secret] 
       namespace: venafi 
       useFIPSImages: false 
     certManager: 
       install: true
       skip: false 
       version: v1.16.1
     venafiKubernetesAgent:
       install: true
       clientID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
       values: 
         securityContext:
           runAsUser: xxxxxxxxxx
         tolerations: 
         - key: node-role.kubernetes.io/infra
           operator: Exists
           effect: NoSchedule
         - key: node-role.kubernetes.io/private
           operator: Exists
           effect: NoSchedule
       version: 1.3.0
   

   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 clientID field to specify the client ID of the Venafi Control Plane service account for the Venafi Kubernetes Agent. This is a required field when installing Venafi Kubernetes Agent.

   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
   

Using a proxy server¶

Some Kubernetes clusters are configured to only allow Internet connections via an HTTP(S) proxy. If that applies to you:

1. Add api.venafi.cloud to the allowed domain list of your egress proxy if you are using the US region. If you are using the EU Venafi Control Plane region, add api.venafi.eu instead.

2. If using a Helm chart to install Venafi Kubernetes Agent, you can use of the following Helm values.

   HTTP ProxyHTTPS ProxyNo Proxy

   Configures the HTTP_PROXY environment variable where a HTTP proxy is required. For example:

   http_proxy: "http://<proxy server>:<port>"
   

   Configure the HTTPS_PROXY environment variable where a HTTP proxy is required. For example:

   https_proxy: "https://<proxy server>:<port>"
   

   Configure the NO_PROXY environment variable where a HTTP proxy is required, but certain domains should be excluded. For example:

   no_proxy: 127.0.0.1,localhost,kubernetes.default.svc,kubernetes.default.svc.cluster.local
   

For more information about proxy server Helm values for Venafi Kubernetes Agent, see the Venafi Kubernetes Agent Helm values reference page.

Also, when the Venafi Kubernetes Agent requires a proxy for outbound connections, and the proxy uses a certificate issued by a private certificate authority, you can now add the certificate authority to a custom CA bundle that the agent will trust. The Helm chart supports specifying volumes and volume mounts to streamline this process. For more information, see the Venafi Kubernetes Agent Helm values reference page.

Step 4: Verify the installation¶

1. Verify whether Venafi Kubernetes Agent is successfully installed by running the following command:

   oc get venafiinstall,pods
   

   Sample output:

   NAME                                                   STATUS   LAST SYNC
   venafiinstall.installer.venafi.com/venafi-components   Synced   5h8m
   
   NAME                                           READY   STATUS    RESTARTS         AGE
   pod/cert-manager-7b67bb8b56-9tslt              1/1     Running   0                5h10m
   pod/cert-manager-cainjector-6f55988c8f-qjj94   1/1     Running   0                5h10m
   pod/cert-manager-webhook-75ddc44d97-8mmjq      1/1     Running   0                5h10m
   pod/vcp-operator-6f76c5fb67-z2cm2              1/1     Running   0                6d8h
   pod/venafi-kubernetes-agent-6cc4bc5967-2992j   1/1     Running   0                5h10m