Skip to content

Connecting a cluster to Venafi by installing 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 connect a cluster to Venafi Control Plane in three ways:

  • By using the venctl installation cluster connect command, which is convenient for quick interactive connections of a small number of clusters.
  • By using Venafi Kubernetes Manifest. This is the recommended option when you want to integrate the connection process into your CI/CD pipelines.
  • By using a Helm chart, which is an alternative to using Venafi Kubernetes Manifest.

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 connect a cluster using the venctl installation cluster connect command

  1. Download and install the appropriate version of the Venafi CLI tool for your platform.
  2. Choose your tenant's region and then follow the instructions.
  3. Connect a cluster by executing the appropriate region-specific command:

    venctl installation cluster connect --name "replace-with-your-cluster-name" --api-key xyz
    
    venctl installation cluster connect --name "replace-with-your-cluster-name" --vcp-region eu --api-key xyz
    

Consider using the following additional flags:

Flag Type Description
--description string A textual description for the cluster resource.
--owning-team string The team set as owner of the cluster resource. The team can be passed as names or IDs.
--kubeconfig string The path to the kubeConfig file you want to use to connect to the cluster.
--kubeconfig-context string The name of the kubeConfig file context you want to use to connect to the cluster.

Tip

You can also use the venctl components kubernetes apply command to install this component on a Kubernetes cluster quickly and easily for test purposes. Note that this command is not recommended for use in production environments.

See venctl components kubernetes apply for more information on how to use the command with this component.

To connect a cluster using Venafi Kubernetes Manifest

