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 \
  --credential-format secret \
  --credential-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"

    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 \
  --credential-format secret \
  --credential-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 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

  1. Choose your tenant's region and then follow the instructions.

    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 \
  --credential-format secret \
  --credential-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 \
  --credential-format secret \
  --credential-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.

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