Registry Overview
An Overview of Chainguard's Registry
Organizations can use Chainguard Containers along with third-party software repositories in order to integrate with current workflows as the single source of truth for software artifacts. In this situation, you can set up a proxy repository to function as a mirror of Chainguard’s registry. This mirror can then serve as a pull through cache for your Chainguard Containers.
This tutorial outlines how to set up a remote repository with Google Artifact Registry. It will walk you through how to set up an Artifact Registry Repository you can use as a pull through cache for Chainguard’s public Starter containers or Production containers originating from a private Chainguard repository.
In order to complete this tutorial, you will need the following:
chainctl
installed to create the pull token. If you haven’t already installed this, follow the installation guide.Chainguard’s Starter container images are free to use, publicly available, and always represent versions tagged as :latest
.
To set up a remote repository in Google Artifact Registry from which you can pull Chainguard Starter container images, log in to the Google Cloud Console and choose your project. Once there, navigate to the Artifact Registry section, click on Repositories in the left-hand navigation menu, and click on the Create Repository button near the top of the page.
On the Create Repository page, enter the following details for your new remote repository:
chainguard-pull-through
.https://cgr.dev/
in the Custom repository field.Following that, choose the Location, Encryption and Cleanup policy options for your repository. This guide’s examples will use the location us-central1
, but you can choose the location that best suits your needs. Finally, click the Create button to create the repository.
By default, the Artifact Registry repository requires authentication. Log in with a valid Google Artifact Registry:
gcloud auth configure-docker us-central1-docker.pkg.dev
Be sure to change us-central1
to reflect the location of your Artifact Registry repository.
Also, after running this command you may be prompted to log in to your Google Cloud account.
After running the command, you will be able to pull a Starter container through Google Artifact Registry. The following example pulls the go
container:
docker pull us-central1-docker.pkg.dev/<your-project-id>/chainguard-pull-through/chainguard/go:latest
This command first specifies the location of the Artifact Registry repository we just created (us-central1-docker.pkg.dev/<your-project-id>/chainguard-pull-through/
). It then follows that with the name of the Starter containers and the remote repository we want to pull it from (chainguard/go:latest
).
If you run into issues with this command, be sure that it contains the correct Google Artifact Registry URL for your repository, including the location and project ID.
Chainguard’s Production container images are enterprise-ready container images that come with patch SLAs and features such as Federal Information Processing Standard (FIPS) readiness. The process for setting up a Google Artifact Registry repository that you can use as a pull through cache for Chainguard Production container images is similar to the one outlined previously for Starter containers, but with a few extra steps.
To get started, you will need to create a pull token for your organization’s registry. Pull tokens are longer-lived tokens that can be used to pull container images from other environments that don’t support OIDC, such as some CI environments, Kubernetes clusters, or with registry mirroring tools like Google Artifact Registry.
First log in with chainctl
:
chainctl auth login
Then configure a pull token:
chainctl auth configure-docker --pull-token
This command will prompt you to select an organization. Be sure to select the organization whose Production container images you want to pull through the Artifact Registry repository.
This will create a pull token and print a docker login
command that can be run in a CI environment to log in with the token. This command includes both --username
and --password
arguments.
Note down the username
value, as you will need it shortly. Then run the following command to create an environment variable named $PASSWORD
set to the pull token password generated by the previous command:
export PASSWORD=<password value copied from previous output>
Now that you’ve set up a pull token, you can configure a repository for pulling through Production container images.
You can edit the existing repository and all your users will have access to the private images. Alternatively, you could create a new chainguard-private
repository exactly as before but with restricted access, though restricting access to repositories in Google Artifact Registry is beyond the scope of this guide.
First, you will need to store the pull token password as a Google Secret Manager secret. This is because Google Artifact Registry does not support storing passwords directly in the repository configuration. To do this, first run the following command:
gcloud secrets create chainguard-pull-token
This command creates an empty secret. Next, you can update the secret with the pull token password using the environment variable you set previously:
echo -n $PASSWORD | gcloud secrets versions add chainguard-pull-token --data-file=-
If you haven’t already done so, this command will ask if you want to enable the Secret Manager API. Press y
and then ENTER
to enable the API and allow the command to finish.
Alternatively, you can also provide the secret using the Google Cloud Console in the Secret Manager section. To do this, select Create Secret, provide a name for the secret, and enter the pull token password in the Secret value field. You also have the option to choose a replication policy, rotation policy, expiration policy, notification policy and more for the secret.
Back in the Google Artifact Registry, click on the repository you want to configure for pulling through Production containers and then click on the Edit button to edit the repository configuration. In the Remote repository source section of the configuration screen, choose Authenticated.
Enter the pull token username
value in the Username field. In the Password field, select the secret you created in Google Secret Manager.
Click the Save button to apply the changes.
As with testing pull through of a Starter container, you’ll first need to authenticate to the Artifact Registry:
gcloud auth configure-docker us-central1-docker.pkg.dev
Be sure to change us-central1
to reflect the location of your Artifact Registry repository.
After running the command, you will be able to pull any Production container images that your organization has access to through Google Artifact Registry. For example, the following command will pull the chainguard-base
Container if your organization has access to it:
docker pull us-central1-docker.pkg.dev/<your-project-id>/chainguard-pull-through/<example.com>/chainguard-base:latest
Be sure the docker pull
command you run includes the name of your Chainguard organization’s registry.
If you run into issues when trying to pull Containers from Chainguard’s registry to Google Artifact Registry, please ensure the following requirements are met:
https://cgr.dev/
. This field must not contain additional components.docker login
from another node (using the Google Artifact Registry pull token credentials) and try pulling an image from cgr.dev/chainguard/<image name>
or cgr.dev/<company domain>/<image name>
.If you haven’t already done so, you may find it useful to review our Registry Overview to learn more about Chainguard’s registry. You can also learn more about Chainguard Containers by checking out our Containers documentation. If you’d like to learn more about Google Artifact Registry, we encourage you to refer to the official Google Artifact Registry documentation.
Last updated: 2024-08-19 15:56