You also need to have kubectl and jq installed for this procedure.

  1. Download and install the appropriate version of the Venafi CLI tool for your platform.
  2. Choose your tenant's region and then follow the instructions.

    1. Create a service account if you have not already done so, for example:

      venctl iam service-account agent create --name sa-agent \
        --output secret \
        --output-file agent-credentials.json \
        --api-key xyz
      
      export VENAFI_AGENT_CLIENT_ID=$(jq -r '.client_id' agent-credentials.json)
      jq -r '.private_key' agent-credentials.json > venafi-agent-private-key-secret.yaml
      

      Important

      Make sure to store the private key as venafi-agent-private-key.pem file, so it can be later imported to the cluster.

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

      kubectl create namespace venafi
      
      kubectl apply --namespace venafi -f venafi-agent-private-key-secret.yaml
      
    3. Create a file called: venafi-kubernetes-agent.values.yaml containing the following content:

      config:
        clusterName: "replace-with-your-cluster-name"
        clusterDescription: "replace-with-your-cluster-description"
      
    4. Enter the following command to install the latest default version of the Venafi Kubernetes Agent.

      venctl components kubernetes manifest generate \
        --venafi-kubernetes-agent \
        --venafi-kubernetes-agent-values-files venafi-kubernetes-agent.values.yaml \
        --venafi-kubernetes-agent-custom-chart-repository oci://registry.venafi.cloud/charts \
        --venafi-kubernetes-agent-custom-image-registry registry.venafi.cloud/venafi-agent > venafi-agent.yaml
      
      VENAFI_KUBERNETES_AGENT_CLIENT_ID=$VENAFI_AGENT_CLIENT_ID venctl components kubernetes manifest tool sync \
        --file venafi-agent.yaml
      
    1. Create a service account if you have not already done so, for example:

      venctl iam service-account agent create --name sa-agent \
        --output secret \
        --output-file agent-credentials.json \
        --vcp-region eu \
        --api-key xyz
      
      export VENAFI_AGENT_CLIENT_ID=$(jq -r '.client_id' agent-credentials.json)
      jq -r '.private_key' agent-credentials.json > venafi-agent-private-key-secret.yaml
      
    2. Create the venafi namespace, and a Kubernetes secret containing the private key of the desired service account.

      kubectl create namespace venafi
      
      kubectl apply --namespace venafi -f venafi-agent-private-key-secret.yaml
      
    3. Create a file called: venafi-kubernetes-agent.values.yaml containing the following content:

      config:
        clusterName: "replace-with-your-cluster-name"
        clusterDescription: "replace-with-your-cluster-description"
      

    4. Enter the following command to install the latest default version of the Venafi Kubernetes Agent.

      venctl components kubernetes manifest generate \
        --venafi-kubernetes-agent \
        --venafi-kubernetes-agent-values-files venafi-kubernetes-agent.values.yaml \
        --venafi-kubernetes-agent-custom-chart-repository oci://registry.venafi.cloud/charts \
        --venafi-kubernetes-agent-custom-image-registry registry.venafi.cloud/venafi-agent \
        --region eu > venafi-agent.yaml
      
      VENAFI_KUBERNETES_AGENT_CLIENT_ID=$VENAFI_AGENT_CLIENT_ID 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 connect a cluster 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 familiarize 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
  1. Create a service account using the Venafi Control Plane UI or the Venafi CLI tool:

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

      kubectl create namespace venafi
      
    13. Import the private key you created and stored earlier in to the cluster:

      kubectl create secret generic agent-credentials \
        --namespace=venafi \
        --from-file=privatekey.pem=venafi-agent-private-key.pem
      
    14. Install the Helm Chart:

      helm upgrade venafi-kubernetes-agent oci://registry.venafi.cloud/charts/venafi-kubernetes-agent \
        --install \
        --namespace "venafi" \
        --set config.clientId="replace-with-clientID" \
        --set config.clusterName="replace-with-your-cluster-name" \
        --set config.clusterDescription="replace-with-your-cluster-description"
      
      helm upgrade venafi-kubernetes-agent oci://registry.venafi.cloud/charts/venafi-kubernetes-agent \
        --install \
        --namespace "venafi" \
        --set config.clientId="replace-with-clientID" \
        --set config.server="https://api.venafi.eu/" \
        --set config.clusterName="replace-with-your-cluster-name" \
        --set config.clusterDescription="replace-with-your-cluster-description"
      

      Note

      Specifying a cluster name and cluster description automatically creates a cluster resource in Venafi Control Plane

      helm upgrade venafi-kubernetes-agent oci://myregistry.example.com/charts/venafi-kubernetes-agent \
        --install \
        --namespace "venafi" \
        --set config.clientId="replace-with-clientID" \
        --set config.clusterName="replace-with-your-cluster-name" \
        --set config.clusterDescription="replace-with-your-cluster-description"
      

      Note

      Specifying a cluster name and cluster description automatically creates a cluster resource in Venafi Control Plane.

      If your Venafi Control Plane tenant is based in Europe, update the Helm command by adding the --set config.server="https://api.venafi.eu/" value.

    1. Create a service account if you have not already done so, for example:

      You must have the Venafi CLI and jq tools installed to complete this procedure.

      venctl iam service-account agent create --name sa-agent \
        --output secret \
        --output-file agent-credentials.json \
        --api-key xyz
      
      export VENAFI_AGENT_CLIENT_ID=$(jq -r '.client_id' agent-credentials.json)
      jq -r '.private_key' agent-credentials.json > venafi-agent-private-key-secret.yaml
      
    2. Create the venafi namespace, and a Kubernetes secret containing the private key of the desired service account.

      kubectl create namespace venafi
      
      kubectl apply --namespace venafi -f venafi-agent-private-key-secret.yaml
      
    3. Install the Helm chart:

      helm upgrade venafi-kubernetes-agent oci://registry.venafi.cloud/charts/venafi-kubernetes-agent \
        --install \
        --namespace "venafi" \
        --set config.clientId="${VENAFI_AGENT_CLIENT_ID}" \
        --set config.clusterName="replace-with-your-cluster-name" \
        --set config.clusterDescription="replace-with-your-cluster-description"
      

      Note

      Specifying a cluster name and cluster description automatically creates a cluster resource in Venafi Control Plane.

    1. Create a service account if you have not already done so, for example:

      You must have the Venafi CLI and jq tools installed to complete this procedure.

      venctl iam service-account agent create --name sa-agent \
        --output secret \
        --output-file agent-credentials.json \
        --vcp-region eu \
        --api-key xyz
      
      export VENAFI_AGENT_CLIENT_ID=$(jq -r '.client_id' agent-credentials.json)
      jq -r '.private_key' agent-credentials.json > venafi-agent-private-key-secret.yaml
      
    2. Create the venafi namespace, and a Kubernetes secret containing the private key of the desired service account.

      kubectl create namespace venafi
      
      kubectl apply --namespace venafi -f venafi-agent-private-key-secret.yaml
      
    3. Install the Helm chart:

      helm upgrade venafi-kubernetes-agent oci://registry.venafi.cloud/charts/venafi-kubernetes-agent \
        --install \
        --namespace "venafi" \
        --set config.clientId="${VENAFI_AGENT_CLIENT_ID}" \
        --set config.server="https://api.venafi.eu/" \
        --set config.clusterName="replace-with-your-cluster-name" \
        --set config.clusterDescription="replace-with-your-cluster-description"
      

      Note

      Specifying a cluster name and cluster description automatically creates a cluster resource in Venafi Control Plane.

    1. Create a service account if you have not already done so, for example:

      You must have the Venafi CLI and jq tools installed to complete this procedure.

      venctl iam service-account agent create --name sa-agent \
        --output secret \
        --output-file agent-credentials.json \
        --vcp-region "set to us or eu as necessary" \
        --api-key xyz
      
      export VENAFI_AGENT_CLIENT_ID=$(jq -r '.client_id' agent-credentials.json)
      jq -r '.private_key' agent-credentials.json > venafi-agent-private-key-secret.yaml
      
    2. Create the venafi namespace, and a Kubernetes secret containing the private key of the desired service account.

      kubectl create namespace venafi
      
      kubectl apply --namespace venafi -f venafi-agent-private-key-secret.yaml
      
    3. Install the Helm chart:

      helm upgrade venafi-kubernetes-agent oci://myregistry.example.com/charts/venafi-kubernetes-agent \
        --install \
        --namespace "venafi" \
        --set config.clientId="${VENAFI_AGENT_CLIENT_ID}" \
        --set config.clusterName="replace-with-your-cluster-name" \
        --set config.clusterDescription="replace-with-your-cluster-description"
      

      Note

      Specifying a cluster name and cluster description automatically creates a cluster resource in Venafi Control Plane.

      If your Venafi Control Plane tenant is based in Europe, update the Helm command by adding the --set config.server="https://api.venafi.eu/" value.

    Using a proxy server

    Some Kubernetes clusters are configured to only allow Internet connections via an HTTP(S) proxy. If that applies to you, see proxy server considerations for more details.

