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 using the Venafi CLI tool in two 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.

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

    venctl installation cluster connect --name "replace-with-your-cluster-name" --helm-chart-repository oci://myregistry.example.com/charts --image-registry myregistry.example.com/venafi-agent --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.
--image-pull-secret string The name of the Kubernetes image pull secret to use if the agent's image is hosted in a protected registry.

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:

      Warning

      When registering clusters with Venafi Control Plane, ensure that only one instance of the Venafi Kubernetes Agent is deployed. Additionally, each instance of the Venafi Kubernetes Agent must use a dedicated Venafi Control Plane service account. This practice allows Venafi Control Plane to accurately identify connected clusters. Using the same service account across multiple clusters is not supported.

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

      Using a custom CA bundle

      1. If you want to employ a custom CA bundle, use kubectl to add it to a ConfigMap:

        kubectl --namespace venafi create configmap ca-cert --from-file=ca-cert=<file-name>

      2. Configure the volumes and volumeMounts in the venafi-kubernetes-agent.values.yaml file:

        venafi-kubernetes-agent.values.yaml
        ...

volumes:
  - name: ca-cert
    configMap:
      name: ca-cert
volumeMounts:
  - name: ca-cert
    mountPath: /etc/ssl/certs/ca-cert.crt
    subPath: ca-cert.crt
    readOnly: true

        Note that this functionality is only available in release 0.1.49 or later.

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

      Warning

      When registering clusters with Venafi Control Plane, ensure that only one instance of the Venafi Kubernetes Agent is deployed. Additionally, each instance of the Venafi Kubernetes Agent must use a dedicated Venafi Control Plane service account. This practice allows Venafi Control Plane to accurately identify connected clusters. Using the same service account across multiple clusters is not supported.

      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"

      Using a custom CA bundle

      1. If you want to employ a custom CA bundle, use kubectl to add it to a ConfigMap:

        kubectl --namespace venafi create configmap ca-cert --from-file=ca-cert=<file-name>

      2. Configure the volumes and volumeMounts in the venafi-kubernetes-agent.values.yaml file:

        venafi-kubernetes-agent.values.yaml
        ...

volumes:
  - name: ca-cert
    configMap:
      name: ca-cert
volumeMounts:
  - name: ca-cert
    mountPath: /etc/ssl/certs/ca-cert.crt
    subPath: ca-cert.crt
    readOnly: true

        Note that this functionality is only available in release 0.1.49 or later.

    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 \
  --region eu > 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:

      Warning

      When registering clusters with Venafi Control Plane, ensure that only one instance of the Venafi Kubernetes Agent is deployed. Additionally, each instance of the Venafi Kubernetes Agent must use a dedicated Venafi Control Plane service account. This practice allows Venafi Control Plane to accurately identify connected clusters. Using the same service account across multiple clusters is not supported.

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

      Using a custom CA bundle

      1. If you want to employ a custom CA bundle, use kubectl to add it to a ConfigMap:

        kubectl --namespace venafi create configmap ca-cert --from-file=ca-cert=<file-name>

      2. Configure the volumes and volumeMounts in the venafi-kubernetes-agent.values.yaml file:

        venafi-kubernetes-agent.values.yaml
        ...

volumes:
  - name: ca-cert
    configMap:
      name: ca-cert
volumeMounts:
  - name: ca-cert
    mountPath: /etc/ssl/certs/ca-cert.crt
    subPath: ca-cert.crt
    readOnly: true

        Note that this functionality is only available in release 0.1.49 or later.

    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://myregistry.example.com/charts \
  --venafi-kubernetes-agent-custom-image-registry myregistry.example.com/venafi-agent > 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.

Using a proxy server

Some Kubernetes clusters are configured to only allow Internet connections via a 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 you are installing Venafi Kubernetes Agent using the venctl installation cluster connect command, add an HTTPS_PROXY environment variable to the PodTemplate of the Deployment resource of the Venafi Kubernetes agent.

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