Organize repositories and access with folders

A folder is a group of resources inside a Chainguard organization. Folders can contain other folders, so you can build a hierarchy under your organization, for example to separate a team’s images, or to stage images for testing before you use them in production.

Folders do two things:

• They group repositories. A repository in a folder has the folder’s name in its path.
• They scope access. A role granted on a folder applies only to that folder and the folders inside it.

Note: Earlier versions of Chainguard called organizations “groups” and folders “subgroups.” The Chainguard Terraform provider still uses the term “groups.”

Create and manage folders

Use chainctl iam folders to work with folders.

Create a folder under your organization. Use --parent to choose where it goes; to create a nested folder, name an existing folder as the parent:

chainctl iam folders create test --parent=example.com

List the folders in an organization:

chainctl iam folders list example.com

Describe, rename, or delete a folder:

chainctl iam folders describe test
chainctl iam folders update test --name=staging
chainctl iam folders delete test

Run any of these commands without a folder name to select one interactively.

Repository paths in folders

A repository’s path is your organization’s name, followed by each folder above the repository, followed by the repository name:

cgr.dev/<organization>/<folder>/<repository>:<tag>
cgr.dev/<organization>/<folder>/<nested-folder>/<repository>:<tag>

The last path segment is always the repository. Everything before it identifies the organization and the folders, from the outermost folder to the innermost one.

For example, with this layout:

example.com
├── python            (repository)
└── test              (folder)
    └── python        (repository)

you pull the two repositories with:

docker pull cgr.dev/example.com/python:latest        # repository at the organization root
docker pull cgr.dev/example.com/test/python:latest   # repository in the "test" folder

These are two separate repositories. An image in test/python isn’t available at example.com/python, or the other way round.

Pulling doesn’t create folders. If a path names a folder that doesn’t exist, the pull fails.

To see which repositories a folder contains, list them with the folder as the parent:

chainctl images repos list --parent=test

Grant access to a folder

Roles apply downward: a role granted on an organization or folder applies to that location and to every folder inside it. A role never applies upward to a parent, or sideways to another folder.

Pull tokens

A pull token can pull from the location it’s created in and from every folder below it.

To use one token for the whole organization, including all of its folders, create it at the organization:

chainctl auth pull-token create --parent=example.com

To limit a token to one folder, create it at that folder:

chainctl auth pull-token create --parent=test

A token created at a folder can’t pull repositories at the organization root or in other folders.

Role-bindings

To give an existing identity pull access to a single folder, bind the registry.pull role at that folder:

chainctl iam role-bindings create --parent=test --identity=<identity-uidp> --role=registry.pull

An identity that already has registry.pull at the organization doesn’t need an extra binding on the folder. The organization binding already covers it.

For more about roles, refer to Overview of roles and role-bindings.

Custom Assembly in folders

You can use Custom Assembly on repositories in folders, and you can bind overlays to every repository in a folder.

A Custom Assembly build for a repository in a folder can currently use only the packages from images in that same folder, not every package your organization is entitled to. If a build in a folder fails to resolve a package that’s available to your organization, build the customized image at the organization root instead, or contact Chainguard support.

Troubleshooting

If a pull from a folder fails, check these in order:

1. The path. Confirm each folder in the path exists and the repository is in the innermost one: chainctl iam folders list <organization>, then chainctl images repos list --parent=<folder>.
2. Where the token or role-binding lives. List pull tokens with chainctl auth pull-token list, and role-bindings with chainctl iam role-bindings list --parent=<organization>, which includes bindings in every folder below it. The binding must be at the folder or at a location above it, such as the organization.
3. Mirrors and proxies. If you pull through an artifact manager such as Artifactory, include the folder in the upstream path it requests from cgr.dev.

Learn more

• Overview of the Chainguard IAM model
• Overview of roles and role-bindings
• Authenticating to the Chainguard registry
• chainctl iam folders reference