Skip to content

Installing the Venafi Kubernetes Agent

The Venafi Kubernetes Agent connects your Kubernetes or OpenShift cluster to the Venafi Control Plane. You will require a Venafi Control Plane account to connect your cluster.

To learn more, see Venafi Kubernetes Agent network requirements.

You can install the Venafi Kubernetes Agent in three ways:

  • By using the Venafi Control Plane UI, which is convenient for quick, one-off installations on a few clusters.
  • By using the Venafi CLI utility, also convenient for quick, one-off installations on a few clusters.
  • By using a Helm chart, which is recommended when you want to integrate the installation process into your CI/CD pipelines.

Important

If you use your own registry, which replicates the Venafi images, replace the address of your own registry in any of the relevant commands given on this page.

Prerequisites

You need cluster level access, including the permissions to install new components.

To install the Venafi Kubernetes Agent using the Venafi Control Plane UI

Connecting an agent to Venafi Control Plane:

  1. Sign into the Venafi Control Plane, and go to Installations > Kubernetes Clusters.
  2. Click New and follow the instructions in the Kubernetes cluster connection wizard.

For more information, see Connecting a Kubernetes cluster.

To install the Venafi Kubernetes Agent using the Venafi CLI tool

  1. Download and install the appropriate version of the Venafi CLI tool for your platform.
  2. Create the venafi namespace, and create a Kubernetes secret containing the private key of the desired service account. If you need to create a service account, see Creating a Service Account.

    kubectl create namespace venafi
    kubectl create secret generic agent-credentials \
      --namespace venafi \
      --from-file=privatekey.pem=[Replace with the path the to file of the private key of the service account]
    
  3. Open a command prompt, and enter the following command to install the latest default version of the Venafi Kubernetes Agent:

    venctl components kubernetes manifest generate --venafi-kubernetes-agent > venafi-agent.yaml
    VENAFI_KUBERNETES_AGENT_CLIENT_ID=[Replace with the Client ID of the service account] venctl components kubernetes manifest tool sync --file venafi-agent.yaml
    

For further information on installing the Venafi Kubernetes Agent using the Venafi CLI tool, see the Venafi CLI tool reference page.

To install the Venafi Kubernetes Agent using a Helm chart

Although installing the Venafi Kubernetes Agent using the Venafi CLI is handy for quick, one-off installations on a few clusters, using a Helm chart is the recommended method when you intend to integrate the installation process into your CI/CD pipelines.

The Helm chart is available from the following Venafi OCI registries:

  • oci://registry.venafi.cloud/charts/venafi-kubernetes-agent (public)
  • oci://private-registry.venafi.cloud/charts/venafi-kubernetes-agent (private, US)
  • oci://private-registry.venafi.eu/charts/venafi-kubernetes-agent (private, EU)

Note

The instructions through this section assume that you are using the public registry.

To familiarise yourself with the Helm chart, use the following commands:

helm show readme oci://registry.venafi.cloud/charts/venafi-kubernetes-agent
helm show values oci://registry.venafi.cloud/charts/venafi-kubernetes-agent
helm template oci://registry.venafi.cloud/charts/venafi-kubernetes-agent

Helm chart installation requires that you already have a Cluster record created in Venafi Control Plane.

Step 1: Create a Venafi service account

