Skip to content

Configuring access to a Venafi OCI Registry

This guide provides instructions on how to acquire access credentials and configure access to Venafi Kubernetes components via a private OCI registry. You'll learn how to access container images, Helm charts, and other artifacts, ensuring secure and streamlined operation within your Kubernetes infrastructure.

Step 1: Acquiring Venafi OCI registry credentials

The Venafi OCI (Open Container Initiative) registries store container images, Helm charts, and other artifacts, ensuring secure and streamlined operation within your Kubernetes infrastructure.

There are two types of registries: public and private.

  • Public Registries: These are deployed in all available Venafi Control Plane regions and serve from a single location: registry.venafi.cloud. Public registries hold publicly available artifacts and do not require authentication.

  • Private Registries: These registries store enterprise Venafi software and are available in region-specific locations. For example, use private-registry.venafi.cloud for the US region, and private-registry.venafi.eu for the EU region. Access to these registries requires a subscription to the Venafi Control Plane. For your convenience, the private registries also contain the public artifacts hosted by the public registries.

There are two ways to acquire credentials to access the registry:

  • Using the Venafi Control Plane UI
  • Using the Venafi CLI tool

Acquiring credentials using the Venafi Control Plane UI

Create a service account for accessing the Venafi OCI Registry and following the instructions in the service account creation wizard.

Acquiring credentials using the Venafi CLI tool

This procedure requires the jq tool to be installed.

  1. Download and install the relevant version of the Venafi CLI tool for your platform.

  2. Obtain your API key:

    1. Sign into Venafi Control Plane.
    2. Click your Account Icon on the top right of the UI, and go to Preferences > API to copy your API key.

  3. Fetch your credentials. Generate and choose the credentials' format:

    venctl iam service-accounts registry create --name "My Image Pull Secret" \
  --scopes cert-manager-components,enterprise-venafi-issuer,enterprise-approver-policy,openshift-routes \
  --output dockerconfig \
  --output-file venafi_registry_docker_config.json \
  --validity 365 \
  --api-key xyz

Note

The default credentials format is json, but you can use the --output flag to set it to secret or dockerconfig(as in the example above).

For more information see the Venafi CLI tool reference page.

Installing credentials to a namespace

  1. If it doesn't exist, create the venafi namespace:

    kubectl create ns venafi

  2. Use the credential file obtained earlier (venafi_registry_docker_config.json) to create a Kubernetes secret in the specified namespace:

    kubectl create secret docker-registry venafi-image-pull-secret --namespace venafi --from-file .dockerconfigjson=venafi_registry_docker_config.json

Note

You can use any name for the secret, this documentation uses venafi-image-pull-secret throughout for convenience.

Step 2: Configuring registry access

Once you have acquired access credentials, ensure you have the following prerequisites before you attempt to configure access to the Venafi OCI Registry:

  • Basic understanding of Kubernetes and container image registries.
  • Access to a system with kubectl. For testing, make sure that docker is also installed.
  • Administrative access to your Kubernetes or OpenShift cluster.

In this step, you'll learn how to authenticate and gain access using Docker, Kubernetes, or Helm.

Authenticating with Docker

  1. Use the username and password that were shown to you after creating the service account in the Venafi Control Plane UI. To authenticate, use the following command:

    docker login https://private-registry.venafi.cloud \
--username USERNAME

  2. Enter your password when prompted.

If you prefer to log into the Venafi EU region registry, use the following registry URL in the above command: private-registry.venafi.eu.

If you used venctl to obtain the Docker config JSON file, or if you created a service account in the Venafi Control Plane UI and downloaded the Docker config JSON file, you can extract the username and password with the following command:

docker login private-registry.venafi.cloud \
  --username $(cat venafi_registry_docker_config.json | jq '.. | select(.username?).username' -r) \
  --password $(cat venafi_registry_docker_config.json | jq '.. | select(.username?).auth | @base64d' -r | cut -d: -f2)

If you prefer to log into the Venafi EU region registry, use the following registry URL in the above command: private-registry.venafi.eu.

Authenticating with Kubernetes

If you have credentials in the form of a username and password, or in the form of a Dockerconfig file, you can use kubectl to create a secret so your Kubernetes clusters can pull images from the Venafi OCI registry:

kubectl create secret docker-registry venafi-image-pull-secret --namespace venafi \
  --docker-server=private-registry.venafi.cloud \
  --docker-username=<username> \
  --docker-password=<password>

