---
name: Registry-registry_tutorial_configure_iam
title: Granting access to Container Registry resources
description: Use this tutorial to find out how to grant access to your resources by configuring IBM Cloud® Identity and Access Management (IAM) for IBM Cloud® Container Registry.
last-updated: 2026-08-03
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/Registry?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Granting access to Container Registry resources
{: #iam_access}
{: toc-content-type="tutorial"}
{: toc-completion-time="45m"}

Use this tutorial to find out how to grant access to your resources by configuring IBM Cloud® Identity and Access Management (IAM) for IBM Cloud® Container Registry.
{: shortdesc}

All accounts require IAM access policies. To set up and manage IAM access policies, see [Defining IAM access policies](https://cloud.ibm.com/docs/Registry?topic=Registry-user&format=markdown#user).

For more information about how to use IAM to manage access to your resources, see [Managing access to resources](https://cloud.ibm.com/docs/iam?topic=iam-assign-access-resources&interface=ui&format=markdown).

## Before you begin
{: #iam_access_prereq}

Before you begin, you must complete the following tasks:

- Complete the instructions in [Getting started with IBM Cloud Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-getting-started&format=markdown#getting-started).
- Ensure that you have the most recent version of the `container-registry` command-line interface (CLI) plug-in for the IBM Cloud CLI, see [Updating the `container-registry` CLI plug-in](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_setup_cli_namespace&format=markdown#registry_cli_update).
- Ensure that you have access to two [IBM Cloud accounts](https://cloud.ibm.com/login){: external} that you can use for this tutorial, one for User A and one for User B, each must use a unique email address. You work in your own account, User A, and invite another user, User B, to use your account. You can choose to create a second IBM Cloud account, or you can work with a colleague that has an IBM Cloud account.
- Ensure that you have the correct access permissions for adding and removing [namespaces](#x2031005){: term}, see [Access roles for configuring IBM Cloud Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-iam&format=markdown#access_roles_configure).

## Authorize a user to configure the registry
{: #configure_registry}
{: step}

Add a second user to your account and grant them the ability to configure IBM Cloud Container Registry.

1. Add User B to User A's account.

    1. Log in to User A's account by running the following command.

        ```txt
        ibmcloud login
        ```
        {: pre}

    2. Invite User B to access User A's account by running the following command, where `<user.b@example.com>` is User B's email address.

        ```txt
        ibmcloud account user-invite <user.b@example.com>
        ```
        {: pre}

    3. Get User A's Account ID by running the following command.

        ```txt
        ibmcloud target
        ```
        {: pre}

        Make a note of the Account ID that is in the parentheses ( ) in the Account row.

2. Prove that User B can target User A's account but cannot do anything with IBM Cloud Container Registry yet.

    1. Log in as User B and target User A's account by running the following command, where `YOUR_ACCOUNT_ID` is User A's Account ID.

        ```txt
        ibmcloud login -c YOUR_ACCOUNT_ID
        ```
        {: pre}

    2. Try to edit your registry quota to 4 GB of traffic by running the following command.

        ```txt
        ibmcloud cr quota-set --traffic 4000
        ```
        {: pre}

        The command fails because User B doesn't have the correct access.

3. Grant User B the Manager role so that User B can configure IBM Cloud Container Registry.

    1. Log back in to your account as yourself, User A, by running the following command.

        ```txt
        ibmcloud login
        ```
        {: pre}

    2. Create a policy that grants the Manager role to User B by running the following command.

        ```txt
        ibmcloud iam user-policy-create USER.B@EXAMPLE.COM --service-name container-registry --roles Manager
        ```
        {: pre}

4. Prove that User B can now change quotas in User A's account.

    1. Log in as User B, targeting User A's account by running the following command.

        ```txt
        ibmcloud login -c YOUR_ACCOUNT_ID
        ```
        {: pre}

    2. Try to edit your registry quota to 4 GB of traffic by running the following command.

        ```txt
        ibmcloud cr quota-set --traffic 4000
        ```
        {: pre}

        It works because User B has the correct type of access.

    3. Now change the quota back by running the following command.

        ```txt
        ibmcloud cr quota-set --traffic 5120
        ```
        {: pre}

5. Clean up.

    1. Log back in to your account as yourself, User A, by running the following command.

        ```txt
        ibmcloud login
        ```
        {: pre}

    2. List the policies for User B, find the policy that you created by running the following command, and note the ID.

        ```txt
        ibmcloud iam user-policies <user.b@example.com>
        ```
        {: pre}

    3. Delete the policy by running the following command, where `POLICY_ID` is your Policy ID.

        ```txt
        ibmcloud iam user-policy-delete <user.b@example.com> POLICY_ID
        ```
        {: pre}

## Authorize a user to access specific namespaces
{: #access_resources}
{: step}

Create some namespaces with sample images, and grant access to them. You create policies to grant different roles to each namespace, and show what effect that has.

1. Create three new namespaces in User A's account. These namespaces must be unique across the region, so choose your own namespace names, but this tutorial uses `namespace_a`, `namespace_b` and `namespace_c` as examples.

    1. Log in as User A, by running the following command.

        ```txt
        ibmcloud login
        ```
        {: pre}

    2. Create `namespace_a` by running the following command.

        ```txt
        ibmcloud cr namespace-add namespace_a
        ```
        {: pre}

        The namespace must be unique across all IBM Cloud accounts in the same region. Namespaces must have 4 - 30 characters, and contain lowercase letters, numbers, hyphens (-), and underscores (_) only. Namespaces must start and end with a letter or number.
        {: requirement}

        If you have a problem when you try to add a namespace, see [Why can't I add a namespace?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-add-namespace&format=markdown) for assistance.
        {: tip}

    3. Create `namespace_b` by running the following command.

        ```txt
        ibmcloud cr namespace-add namespace_b
        ```
        {: pre}

    4. Create `namespace_c` by running the following command.

        ```txt
        ibmcloud cr namespace-add namespace_c
        ```
        {: pre}

2. Prove that User B cannot see anything.

    1. Log in as User B, targeting User A's account by running the following command.

        ```txt
        ibmcloud login -c YOUR_ACCOUNT_ID
        ```
        {: pre}

    2. Try to list the namespaces as User B by running the following command.

        ```txt
        ibmcloud cr namespaces
        ```
        {: pre}

        It returns an empty list because User B doesn't have access to any namespaces.

3. Create policies to grant User B the ability to interact with the namespaces by running the following command.

    1. Log in as User A's account by running the following command.

        ```txt
        ibmcloud login
        ```
        {: pre}

    2. Check that at least three namespaces are listed by running the following command.

        ```txt
        ibmcloud cr namespaces
        ```
        {: pre}

        The three namespaces that you created in this tutorial (`namespace_a`, `namespace_b`, and `namespace_c`) are shown. If you do not see these namespaces, repeat the instructions to create them again.

    3. Create a policy that grants the Reader role on `namespace_b` to User B by running the following command, where `CLOUD_REGION` is the name of your IBM Cloud region, for example `us-south`.

        ```txt
        ibmcloud iam user-policy-create USER.B@EXAMPLE.COM --service-name container-registry --region CLOUD_REGION --resource-type namespace --resource namespace_b --roles Reader
        ```
        {: pre}

        To see the names of the IBM Cloud regions, run the [`ibmcloud regions`](https://cloud.ibm.com/docs/cli?topic=cli-ibmcloud_cli&format=markdown#ibmcloud_regions) command.
        {: tip}

    4. Create a second policy that grants the Reader and Writer roles on `namespace_c` to User B by running the following command.

        ```txt
        ibmcloud iam user-policy-create USER.B@EXAMPLE.COM --service-name container-registry --region CLOUD_REGION --resource-type namespace --resource namespace_c --roles Reader,Writer
        ```
        {: pre}

        This command adds two roles to the same resource in the same policy.
        {: note}

4. Push images into `namespace_a` and `namespace_b`.

    1. Pull the `hello-world` image by running the following command.

        ```txt
        docker pull hello-world
        ```
        {: pre}

    2. Tag the image to `namespace_a` by running the following command, where `REGISTRY_REGION` is the name of your [IBM Cloud Container Registry region](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#registry_regions), for example `us-south`.

        ```txt
        docker tag hello-world REGISTRY_REGION.icr.io/namespace_a/hello-world
        ```
        {: pre}

    3. Tag the image to `namespace_b` by running the following command.

        ```txt
        docker tag hello-world REGISTRY_REGION.icr.io/namespace_b/hello-world
        ```
        {: pre}

    4. Log in to IBM Cloud Container Registry by running the [`ibmcloud cr login`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_login) command.

        ```txt
        ibmcloud cr login
        ```
        {: pre}

        IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see [Accessing your namespaces interactively](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_access&format=markdown#registry_access_interactive).
        {: tip}

        If you have a problem when you try to log in, see [Why can't I log in to Container Registry?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-login&format=markdown) for assistance.
        {: tip}

    5. Push the image to `namespace_a` by running the following command.

        ```txt
        docker push REGISTRY_REGION.icr.io/namespace_a/hello-world
        ```
        {: pre}

    6. Push the image to `namespace_b` by running the following command.

        ```txt
        docker push REGISTRY_REGION.icr.io/namespace_b/hello-world
        ```
        {: pre}

5. Prove that User B can interact with `namespace_b` and `namespace_c`, but not `namespace_a`.

    1. Log in as User B by running the following command.

        ```txt
        ibmcloud login -c YOUR_ACCOUNT_ID
        ```
        {: pre}

    2. Show that User B can see `namespace_b` and `namespace_c`, but not `namespace_a` because User B doesn't have access to `namespace_a`, by running the following command.

        ```txt
        ibmcloud cr namespaces
        ```
        {: pre}

    3. List your images by running the following command.

        ```txt
        ibmcloud cr images
        ```
        {: pre}

        The image in `namespace_b` is shown in the list, but the image in `namespace_a` doesn't, because User B doesn't have access to `namespace_a`.

    4. Log in to IBM Cloud Container Registry by running the following command.

        ```txt
        ibmcloud cr login
        ```
        {: pre}

        IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see [Accessing your namespaces interactively](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_access&format=markdown#registry_access_interactive).
        {: tip}

    5. Pull the image by running the following command.

        ```txt
        docker pull REGISTRY_REGION.icr.io/namespace_b/hello-world
        ```
        {: pre}

    6. Push the image to `namespace_b` by running the following command.

        ```txt
        docker push REGISTRY_REGION.icr.io/namespace_b/hello-world
        ```
        {: pre}

        This command fails because User B doesn't have the Writer role in `namespace_b`.

    7. Tag the image with `namespace_c` by running the following command.

        ```txt
        docker tag hello-world REGISTRY_REGION.icr.io/namespace_c/hello-world
        ```
        {: pre}

    8. Push the image to `namespace_c` by running the following command.

        ```txt
        docker push REGISTRY_REGION.icr.io/namespace_c/hello-world
        ```
        {: pre}

        The command works because User B has the Writer role in `namespace_c`.

    9. Pull from `namespace_c` by running the following command.

        ```txt
        docker pull REGISTRY_REGION.icr.io/namespace_c/hello-world
        ```
        {: pre}

        The command works because User B has the Reader role in `namespace_c`.

6. Clean up:

    1. Log back in to User A's account by running the following command.

        ```txt
        ibmcloud login
        ```
        {: pre}

    2. List the policies for User B by running the following command.

        ```txt
        ibmcloud iam user-policies <user.b@example.com>
        ```
        {: pre}

        Find the policies that you created and note the Policy IDs.

    3. Delete the policies that you created by running the following command, where `POLICY_ID` is the Policy ID.

        ```txt
        ibmcloud iam user-policy-delete <user.b@example.com> POLICY_ID
        ```
        {: pre}

## Create a service ID and grant access to a resource
{: #service_id}
{: step}

Configure a service ID and grant it access to your IBM Cloud Container Registry namespace.

1. Set up a service ID with access to IBM Cloud Container Registry and create an [API key](#x8051010){: term} for it.

    1. Log in to User A's account by running the following command.

        ```txt
        ibmcloud login
        ```
        {: pre}

    2. Create a service ID named `cr-roles-tutorial` with the description `"Created during the access control tutorial for Container Registry"` by running the following command.

        ```txt
        ibmcloud iam service-id-create cr-roles-tutorial --description "Created during the access control tutorial for Container Registry"
        ```
        {: pre}

    3. Create a service policy for the service ID that grants the Reader role on `namespace_a` by running the following command.

        ```txt
        ibmcloud iam service-policy-create cr-roles-tutorial --service-name container-registry --region CLOUD_REGION --resource-type namespace --resource namespace_a --roles Reader
        ```
        {: pre}

    4. Create a second service policy that grants the Writer role on `namespace_b` by running the following command.

        ```txt
        ibmcloud iam service-policy-create cr-roles-tutorial --service-name container-registry --region CLOUD_REGION --resource-type namespace --resource namespace_b --roles Writer
        ```
        {: pre}

    5. Create an API key for the service ID by running the following command.

        ```txt
        ibmcloud iam service-api-key-create cr-roles-tutorial-apikey cr-roles-tutorial
        ```
        {: pre}

2. Use Docker to log in with the service ID API key, where `API_KEY` is your API key, and interact with the registry.

    1. Log in to IBM Cloud Container Registry by running the following command.

        ```txt
        docker login -u iamapikey -p API_KEY REGISTRY_REGION.icr.io
        ```
        {: pre}

        IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see [Accessing your namespaces in automation](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_access&format=markdown#registry_access_automating).
        {: tip}

    2. Pull your image by running the following command.

        ```txt
        docker pull REGISTRY_REGION.icr.io/namespace_a/hello-world
        ```
        {: pre}

    3. Push your image to `namespace_a` by running the following command.

        ```txt
        docker push REGISTRY_REGION.icr.io/namespace_a/hello-world
        ```
        {: pre}

        This command doesn't work because the user doesn't have the Writer role in `namespace_a`.

    4. Push your image to `namespace_b` by running the following command.

        ```txt
        docker push REGISTRY_REGION.icr.io/namespace_b/hello-world
        ```
        {: pre}

        This command works because the user has the Writer role in `namespace_b`.

3. Clean up:

    1. Log back in to IBM Cloud Container Registry as User A.

        ```txt
        ibmcloud cr login
        ```
        {: pre}

        IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see [Accessing your namespaces interactively](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_access&format=markdown#registry_access_interactive).
        {: tip}

    2. List your service policies by running the following command.

        ```txt
        ibmcloud iam service-policies cr-roles-tutorial
        ```
        {: pre}

        Note your Policy IDs.

    3. Delete your service policies by running the following command for each policy.

        ```txt
        ibmcloud iam service-policy-delete cr-roles-tutorial POLICY_ID
        ```
        {: pre}

    4. Delete your service ID by running the following command.

        ```txt
        ibmcloud iam service-id-delete cr-roles-tutorial
        ```
        {: pre}

## Cleaning up your account
{: #clean_up}
{: step}

Remove the resources that you created in previous sections so that your account returns to how it was at the start of this tutorial.

1. Log in to User A's account by running the following command.

    ```txt
    ibmcloud login
    ```
    {: pre}

2. Delete `namespace_a`, `namespace_b`, and `namespace_c` by running the following commands.

    ```txt
    ibmcloud cr namespace-rm namespace_a
    ```
    {: pre}

    ```txt
    ibmcloud cr namespace-rm namespace_b
    ```
    {: pre}

    ```txt
    ibmcloud cr namespace-rm namespace_c
    ```
    {: pre}

3. Remove User B from your account by running the following command.

    ```txt
    ibmcloud account user-remove <user.b@example.com>
    ```
    {: pre}