Create a new service account in the Venafi Control Plane UI. The service account is used by the Venafi Kubernetes Agent to authenticate to the Venafi Control Plane. Every Venafi Kubernetes Agent should use a unique service account. You must create the service account before installing the Helm chart.

  1. First, create an RSA key pair:

    export VENAFI_SERVICE_ACCOUNT="example-cluster"
    openssl genrsa -out ${VENAFI_SERVICE_ACCOUNT}.pem
    openssl rsa -in ${VENAFI_SERVICE_ACCOUNT}.pem -pubout --out ${VENAFI_SERVICE_ACCOUNT}.pub
    
  2. Next create a service account in Venafi Control Plane:

    1. Log into Venafi Control Plane, and click Settings > Service Accounts.

    2. Click New.

    3. Choose the desired use case from the Select the Purpose list, and click Continue. The purposes available for you to choose depend on the Venafi Control Plane components you have licenses for.
    4. Enter a Name for your new service account.
    5. Select an Owning Team. This team owns the machine you want to create the service account for.
    6. 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.
    7. The remaining steps depend on the purpose you selected earlier:
    1. Select the desired Scope, and click Continue.

      • Distributed Issuance is the default scope for Venafi Firefly.
      • Kubernetes Discovery is the default scope for Venafi Kubernetes Agent.
    2. Select one of the following key generation options as required:

      1. Click the Auto-generate a keypair and download the private key radio button, and click Create.
      2. 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.

      Or:

      1. Click the Generate your own keypair and upload the public key radio button, and click Continue.
      2. 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
    3. Click Finish to create the service account and return to the Service Accounts page.

    1. Select the desired Scope, and click Create. The following scopes are available if you have the appropriate licenses:

      • [cert-manager][cert-manager-overview]: Enterprise cert-manager Components
      • [Approver Policy Enterprise][ape-overview]: Approver Policy Enterprise Component for cert-manager
      • [Venafi Enhanced Issuer][vei-overview]: Venafi Enhanced Issuer Component for cert-manager
    2. In the Credentials section, copy and store safely the Venafi OCI registry address as well as the credential Username and Password.

      Important

      Store these authentication credentials securely as they cannot be recovered if lost. This is your only opportunity to copy these authentication credentials.

    3. Select the relevant installation option for your system:

      Note

      You must have kubectl installed on your system to complete the following steps.

      1. From the first text area, copy and run the kubectl create namespace venafi command to create the default namespace.
      2. Next, also from the first text area, copy and run the remaining code for the kubectl apply command to create a secret in Kubernetes.
      3. Copy and use the command in the second text area in this section to update the default Kubernetes service account to use the image pull secret, and enable all workloads in the namespace to use it.

      Note

      You must have the OpenShift CLI tool oc installed on your system to complete the following steps.

      1. From the first text area, copy and run the oc create namespace venafi command to create the default namespace.
      2. Next, also from the first text area, copy and run the remaining code for the oc apply command to create a secret in OpenShift.
      3. Copy and use the command in the second text area in this section to update the default OpenShift service account to use the image pull secret, and enable all workloads in the namespace to use it.
      1. Copy the generated content and save it as venafi_registry_docker_config.json.
    4. Click Finish to return to the Service Accounts page.

  3. On the row on the Service Accounts page dedicated to the service account you created, click the action menu icon icon, and then Copy Client ID. You need the client ID when you install the Helm chart.

Step 2: Deploy the chart

  1. Create a namespace and then create a secret containing the private key of the service account:

    export VENAFI_NAMESPACE="venafi"
    kubectl create namespace ${VENAFI_NAMESPACE}
    kubectl create secret generic agent-credentials \
        --namespace ${VENAFI_NAMESPACE} \
        --from-file=privatekey.pem=${VENAFI_SERVICE_ACCOUNT}.pem
    
  2. Install the chart:

    export VENAFI_CLIENT_ID="<your-client-id>"
    helm upgrade venafi-kubernetes-agent oci://registry.venafi.cloud/charts/venafi-kubernetes-agent \
    --install \
    --namespace ${VENAFI_NAMESPACE} \
    --set config.clientId="${VENAFI_CLIENT_ID}"
    --set config.clusterName="<your-cluster-name>"
    --set config.clusterDescription="<your-cluster-description>"
    
    export VENAFI_CLIENT_ID="<your-client-id>"
    helm upgrade venafi-kubernetes-agent oci://registry.venafi.cloud/charts/venafi-kubernetes-agent \
    --install \
    --namespace ${VENAFI_NAMESPACE} \
    --set config.clientId="${VENAFI_CLIENT_ID}"
    --set config.server=https://api.eu.venafi.cloud/
    --set config.clusterName="<your-cluster-name>"
    --set config.clusterDescription="<your-cluster-description>"
    

    Note

    Specifying a cluster name and cluster description automatically creates a cluster resource in Venafi Control Plane. These parameters are optional but required for successful registration in most cases.

Step 3: Verify the deployment

  1. In the Venafi Control Plane UI, click Installations > Kubernetes Clusters and verify the following for your cluster:

    • Status: Active
    • Last Check In: ... seconds ago
  2. Click Settings > Event Log, and check the following events are present for your service account:

    • Service account access token granted
    • Login succeeded

    Tip

    To trouble shoot any issues, use the following command to check the agent logs:

    ```bash
    kubectl logs -n ${VENAFI_NAMESPACE} -l app.kubernetes.io/instance=venafi-kubernetes-agent --tail -1 | grep -A 5 "Running Agent"
    ```
    You should see something similar to the following:
    
    ```bash
    2023/10/24 12:10:03 Running Agent...
    2023/10/24 12:10:03 Posting data to: https://api.venafi.cloud/
    2023/10/24 12:10:04 Data sent successfully.
    ```
    

Next steps