Installing Venafi Kubernetes Agent using the Venafi Control Plane Operator¶
Venafi Control Plane Operator for Red Hat OpenShift is designed to assist customers in installing, maintaining, and upgrading Venafi cluster components.
Follow the steps below to deploy the default version of cert-manager and Venafi Kubernetes Agent using the Venafi Control Plane Operator.
Prerequisites¶
To install Venafi Kubernetes Agent using the Venafi Control Plane Operator, you'll need to ensure you have the following:
- Access to the Venafi OCI registry (or your own mirror).
- Venafi Control Plane Operator already installed on your system.
- Red Hat OpenShift CLI tool
oc
installed on your system.
Connecting a cluster using worker identity federation¶
Connecting a cluster and authenticating it using workload identity federation involves four steps:
- Install Venafi Kubernetes Agent.
- Obtaining the OIDC Issuer URL and JWKS URI.
- Creating a service account in the Venafi Control Plane UI.
- Configuring Kubernetes resources.
Step 1: Install the Venafi Kubernetes Agent¶
-
Create a manifest
venafi-components.yaml
. You can use one of the samples below as a basis:venafi-components.yamlapiVersion: installer.venafi.com/v1alpha1 kind: VenafiInstall metadata: name: venafi-components spec: globals: enableDefaultApprover: false imagePullSecretNames: [venafi-image-pull-secret] namespace: venafi useFIPSImages: false vcpRegion: US region: US certManager: install: true skip: false version: v1.16.1 venafiKubernetesAgent: install: true values: tolerations: - key: node-role.kubernetes.io/infra operator: Exists effect: NoSchedule - key: node-role.kubernetes.io/private operator: Exists effect: NoSchedule config: clusterName: "replace-with-your-cluster-name" # (1)! clusterDescription: "replace-with-your-cluster-description" # (2)! authentication: venafiConnection: enabled: true version: 1.2.0
- Friendly name for the cluster resource in Venafi Control Plane.
- The textual description for the cluster resource.
venafi-components.yamlapiVersion: installer.venafi.com/v1alpha1 kind: VenafiInstall metadata: name: venafi-components spec: globals: enableDefaultApprover: false imagePullSecretNames: [venafi-image-pull-secret] namespace: venafi useFIPSImages: false vcpRegion: EU region: EU venafiKubernetesAgent: install: true values: tolerations: - key: node-role.kubernetes.io/infra operator: Exists effect: NoSchedule - key: node-role.kubernetes.io/private operator: Exists effect: NoSchedule config: clusterName: "replace-with-your-cluster-name" # (1)! clusterDescription: "replace-with-your-cluster-description" # (2)! authentication: venafiConnection: enabled: true version: 1.2.0
- Friendly name for the cluster resource in Venafi Control Plane.
- The textual description for the cluster resource.
venafi-components.yamlapiVersion: installer.venafi.com/v1alpha1 kind: VenafiInstall metadata: name: venafi-components spec: globals: customChartRepository: oci://myregistry.example.com/charts customImageRegistry: myregistry.example.com enableDefaultApprover: false imagePullSecretNames: [venafi-image-pull-secret] namespace: venafi useFIPSImages: false certManager: install: true skip: false version: v1.16.1 venafiKubernetesAgent: install: true values: tolerations: - key: node-role.kubernetes.io/infra operator: Exists effect: NoSchedule - key: node-role.kubernetes.io/private operator: Exists effect: NoSchedule config: clusterName: "replace-with-your-cluster-name" # (1)! clusterDescription: "replace-with-your-cluster-description" # (2)! authentication: venafiConnection: enabled: true version: 1.2.0
- Friendly name for the cluster resource in Venafi Control Plane.
- The textual description for the cluster resource.
Tip
For a complete list of Venafi Control Plane Operator configuration parameters, refer to the Venafi Control Plane Operator API reference.
-
Apply the manifest by running the following command:
oc apply -f venafi-components.yaml
Step 2: 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.
-
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'
-
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 3: Create a service account in the Venafi Control Plane UI¶
If you haven't already done so, create a service account in the Venafi Control Plane UI and obtain the tenant ID.
- Sign in to Venafi Control Plane.
-
Click Settings > Service Accounts.
-
Click New.
-
Select the Kubernetes Agent radio button in the Use Case list, and click Continue.
-
Enter a Name for your new service account.
-
Select an Owning Team. This team owns the machine you want to create the service account for.
-
Enter the Validity period in days for the service account.
-
Select Kubernetes Discovery for the Scope if not already selected.
-
Select Workload Identity Federation as the authentication method, and then click Continue.
-
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
- Example:
-
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
- Example:
-
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
- Example:
-
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
orhttps://api.venafi.eu
- Examples:
-
-
Create the
venafi
namespace in your cluster:kubectl create namespace venafi
-
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.
-
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)!
- 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)!
- Add the tenant ID here that you retrieved in the previous step.
Step 4: Configuring Kubernetes resources¶
-
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
-
Give the Venafi Connection the permission to acquire tokens for this service account:
-
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" ]
-
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
-
Connecting a cluster using key pair service account authentication¶
Step 1: Configure access to the Venafi OCI registry¶
Important
Follow the instructions in Configuring access to the Venafi OCI registry to enable access to the artifacts required for this component (cert-manager Components
is the default scope for cert-manager). Use venafi
as the namespace.
For the example below, it's assumed that you created the following Kubernetes Secret:
- namespace:
venafi
- name:
venafi-image-pull-secret
Step 2: Create a service account in the Venafi Control Plane UI¶
If you haven't already done so, create a service account in the Venafi Control Plane UI and obtain both the private key and client ID.
- Sign in to Venafi Control Plane.
-
Click Settings > Service Accounts.
-
Click New.
-
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.
-
Enter a Name for your new service account.
-
Select an Owning Team. This team owns the machine you want to create the service account for.
-
(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.
-
Select the Kubernetes Discovery option from the Scope drop-down, and click Continue. Learn more
-
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
-
Click Finish to create the service account and return to the Service Accounts page.
-
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 you will be able to access later as it will be required as part of the Helm install command.
-
Create the
venafi
namespace, and a Kubernetes secret containing the private key of the desired service account.oc create namespace venafi
-
Import the private key you created and stored earlier in to the cluster:
oc create secret generic agent-credentials \ --namespace=venafi \ --from-file=privatekey.pem=venafi-agent-private-key.pem
Step 3: Create and apply the manifest¶
-
Create a manifest
venafi-components.yaml
. You can use one of the samples below as a basis:venafi-components.yamlapiVersion: installer.venafi.com/v1alpha1 kind: VenafiInstall metadata: name: venafi-components spec: globals: enableDefaultApprover: false imagePullSecretNames: [venafi-image-pull-secret] namespace: venafi useFIPSImages: false vcpRegion: US region: US certManager: install: true skip: false version: v1.16.1 venafiKubernetesAgent: install: true clientID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx values: securityContext: runAsUser: xxxxxxxxxx tolerations: - key: node-role.kubernetes.io/infra operator: Exists effect: NoSchedule - key: node-role.kubernetes.io/private operator: Exists effect: NoSchedule version: 1.2.0
venafi-components.yamlapiVersion: installer.venafi.com/v1alpha1 kind: VenafiInstall metadata: name: venafi-components spec: globals: enableDefaultApprover: false imagePullSecretNames: [venafi-image-pull-secret] namespace: venafi useFIPSImages: false vcpRegion: EU region: EU certManager: install: true skip: false version: v1.16.1 venafiKubernetesAgent: install: true clientID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx values: securityContext: runAsUser: xxxxxxxxxx tolerations: - key: node-role.kubernetes.io/infra operator: Exists effect: NoSchedule - key: node-role.kubernetes.io/private operator: Exists effect: NoSchedule version: 1.2.0
venafi-components.yamlapiVersion: installer.venafi.com/v1alpha1 kind: VenafiInstall metadata: name: venafi-components spec: globals: customChartRepository: oci://myregistry.example.com/charts customImageRegistry: myregistry.example.com enableDefaultApprover: false imagePullSecretNames: [venafi-image-pull-secret] namespace: venafi useFIPSImages: false certManager: install: true skip: false version: v1.16.1 venafiKubernetesAgent: install: true clientID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx values: securityContext: runAsUser: xxxxxxxxxx tolerations: - key: node-role.kubernetes.io/infra operator: Exists effect: NoSchedule - key: node-role.kubernetes.io/private operator: Exists effect: NoSchedule version: 1.2.0
Notes
Set the
spec.certManager.skip
parameter totrue
and thespec.certManager.install
parameter tofalse
if you have already installed and configured cert-manager.Use the
clientID
field to specify the client ID of the Venafi Control Plane service account for the Venafi Kubernetes Agent. This is a required field when installing Venafi Kubernetes Agent.Tip
For a complete list of Venafi Control Plane Operator configuration parameters, refer to the Venafi Control Plane Operator API reference.
-
Apply the manifest by running the following command:
oc apply -f venafi-components.yaml
Using a proxy server¶
Some Kubernetes clusters are configured to only allow Internet connections via an 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 using a Helm chart to install Venafi Kubernetes Agent, you can use of the following Helm values.
Configures the HTTP_PROXY environment variable where a HTTP proxy is required. For example:
http_proxy: "http://<proxy server>:<port>"
Configure the HTTPS_PROXY environment variable where a HTTP proxy is required. For example:
https_proxy: "https://<proxy server>:<port>"
Configure the NO_PROXY environment variable where a HTTP proxy is required, but certain domains should be excluded. For example:
no_proxy: 127.0.0.1,localhost,kubernetes.default.svc,kubernetes.default.svc.cluster.local
For more information about proxy server Helm values for Venafi Kubernetes Agent, see the Venafi Kubernetes Agent Helm values reference page.
Also, when the Venafi Kubernetes Agent requires a proxy for outbound connections, and the proxy uses a certificate issued by a private certificate authority, you can now add the certificate authority to a custom CA bundle that the agent will trust. The Helm chart supports specifying volumes and volume mounts to streamline this process. For more information, see the Venafi Kubernetes Agent Helm values reference page.
Step 4: Verify the installation¶
-
Verify whether Venafi Kubernetes Agent is successfully installed by running the following command:
oc get venafiinstall,pods
Sample output:
NAME STATUS LAST SYNC venafiinstall.installer.venafi.com/venafi-components Synced 5h8m NAME READY STATUS RESTARTS AGE pod/cert-manager-7b67bb8b56-9tslt 1/1 Running 0 5h10m pod/cert-manager-cainjector-6f55988c8f-qjj94 1/1 Running 0 5h10m pod/cert-manager-webhook-75ddc44d97-8mmjq 1/1 Running 0 5h10m pod/vcp-operator-6f76c5fb67-z2cm2 1/1 Running 0 6d8h pod/venafi-kubernetes-agent-6cc4bc5967-2992j 1/1 Running 0 5h10m