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¶
- Download and install the appropriate version of the Venafi CLI tool for your platform.
- Choose your tenant's region and then follow the instructions.
-
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.
- Download and install the appropriate version of the Venafi CLI tool for your platform.
-
Choose your tenant's region and then follow the instructions.
-
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
-
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
-
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
-
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>
-
Configure the
volumes
andvolumeMounts
in thevenafi-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.
-
-
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
-
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
-
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
-
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
-
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>
-
Configure the
volumes
andvolumeMounts
in thevenafi-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.
-
-
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
-
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
-
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
-
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
-
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>
-
Configure the
volumes
andvolumeMounts
in thevenafi-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.
-
-
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:
- 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, addapi.venafi.eu
instead. - 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:
-
In the Venafi Control Plane UI, click Installations > Kubernetes Clusters and verify the following for your cluster:
- Status: Active
- Last Check In: ... seconds ago
-
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:
You should see something similar to the following:kubectl logs -n venafi -l app.kubernetes.io/instance=venafi-kubernetes-agent --tail -1 | grep -A 5 "Running Agent"
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:
- In the Venafi Control Plane UI, go to Installations > Kubernetes Clusters.
- Click the checkbox on the row assigned to your cluster, and click Disconnect.
- Next, go to Settings > Service Accounts.
- 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