Skip to content

Connecting 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

To connect a cluster using a Helm chart

  1. Create a service account using the Venafi Control Plane UI or the Venafi CLI tool:

    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.

    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 image.repository="myregistry.example.com/venafi-agent/venafi-agent" \
  --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 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