To use the Venafi EU region registry, employ the following registry URL in the above command: private-registry.venafi.eu.

kubectl create secret generic venafi-image-pull-secret --namespace venafi \
  --type=kubernetes.io/dockerconfigjson \
  --from-file=.dockerconfigjson=venafi_registry_docker_config.json

Tip

If you previously created the secret in Kubernetes and want to display its contents, you can use the following command:

kubectl get secret venafi-image-pull-secret --namespace venafi \
  --output="jsonpath={.data.\.dockerconfigjson}" \
  | base64 --decode \
  | jq

This command produces an output similar to the following:

{
  "auths": {
    "private-registry.venafi.cloud": {
      "username": "sa-us@3bdc33de-a250-46f2-bdf9-d755970193fb",
      "auth": "c2EtdXNAYmZiYWMx...pYZFpPT2xvTDhm"
    }
  }
}

Investigating your Kubernetes secret

  1. If you want to check that your secret is correctly configured, use the following commands:

    kubectl get secret venafi-image-pull-secret --namespace venafi --output=yaml

    If you prefer to log into the Venafi EU region registry, use the following registry URL in the above command: private-registry.venafi.eu.

  2. If you used venctl to obtain the Docker config JSON file, or if you created a service account in the Venafi Control Plane UI and downloaded the Docker config file, you can use the following command:

    docker login private-registry.venafi.cloud \
  --username $(cat venafi_registry_docker_config.json | jq '.. | select(.username?).username' -r) \
  --password $(cat venafi_registry_docker_config.json | jq '.. | select(.username?).auth | @base64d' -r | cut -d: -f2)

    If you prefer to log into the Venafi EU region registry, use the following registry URL in the above command: private-registry.venafi.eu.

Authenticating with Helm

Helm and Docker share the same authentication. If you want to authenticate with Helm to install charts from the Venafi OCI registry, use the following command:

docker login https://private-registry.venafi.cloud \
  --username USERNAME

Use the username and password provided when creating the service account in the Venafi Control Plane UI. If you prefer to log into the Venafi EU region registry, use the following registry URL in the above command: private-registry.venafi.eu.

If you used venctl to obtain the Docker config JSON file, or if you created a service account in the Venafi Control Plane UI and downloaded the Docker config JSON file, you can extract the username and password with the following command:

docker login private-registry.venafi.cloud \
  --username $(cat venafi_registry_docker_config.json | jq '.. | select(.username?).username' -r) \
  --password $(cat venafi_registry_docker_config.json | jq '.. | select(.username?).auth | @base64d' -r | cut -d: -f2)

If you prefer to log into the Venafi EU region registry, use the following registry URL in the above command: private-registry.venafi.eu.

Alternatively, you can use the --registry-config flag:

helm template cert-discovery-venafi \
  oci://private-registry.venafi.cloud/charts/cert-discovery-venafi \
  --registry-config venafi_registry_docker_config.json

Tip

You can use the following region-specific OCI registries:

  • US: oci://private-registry.venafi.cloud/
  • EU: oci://private-registry.venafi.eu/

All Venafi charts use container images in the enterprise registry. Ensure you install the credentials to the desired namespace in your cluster. The installation instructions for the chart provide detailed guidance on specifying the flags that set the ImagePullSecret.

Additional configurations

Configuring a mirroring repository

To set up Docker mirroring, follow the specific process for your mirroring tool, like Artifactory.

The username and password can be found using the following:

Use the username and password that were provided when creating the service account in the Venafi Control Plane UI.

If you used venctl to obtain the Docker config JSON file, or if you created a service account in the Venafi Control Plane UI and downloaded the Docker config JSON file, you can extract the username and password with the following command:

cat venafi_registry_docker_config.json \
  | jq '.. | select(.username?) | "username: \(.username)\npassword: \(.auth)"' -r

This produces an output similar to the following:

username: sa-us@f967c9b7-9d6b-4d23-a241-d5cae7af8214
password: c2EtdXNAYmZiYW...YZFpPT2xvTDhm

Use the outputted username and password to authenticate in your mirroring tool.

Tip

For more information on mirroring for Artifactory, see the Artifactory documentation.

Allow domains

Add the following domains to your corporate firewall allowlist as required:

For the US region:

  • private-registry.venafi.cloud

For the EU region:

  • private-registry.venafi.eu