IBM Cloud Docs
Setting up the Container Registry CLI and namespace

Setting up the Container Registry CLI and namespace

To manage your Docker images in IBM Cloud® Container Registry, you must install the container-registry CLI plug-in and create a namespaceA collection of repositories that store images in a registry. A namespace is associated with an IBM Cloud account, which can include multiple namespaces. in a resource groupThe environment, and constraints, in which contained resource instances adhere to. A user can be associated with a resource group to enable collaboration..

Do not put personal information in your container images, namespace names, description fields, or in any image configuration data (for example, image names or image labels).

To add and remove namespaces, you must have the Manager role at the account level, see Access roles for configuring IBM Cloud Container Registry.

Before you begin, install the IBM Cloud CLI, see Getting started with the IBM Cloud CLI.

Installing the container-registry CLI plug-in

Install the container-registry CLI plug-in so that you can use the command line to manage your namespaces and Docker images in IBM Cloud Container Registry.

  1. Install the container-registry CLI plug-in by running the following command:

    ibmcloud plugin install container-registry

    For more information about installing plug-ins, see Extending IBM Cloud CLI with plug-ins.

  2. Optional: Configure your Docker client to run commands without root permissions. If you do not do this step, you must run ibmcloud login, ibmcloud cr login, docker pull, and docker push commands with sudo or as root.

IBM Cloud Container Registry supports Docker and other clients. To log in by using other clients, see Accessing your namespaces interactively.

You can now set up your own namespace in IBM Cloud Container Registry.

Updating the container-registry CLI plug-in

You might want to update the container-registry CLI plug-in periodically to use new features.

Updating container-registry CLI plug-in version 1.0

To update version 1.0 of the Container Registry CLI, run the following command:

ibmcloud plugin update container-registry

Updating container-registry CLI plug-in version 0.1

To update version 0.1 of the Container Registry CLI, run the following command, where <version_number> is the number of the version of the CLI.

Version 0.1 of the Container Registry CLI is deprecated. For more information, see All releases of Container Registry plug-in 0.1 are deprecated.

ibmcloud plugin install container-registry -v <version_number>

For example, to update the CLI to version 0.1.584, run the following command:

ibmcloud plugin install container-registry -v 0.1.584

Uninstalling the container-registry CLI plug-in

If you no longer need the container-registry CLI plug-in, you can uninstall it.

To uninstall the container-registry CLI plug-in, run the following command:

ibmcloud plugin uninstall container-registry

Planning namespaces

IBM Cloud Container Registry provides a multi-tenant private image registryA storage and distribution service that contains public or private images that are used to create containers. that is hosted and managed by IBM. You can store and share your Docker images in this registry by setting up a registry namespace.

Namespaces are created in a resource group that you specify so that you can configure access to resources within the namespace at the resource group level. If you don't specify a resource group, and a resource group isn't targeted, the default resource group is used. However, you can still set permissions for the namespace at the account level or in the namespace itself. If you don't specify a resource group, and a resource group isn't targeted, the default resource group is used.

If you have an older namespace that isn't in a resource group, you can assign it to a resource group and then set permissions for that namespace at the resource group level. For more information about resource groups, see Assigning existing namespaces to resource groups.

Namespaces that are assigned to a resource group show in the Resource list page of the IBM Cloud console.

You can set up multiple namespaces, for example, to have separate repositories for your production and staging environments. If you want to use the registry in multiple IBM Cloud regions, you must set up a namespace for each region. Namespace names are unique within regions. You can use the same namespace name for each region, unless someone else already has a namespace with that name in that region.

You can have 100 namespaces in each region.

To work with the IBM-provided public images only, you do not need to set up a namespace.

If you're unsure whether a namespace is already set for your account, run the ibmcloud cr namespace-list command with the -v option to retrieve existing namespace information.

Consider the following rules when you choose a namespace:

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

Do not put personal information in your namespace names.

After you set your first namespace, you are assigned to the free IBM Cloud Container Registry service plan unless you upgrade your plan.

User permissions for working with namespaces

You can control which users can work with namespaces by using IAM roles.

  • To add, assign, and remove namespaces, you must have the Manager role in the IBM Cloud Container Registry service at the account level, see Access roles for configuring IBM Cloud Container Registry.

    • To add and assign namespaces, you must also have the Viewer platform role for the resource group in which you want to create the namespace. To assign the Viewer role for a resource group to a user, run the following ibmcloud iam user-policy-create command, where <user> is the name of the user and <resource_group_id> is the resource group ID:

      ibmcloud iam user-policy-create <user> --roles Viewer --resource-type resource-group --resource <resource_group_id>

  • To view and analyze namespaces, you must have the Reader or Manager role in the IBM Cloud Container Registry service, see Access roles for using IBM Cloud Container Registry.

For more information about user roles, Defining IAM access policies.

Setting up a namespace

You must create a namespace to store your Docker images in IBM Cloud Container Registry.

Before you begin, complete the following tasks:

To create a namespace, see Set up a namespace. Namespaces are created in the resource group that you specify so that you can configure access to resources within the namespace at the resource group level. If you don't specify a resource group, and a resource group isn't targeted, the default resource group is used. For more information about resource groups, see Managing resource groups.

Namespaces that are assigned to a resource group show in the Resource list page of the IBM Cloud console.

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.

You can now push Docker images to your namespace in IBM Cloud Container Registry and share these images with other users in your account. To control access to namespaces in IBM Cloud IAM, see Creating policies.

Assigning existing namespaces to resource groups

Namespaces created in version 0.1.484 of the CLI or earlier and in the IBM Cloud console before 29 July 2020, aren't assigned to resource groups. If you have a namespace that isn't assigned to a resource group, you can assign the namespace to a resource group and then set permissions for that namespace at the resource group level.

You can assign a namespace to a resource group only once. When a namespace is in a resource group, you can't move it to another resource group.

You can assign an existing namespace to a resource group by using the ibmcloud cr namespace-assign command. To find out which namespaces are assigned to resource groups and which are unassigned, run the ibmcloud cr namespace-list command with the -v option.

Namespaces that are assigned to a resource group show in the Resource list page of the IBM Cloud console.

If the namespaces don't all show in the Resource list page, see Why don't all my namespaces show in the Resource list? for assistance.

For more information about resource groups, see Creating a resource group.

To assign an existing namespace to a resource group, complete the following steps:

  1. Log in to IBM Cloud.

    ibmcloud login

  2. To find the namespace, list the available namespaces.

    ibmcloud cr namespace-list -v

  3. Assign the namespace to a resource group.

    Replace <my_resource_group> with the name or ID of the resource group and <my_namespace> with the name of the namespace.

    ibmcloud cr namespace-assign -g <my_resource_group> <my_namespace>

Removing namespaces

If you no longer require a registry namespace, you can remove the namespace from your IBM Cloud account.

  1. Log in to IBM Cloud.

    ibmcloud login

  2. List available namespaces.

    ibmcloud cr namespace-list

  3. Remove a namespace.

    When you remove a namespace, any images that are stored in that namespace are also deleted. This action cannot be undone.

    Replace <my_namespace> with the namespace that you want to remove.

    ibmcloud cr namespace-rm <my_namespace>

    After you delete a namespace, it might take a few minutes before that namespace becomes available again to reuse.