New permission capabilities required for pulling images and APKs from cgr.dev

TL;DR: Pulling images will require the repo.blobs.get capability and pulling APKs will require the apk.blobs.get capability. If you only use Chainguard managed roles for pulling artifacts, no action is needed. If you have custom roles that can pull artifacts or create pull tokens, we added these new capabilities for you. If you use Terraform or a similar automated configuration to manage your custom roles, you need to include these new capabilities by 2026/2/14.

Chainguard is updating the required IAM capabilities for pulling images and packages from cgr.dev. We added new capabilities, repo.blobs.get and apk.blobs.get,to the managed roles for pulling artifacts, and they will soon be required by the registry servers.

This communication includes the following topics: 

What is changing?

Chainguard is introducing a new set of Identity and Access Management (IAM) capabilities: repo.blobs.get and apk.blobs.get. These capabilities will differentiate permissions between viewing image repositories and APKs and will be required for pulling artifacts from cgr.dev. These new capabilities are already included in the managed roles that enable pulling artifacts (registry.pull, apk.pull, registry.pull_token_creator, and apk.pull_token_creator), and we added them to custom roles that enable pulling artifacts. After 2026/2/14, these capabilities will be required for authorization to pull artifacts from cgr.dev. 

Why is Chainguard making this change?

Introducing *.blobs.get capabilities provides customers with finer grained control over view-only roles and roles that authorize users to pull artifacts from Chainguard. Previously, users were only required to have the respective *.list capability to both view image/APKs through the console or chainctl and to pull those artifacts. 

How will this affect me?

Please read through the scenarios below to see which applies to you to determine your next steps.

• If you only use managed roles, this change requires NO ACTION. The required capabilities are already present and will work as expected.
• If you use custom roles that leverage these capabilities that were configured manually through chainctl or the API (and are not continuously reconciled), then this change requires no action.
• If you use custom roles that leverage these capabilities that have been configured with Terraform, or a similar automated configuration, then you need to update your custom role definition to include these required capabilities before enforcement is enabled on 2026/2/14. See the next section to learn how to do so.

What do I need to do?

If you have a custom role that is intended to pull artifacts from Chainguard or create pull tokens configured as infrastructure-as-code, you must include the capability in any configuration that manages the custom role. For example, if you are using the Chainguard Terraform provider you need to include one or both of the new capabilities in your custom role definition to ensure the capability changes are persisted. These capabilities are already defined in our platform and can be added now.

resource "chainguard_role" "custom-image-puller" {
  parent_id = "org-id"
  
  name        = "custom-image-puller"
  description = "A user-managed IAM role for pulling images."
  
  capabilities = [
    "groups.list",
    "repo.list",
    "repo.blobs.get", # New capability required for pulling blobs
    ...
  ]
}

Need help or have questions?

We're here to help - visit our support portal at support.chainguard.dev.

- Chainguard Team