How to Set Up Pull Through from Chainguard's Registry to Google Artifact 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.

Prerequisites

In order to complete this tutorial, you will need the following:

• Docker installed on your local machine. Follow the official installation instructions to set this up.
• Administrative privileges over a Google Cloud Platform project. This project will also need to have the Artifact Registry API enabled.
• If you plan to set up an Artifact Registry repository to serve as a pull through cache for Production containers, then you will also need to have privileges to create a pull token from Chainguard.
  • Additionally, you’ll need chainctl installed to create the pull token. If you haven’t already installed this, follow the installation guide.

Setting up Google Artifact Registry as a Pull Through for Starter Containers

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:

• Name — This is used to refer to your repository. You can choose whatever name you like here, but this guide’s examples will use the name chainguard-pull-through.
• Format — For the purposes of this guide, this must be set to Docker.
• Mode — Set this to Remote.
• Remote repository source — Choose Custom then enter 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.

Testing pull through of a Starter container image

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.

Setting up Google Artifact Registry as a Pull Through for Production Containers

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.

Testing pull through of a Production container:

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.

Debugging Pull Through from Chainguard’s Registry to Google Artifact 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:

• Ensure that all Containers network requirements are met.
• When configuring a remote Google Artifact Registry repository, ensure that the URL field is set to https://cgr.dev/. This field must not contain additional components.
• You can troubleshoot by running 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>.
• It could be that your Google Artifact Registry repository was misconfigured. In this case, create and configure a new Google Artifact Registry repository to test with.

Learn More

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.