Product Docs
Open Source
Education
Chainguard Images tagged :latest or :latest-dev, and Images by digest are available for free in the Public catalog. However, logging in with a Chainguard account and authenticating when pulling from the Registry provides a mechanism for Chainguard to contact you if there are any issues with images you are pulling. This may enable Chainguard to notify you of upcoming deprecations, changes in behavior, critical vulnerabilities and remediations for images you have recently pulled.
:latest
:latest-dev
As of August 16, 2023, all other tags for Chainguard Images in the Public catalog are unavailable without paying for access to the Standard or Custom catalogs. This means that Public catalog users, including open source projects, will either need to pin to the digest they currently use, migrate to the software version associated with :latest, or build upon wolfi-base to build their desired image. You can read about these changes in the Important updates for Chainguard Images public catalog users blog post.
You can register a Chainguard account through our sign up form. This will create your account and your organization’s root IAM group. If you already have an account, you can log in through the login page.
For more details on signing in, you can review our sign in guidance. If your organization is interested in (or already using) custom identity providers like Okta, you can read how to authenticate to Chainguard with custom identity providers.
chainctl
You can configure authentication by using the credential helper included with chainctl. This is the workflow recommended by Chainguard.
First install chainctl, and configure the credential helper:
chainctl auth configure-docker
This will update your Docker config file to call chainctl when an auth token is needed. A browser window will open when the token needs to be refreshed.
Pulls authenticated in this way are associated with your user.
You can also create a “pull token” using chainctl. This generates a longer-lived token that can be used to pull images from other environments that’s don’t support OIDC, such as some CI environments, Kubernetes clusters, or with registry mirroring tools like Artifactory.
First install chainctl, then log in and configure a pull token:
chainctl auth configure-docker --pull-token
With the latest release of chainctl, this will print a docker login command that can be run in the CI environment to log in with a pull token.
docker login
You can also pass the --save flag, which will update your Docker config file with the pull token directly.
--save
This token expires in 30 days by default, which can be shortened using the --ttl flag (for example, --ttl=24h).
--ttl
--ttl=24h
Pulls authenticated in this way are associated with a Chainguard identity, which is associated with the group selected when the pull token was created.
Running the chainctl auth configure-docker --pull-token command multiple times will result in multiple pull tokens being created. However, the tokens are stored in your Docker config when using --save will overwrite old tokens.
Tokens cannot be retrieved once they have been overwritten so they must be extracted from the local Docker config and saved elsewhere if multiple are required.
Pull tokens are associated with Chainguard identities so they can be viewed with:
chainctl iam identities list
To revoke a token, delete the associated identity.
chainctl iam identity delete <identity UUID>
You can configure authentication with OIDC-aware CI platforms like GitHub Actions.
First create an identity using chainctl, which can be limited to only allow OIDC federation from certain GitHub workflow runs:
chainctl iam identity create github [GITHUB-IDENTITY] \ --github-repo=${GITHUB_ORG}/${GITHUB_REPO} \ --github-ref=refs/heads/main \ --role=registry.pull
This creates a Chainguard identity that can be assumed by a GitHub Actions workflow only for the specified GitHub repository, triggered on pushes to the specified branch (such as refs/heads/main), with permissions only to pull from the Chainguard Registry.
refs/heads/main
When this identity is created, its ID will be displayed. Using this ID, you can configure your GitHub Actions workflow to install chainctl and assume this identity when the workflow runs:
name: Chainguard Registry Example on: push: branches: ['main'] permissions: contents: read id-token: write # This is needed for OIDC federation. jobs: example: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: chainguard-dev/actions/setup-chainctl@main with: identity: [[ The Chainguard Identity ID you created above ]] - run: docker pull cgr.dev/chainguard/node
Pulls authenticated in this way are associated with the Chainguard identity you created, which is associated with the group selected when the identity was created.
If the identity is configured to only work with GitHub Actions workflow runs from a given repo and branch, that identity will not be able to pull from other repos or branches, including pull requests targetting the specified branch.
You can also configure a Kubernetes cluster to use a pull token, as described above.
When you create a pull token with --save, your Docker config file is updated to include that token and configure it to be used when pulling images from cgr.dev.
cgr.dev
After that, you can create a Kubernetes secret based on those credentials, following these instructions:
kubectl create secret generic regcred \ --from-file=.dockerconfigjson=<path/to/.docker/config.json> \ --type=kubernetes.io/dockerconfigjson
Important Note: this will also make any other credentials you have configured in your Docker config available in the secret! Ensure only the necessary credentials are included.
Then you can create a Pod that uses that secret, following these instructions:
apiVersion: v1 kind: Pod metadata: name: cgr-example spec: containers: - name: nginx image: cgr.dev/chainguard/nginx:latest imagePullSecrets: - name: regcred
For this example, save the file as cgr-example.yaml. Then you can create and get the Pod:
cgr-example.yaml
kubectl apply -f cgr-example.yaml kubectl get pod cgr-example