Granting access to Container Registry resources tutorial

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.

All accounts require IAM access policies. To set up and manage IAM access policies, see Defining IAM access policies.

For more information about how to use IAM to manage access to your resources, see Managing access to resources.

Before you begin

Before you begin, you must complete the following tasks:

Complete the instructions in Getting started with IBM Cloud Container Registry.
Ensure that you have the most recent version of the container-registry CLI plug-in for the IBM Cloud CLI, see Updating the container-registry CLI plug-in.
Ensure that you have access to two IBM Cloud accounts 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 namespacesA collection of repositories that store images in a registry. A namespace is associated with an IBM Cloud account, which can include multiple namespaces., see Access roles for configuring IBM Cloud Container Registry.

Authorize a user to configure the registry

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

Add User B to User A's account.
1. Log in to User A's account by running the following command.
```
ibmcloud login
```
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.
```
ibmcloud account user-invite <user.b@example.com>
```
3. Get User A's Account ID by running the following command.
```
ibmcloud target
```
  Make a note of the Account ID that is in the parentheses ( ) in the Account row.
Prove that User B can target User A's account but can't 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 <YourAccountID> is User A's Account ID.
```
ibmcloud login -c <YourAccountID>
```
2. Try to edit your registry quota to 4 GB of traffic by running the following command.
```
ibmcloud cr quota-set --traffic=4000
```
  The command fails because User B doesn't have the correct access.
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.
```
ibmcloud login
```
2. Create a policy that grants the Manager role to User B by running the following command.
```
ibmcloud iam user-policy-create <user.b@example.com> --service-name container-registry --roles Manager
```
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.
```
ibmcloud login -c <YourAccountID>
```
2. Try to edit your registry quota to 4 GB of traffic by running the following command.
```
ibmcloud cr quota-set --traffic=4000
```
  It works because User B has the correct type of access.
3. Now change the quota back by running the following command.
```
ibmcloud cr quota-set --traffic=5120
```
Clean up.
1. Log back in to your account as yourself, User A, by running the following command.
```
ibmcloud login
```
2. List the policies for User B, find the policy that you created by running the following command, and note the ID.
```
ibmcloud iam user-policies <user.b@example.com>
```
3. Delete the policy by running the following command, where <Policy_ID> is your Policy ID.
```
ibmcloud iam user-policy-delete <user.b@example.com> <Policy_ID>
```

Authorize a user to access specific namespaces

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.

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.
```
ibmcloud login
```
2. Create namespace_a by running the following command.
```
ibmcloud cr namespace-add namespace_a
```
  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.
  
  If you have a problem when you try to add a namespace, see Why can't I add a namespace? for assistance.
3. Create namespace_b by running the following command.
```
ibmcloud cr namespace-add namespace_b
```
4. Create namespace_c by running the following command.
```
ibmcloud cr namespace-add namespace_c
```
Prove that User B can't see anything.
1. Log in as User B, targeting User A's account by running the following command.
```
ibmcloud login -c <YourAccountID>
```
2. Try to list the namespaces as User B by running the following command.
```
ibmcloud cr namespaces
```
  It returns an empty list because User B doesn't have access to any namespaces.
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.
```
ibmcloud login
```
2. Check that at least three namespaces are listed by running the following command.
```
ibmcloud cr namespaces
```
  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.
```
ibmcloud iam user-policy-create <user.b@example.com> --service-name container-registry --region <cloud_region> --resource-type namespace --resource namespace_b --roles Reader
```
  To see the names of the IBM Cloud regions, run the ibmcloud regions command.
4. Create a second policy that grants the Reader and Writer roles on namespace_c to User B by running the following command.
```
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
```
  This command adds two roles to the same resource in the same policy.
Push images into namespace_a and namespace_b.
1. Pull the hello-world image by running the following command.
```
docker pull hello-world
```
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, for example us-south.
```
docker tag hello-world <registry_region>.icr.io/namespace_a/hello-world
```
3. Tag the image to namespace_b by running the following command.
```
docker tag hello-world <registry_region>.icr.io/namespace_b/hello-world
```
4. Log in to IBM Cloud Container Registry by running the ibmcloud cr login command.
```
ibmcloud cr login
```
  IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see Accessing your namespaces interactively.
  
  If you have a problem when you try to log in, see Why can't I log in to Container Registry? for assistance.