Verifying the deployment

To 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 troubleshoot any issues, use the following command to check the agent logs:

    kubectl logs -n venafi -l app.kubernetes.io/instance=venafi-kubernetes-agent --tail -1 | grep -A 5 "Running Agent"
    
    You should see something similar to the following:

    2023/01/01 01:01:01 Running Agent...
    2023/01/01 01:01:02 Posting data to: https://api.venafi.cloud/ or https://api.venafi.eu/
    2023/01/01 01:01:03 Data sent successfully.
    

Disconnecting a cluster and uninstalling Venafi Kubernetes Agent

To disconnect a cluster completely from Venafi Control Plane, you must:

  • Disconnect the cluster using the Venafi Control Plane UI.
  • Uninstall the Venafi Kubernetes Agent from the cluster.

Disconnecting a cluster using the Venafi Control Plane web interface

To disconnect a cluster using the Venafi Control Plane web interface, follow the instructions below:

  1. In the Venafi Control Plane UI, go to Installations > Kubernetes Clusters.
  2. Click the checkbox on the row assigned to your cluster, and click Disconnect.
  3. Next, go to Settings > Service Accounts.
  4. Click the checkbox on the row assigned to the service account you created when installing Venafi Kubernetes Agent, and click Delete.

Uninstalling the Venafi Kubernetes Agent

To uninstall the Venafi Kubernetes Agent using kubectl, issue the following command:

kubectl delete -n venafi deployment agent

Next steps