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 and authenticate it using workload identity federation

Connecting a cluster and authenticating it using workload identity federation involves five steps:

  1. Create a Helm values file.
  2. Install Venafi Kubernetes Agent using the Venafi CLI tool
  3. Obtaining the OIDC Issuer URL and JWKS URI.
  4. Creating a service account in the Venafi Control Plane UI.
  5. Configuring Kubernetes resources.

Step 1: Create a values file

First, create a venafi-kubernetes-agent.values.yaml to define Helm values for the Venafi Connection to Venafi Control Plane:

venafi-kubernetes-agent.values.yaml
config:
  clusterName: "replace-with-your-cluster-name"
  clusterDescription: "replace-with-your-cluster-description"
authentication:
  venafiConnection:
    enabled: true

Step 2: Install Venafi Kubernetes Agent

  1. If not already installed, download and install the relevant version of the Venafi CLI tool for your platform.

  2. Initialize the Venafi Kubernetes Manifest tool:

    venctl components kubernetes manifest tool init

    For more information on this command and its associated flags, see the venctl reference page.

  3. Install the latest version of Venafi Kubernetes Agent:

    venctl components kubernetes manifest generate \
  --venafi-kubernetes-agent \
  --venafi-kubernetes-agent-values-files venafi-kubernetes-agent.values.yaml > venafi-agent.yaml

venctl components kubernetes manifest tool sync \
  --file venafi-agent.yaml

Step 3: Obtaining the OIDC Issuer URL and JWKS URI

Before creating a service account in Venafi Control Plane, you must complete the following tasks on your Kubernetes cluster.

  1. Obtain the OIDC Issuer URL: To get the OIDC Issuer URL, run the command below

    kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'

  2. Obtain the OIDC JWKS URI: To get the OIDC JWKS URI, run the command below

    ISSUER_URL=$(kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer')
curl -fsSL "${ISSUER_URL}/.well-known/openid-configuration" | jq -r '.jwks_uri

    IMPORTANT!

    The JWKS URI must be a publicly accessible HTTPS endpoint, without authentication. This allows Venafi Control Plane to retrieve authentication information. If the JWKS URI isn't publicly accessible or if it is protected, you must establish an alternative location that is kept in constant synchronization with the original JWKS URI of your cluster.

    For example, on a Google GKE cluster, the public JWKS URI can be found in the public discovery document rather than the in-cluster discovery document:

    https://container.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/clusters/${CLUSTER_NAME}/.well-known/openid-configuration. Learn more

Step 4: Creating a service account in the Venafi Control Plane UI

Warning

When registering clusters with Venafi Control Plane, ensure that only one instance of the Venafi Kubernetes Agent is deployed per cluster. 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. Select the Kubernetes Agent radio button in the Use Case list, and click Continue.

  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. Enter the Validity period in days for the service account.

  8. Select Kubernetes Discovery for the Scope if not already selected.

  9. Select Workload Identity Federation as the authentication method, and then click Continue.

  10. Fill in the credentials with the specific information required for authentication, and then click Finish:

    • Issuer URL: Enter the OIDC Issuer URL of the cluster obtained in the previous section.

      • Example: https://kubernetes.default.svc

    • JWKS URI: Enter the OIDC JWKS URI of the cluster or the public location where the JSON Web Key Set (JWKS) data is replicated.

      • Example: https://www.example.com:6443/.well-known/jwks.json

    • Subject Identifier: Enter the unique identifier for the subject within the issuing authority's namespace. Kubernetes uses the format system:serviceaccount:<NAMESPACE>:<SERVICE ACCOUNT NAME> for the Subject Identifier field.

      • Example: system:serviceaccount:venafi:venafi-components

    • Audience: Enter the intended audience for the token, which is usually the API or resource that the token is intended to access.

      • Examples: https://api.venafi.cloud or https://api.venafi.eu

  11. Create the venafi namespace in your cluster:

    kubectl create namespace venafi

  12. Retrieve your tenant ID in the Venafi Control Plane UI by navigating to Settings > Licensing. Your Tenant ID will be displayed under Account information on the Licensing page.

    Tenant ID

  13. Create a Venafi Connection resource in YAML. For example:

    apiVersion: jetstack.io/v1alpha1
kind: VenafiConnection
metadata:
  name: venafi-components
  namespace: venafi
spec:
  vcp:
    url: https://api.venafi.cloud
    accessToken:
    - serviceAccountToken:
        name: venafi-components
        audiences: ["https://api.venafi.cloud"]
    - vcpOAuth:
        tenantID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # (1)!
    1. Add the tenant ID here that you retrieved in the previous step.
    apiVersion: jetstack.io/v1alpha1
kind: VenafiConnection
metadata:
  name: venafi-components
  namespace: venafi
spec:
  vcp:
    url: https://api.venafi.eu
    accessToken:
    - serviceAccountToken:
        name: venafi-components
        audiences: ["https://api.venafi.eu"]
    - vcpOAuth:
        tenantID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # (1)!
    1. Add the tenant ID here that you retrieved in the previous step.

Step 5: Configuring Kubernetes resources

  1. Create a Kubernetes service account that the Venafi Connection can use to authenticate to Venafi Control Plane.

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: venafi-components
  namespace: venafi

  2. Give the Venafi Connection the permission to acquire tokens for this service account:

    1. Create a role that allows the creation of service account tokens for venafi-components:

      apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: venafi-components-create-token
  namespace: venafi
rules:
- apiGroups: [ "" ]
  resources: [ "serviceaccounts/token" ]
  verbs: [ "create" ]
  resourceNames: [ "venafi-components" ]

    2. Link the Venafi Connection service account (which is used by Venafi Kubernetes Agent for authentication) to the venafi-components-create-token role:

      apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: venafi-components-create-token
  namespace: venafi
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: venafi-components-create-token
subjects:
- kind: ServiceAccount
  name: venafi-connection
  namespace: venafi

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_KUBERNETES_AGENT_CLUSTER_NAME=<my-cluster-name>

export VENAFI_KUBERNETES_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 if you want to add a cluster description. This step optional and can be omitted if you do not want to add a cluster description:

      config:
  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. A values file is required if you are using a custom CA bundle:

        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

venctl components kubernetes manifest tool sync \
  --file venafi-agent.yaml

      Note

      You can omit the --venafi-kubernetes-agent-values-files venafi-kubernetes-agent.values.yaml flag here if you don't require a cluster description as shown above.

    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_KUBERNETES_AGENT_CLUSTER_NAME=<my-cluster-name>

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:
  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. A values file is required if you are using a custom CA bundle:

        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

venctl components kubernetes manifest tool sync \
  --file venafi-agent.yaml

      Note

      You can omit the --venafi-kubernetes-agent-values-files venafi-kubernetes-agent.values.yaml flag here if you don't require a cluster description as shown above.

    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_KUBERNETES_AGENT_CLUSTER_NAME=<my-cluster-name>

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:
  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. A values file is required if you are using a custom CA bundle:

        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

venctl components kubernetes manifest tool sync \
  --file venafi-agent.yaml

      Note

      You can omit the --venafi-kubernetes-agent-values-files venafi-kubernetes-agent.values.yaml flag here if you don't require a cluster description as shown above.

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