5. Push the image to namespace_a by running the following command.
```
docker push <registry_region>.icr.io/namespace_a/hello-world
```
6. Push the image to namespace_b by running the following command.
```
docker push <registry_region>.icr.io/namespace_b/hello-world
```
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.
```
ibmcloud login -c <YourAccountID>
```
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.
```
ibmcloud cr namespaces
```
3. List your images by running the following command.
```
ibmcloud cr images
```
  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.
```
ibmcloud cr login
```
  IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see Accessing your namespaces interactively.
5. Pull the image by running the following command.
```
docker pull <registry_region>.icr.io/namespace_b/hello-world
```
6. Push the image to namespace_b by running the following command.
```
docker push <registry_region>.icr.io/namespace_b/hello-world
```
  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.
```
docker tag hello-world <registry_region>.icr.io/namespace_c/hello-world
```
8. Push the image to namespace_c by running the following command.
```
docker push <registry_region>.icr.io/namespace_c/hello-world
```
  The command works because User B has the Writer role in namespace_c.
9. Pull from namespace_c by running the following command.
```
docker pull <registry_region>.icr.io/namespace_c/hello-world
```
  The command works because User B has the Reader role in namespace_c.
Clean up:
1. Log back in to User A's account by running the following command.
```
ibmcloud login
```
2. List the policies for User B by running the following command.
```
ibmcloud iam user-policies <user.b@example.com>
```
  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.
```
ibmcloud iam user-policy-delete <user.b@example.com> <Policy_ID>
```

Create a service ID and grant access to a resource

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

Set up a service ID with access to IBM Cloud Container Registry and create an API keyA unique code that is passed to an API to identify the calling application or user. An API key is used to track and control how the API is being used, for example, to prevent malicious use or abuse of the API. for it.
1. Log in to User A's account by running the following command.
```
ibmcloud login
```
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.
```
ibmcloud iam service-id-create cr-roles-tutorial --description "Created during the access control tutorial for Container Registry"
```
3. Create a service policy for the service ID that grants the Reader role on namespace_a by running the following command.
```
ibmcloud iam service-policy-create cr-roles-tutorial --service-name container-registry --region <cloud_region> --resource-type namespace --resource namespace_a --roles Reader
```
4. Create a second service policy that grants the Writer role on namespace_b by running the following command.
```
ibmcloud iam service-policy-create cr-roles-tutorial --service-name container-registry --region <cloud_region> --resource-type namespace --resource namespace_b --roles Writer
```
5. Create an API key for the service ID by running the following command.
```
ibmcloud iam service-api-key-create cr-roles-tutorial-apikey cr-roles-tutorial
```
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.
```
docker login -u iamapikey -p <API_Key> <registry_region>.icr.io
```
  IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see Accessing your namespaces in automation.
2. Pull your image by running the following command.
```
docker pull <registry_region>.icr.io/namespace_a/hello-world
```
3. Push your image to namespace_a by running the following command.
```
docker push <registry_region>.icr.io/namespace_a/hello-world
```
  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.
```
docker push <registry_region>.icr.io/namespace_b/hello-world
```
  This command works because the user has the Writer role in namespace_b.
Clean up:
1. Log back in to IBM Cloud Container Registry as User A.
```
ibmcloud cr login
```
  IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see Accessing your namespaces interactively.
2. List your service policies by running the following command.
```
ibmcloud iam service-policies cr-roles-tutorial
```
  Note your Policy IDs.
3. Delete your service policies by running the following command for each policy.
```
ibmcloud iam service-policy-delete cr-roles-tutorial <Policy_ID>
```
4. Delete your service ID by running the following command.
```
ibmcloud iam service-id-delete cr-roles-tutorial
```

Cleaning up your account

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

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

ibmcloud cr namespace-rm namespace_a

ibmcloud cr namespace-rm namespace_b

ibmcloud cr namespace-rm namespace_c

Remove User B from your account by running the following command.
```
ibmcloud account user-remove <user.b@example.com>
```