getting-started.md

copyright	years 2017, 2025
lastupdated	2025-08-12
keywords	IBM Cloud Container Registry, namespace, cli, Docker, image, registry, Podman, resource group, docker, repository
subcollection	Registry
content-type	tutorial
services	containers
account-plan	lite
completion-time	45m

{{site.data.keyword.attribute-definition-list}}

Getting started with {{site.data.keyword.registryshort_notm}}

{: #getting-started} {: toc-content-type="tutorial"} {: toc-services="containers"} {: toc-completion-time="45m"}

{{site.data.keyword.registrylong}} provides a multi-tenant private image registry that you can use to store and share your container images with users in your {{site.data.keyword.cloud_notm}} account. {: shortdesc}

The {{site.data.keyword.cloud_notm}} console includes a brief Quick Start. To find out more about how to use the {{site.data.keyword.cloud_notm}} console, see Managing image security with Vulnerability Advisor.

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). {: important}

Before you begin

{: #gs_registry_prereqs}

Install the {{site.data.keyword.cloud_notm}} command-line interface (CLI) so that you can run the {{site.data.keyword.cloud_notm}} ibmcloud commands, see Getting started with the {{site.data.keyword.cloud_notm}} CLI.

The following instructions assume that you’re in your own account with permission to do everything. If you find that you can't run the commands and you’re a member of an account that is owned and administered by someone else, you might lack the correct permissions to configure and operate the {{site.data.keyword.registryshort}} service. In which case, you must ask your administrator to give you the required IAM service access role permissions. For more information, see Why can't I get started with {{site.data.keyword.registryshort}}? {: note}

Install the {{site.data.keyword.registryshort_notm}} CLI

{: #gs_registry_cli_install} {: step}

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

   ibmcloud plugin install container-registry

   {: pre}

   For more information about installing plug-ins, see Extending {{site.data.keyword.cloud_notm}} CLI with plug-ins.

Set up a namespace

{: #gs_registry_namespace_add} {: step} {: help} {: support}

Create a namespace. The namespace is 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 you don't target a resource group, the default resource group is used. Namespaces that are assigned to a resource group show in the Resource list page of the {{site.data.keyword.cloud_notm}} console.

1. Log in to {{site.data.keyword.cloud_notm}}.

   ibmcloud login

   {: pre}

   If you have a federated ID, use ibmcloud login --sso to log in. Enter your username and use the provided URL in your CLI output to retrieve your one-time passcode. If you have a federated ID, the login fails without the --sso and succeeds with the --sso option. {: requirement}

   You don't need to log in to {{site.data.keyword.registryshort_notm}} until you want to push an image, see Step 5: Push images to your namespace. {: note}

2. Add a namespace to create your own image repository. Replace MY_NAMESPACE with your preferred namespace.

   The namespace must be unique across all {{site.data.keyword.cloud_notm}} 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}

   ibmcloud cr namespace-add MY_NAMESPACE

   {: pre}

   You can put the namespace in a resource group of your choice by using one of the following options.

   • Before you create the namespace, run the ibmcloud target -g RESOURCE_GROUP command, where RESOURCE_GROUP is the resource group.
   • Specify the resource group by using the -g option on the ibmcloud cr namespace-add command.

   If you have a problem when you try to create a namespace, see Why can't I add a namespace? for assistance. {: tip}

3. To help ensure that your namespace is created, run the ibmcloud cr namespace-list command.

   ibmcloud cr namespace-list -v

   {: pre}

Pull images from a registry to your local computer

{: #gs_registry_images_pulling} {: step} {: help} {: support}

1. Install Docker or a tool of your choice, such as Podman.

   • Install the Docker Engine CLI{: external}.

     [Windows]{: tag-windows} [macOS]{: tag-macos} For Windows® 8, or macOS X Yosemite 10.10.x or earlier, install Docker Desktop{: external} instead.

     For more information about the version of Docker that is supported by {{site.data.keyword.registrylong_notm}}, see Support for Docker.

   • Install Podman{: external}.

2. Download (pull) the image to your local computer. Replace SOURCE_IMAGE with the repository of the image and TAG with the tag of the image that you want to use, for example, latest. For example, depending on the tool that you are using, run one of the following commands.

   • If you are using Docker, run the following command.

     docker pull SOURCE_IMAGE:TAG

     {: pre}

     Example, where SOURCE_IMAGE is hello-world and TAG is latest:

     docker pull hello-world:latest

     {: pre}

     If you have a problem when you try to pull a Docker image, see Why can't I push or pull a Docker image? for assistance. If you can't pull the most recent image by using the latest tag, see Why can't I pull the newest image by using the latest tag? for assistance. {: tip}

   • If you are using Podman, run the following command.

     podman pull SOURCE_IMAGE:TAG

     {: pre}

     Example, where SOURCE_IMAGE is hello-world and TAG is latest:

     podman pull hello-world:latest

     {: pre}

Tag the image

{: #gs_registry_images_tag} {: step} {: help} {: support}

To tag the image, replace SOURCE_IMAGE with the repository and TAG with the tag of your local image that you pulled earlier. Replace REGION with the name of your region. Replace MY_NAMESPACE with the namespace that you created in Set up a namespace. Define the repository and tag of the image that you want to use in your namespace by replacing NEW_IMAGE_REPO with the name of your image repository and NEW_TAG with the tag. For example, depending on the tool that you are using, run one of the following commands.

To find the name of your region, run the ibmcloud cr region command. {: tip}

• If you are using Docker, run the following command.

  docker tag SOURCE_IMAGE:TAG REGION.icr.io/MY_NAMESPACE/NEW_IMAGE_REPO:NEW_TAG

  {: pre}

  Example, where SOURCE_IMAGE is hello-world, TAG is latest, REGION is uk, MY_NAMESPACE is namespace1, NEW_IMAGE_REPO is hw_repo, and NEW_TAG is 1:

  docker tag hello-world:latest uk.icr.io/namespace1/hw_repo:1

  {: pre}

• If you are using Podman, run the following command.

  podman tag SOURCE_IMAGE:TAG REGION.icr.io/MY_NAMESPACE/NEW_IMAGE_REPO:NEW_TAG

  {: pre}

  Example, where SOURCE_IMAGE is hello-world, TAG is latest, REGION is uk, MY_NAMESPACE is namespace1, NEW_IMAGE_REPO is hw_repo, and NEW_TAG is 1:

  podman tag hello-world:latest uk.icr.io/namespace1/hw_repo:1

  {: pre}

Push images to your namespace

{: #gs_registry_images_pushing} {: step} {: help} {: support}

1. Log in to {{site.data.keyword.registrylong_notm}} by using one of the following options.

   • To log in by using Docker, run the ibmcloud cr login command to log your local Docker daemon in to {{site.data.keyword.registrylong_notm}}.

     ibmcloud cr login --client docker

     {: pre}

   • To log in by using Podman, run the ibmcloud cr login command to log in to {{site.data.keyword.registrylong_notm}}.

     ibmcloud cr login --client podman

     {: pre}

   • 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 {{site.data.keyword.registryshort_notm}}? for assistance. {: tip}

2. Upload (push) the image to your namespace. Replace MY_NAMESPACE with the namespace that you created in Set up a namespace. Replace IMAGE_REPO and TAG with the repository and the tag of the image that you chose when you tagged the image. For example, depending on the tool that you are using, run one of the following commands.

   • If you are using Docker, run the following command.

     docker push REGION.icr.io/MY_NAMESPACE/IMAGE_REPO:TAG

     {: pre}

     Example, where REGION is uk, MY_NAMESPACE is namespace1, IMAGE_REPO is hw_repo, and TAG is 1:

     docker push uk.icr.io/namespace1/hw_repo:1

     {: pre}

     If you have a problem when you try to push a Docker image, see Why can't I push or pull a Docker image? for assistance. {: tip}

   • If you are using Podman, run the following command.

     podman push REGION.icr.io/MY_NAMESPACE/IMAGE_REPO:TAG

     {: pre}

     Example, where REGION is uk, MY_NAMESPACE is namespace1, IMAGE_REPO is hw_repo, and TAG is 1:

     podman push uk.icr.io/namespace1/hw_repo:1

     {: pre}

Verify that the image was pushed

{: #gs_registry_images_verify} {: step} {: help} {: support}

Verify that the image was pushed successfully by running the following command.

ibmcloud cr image-list

{: pre}

You set up a namespace in {{site.data.keyword.registrylong_notm}} and pushed your first image to your namespace.

Set up an audit trail for changes in {{site.data.keyword.registryshort_notm}}

{: #gs_registry_audit} {: step} {: help} {: support}

Create an audit trail for changes in {{site.data.keyword.registryshort_notm}} by capturing activity events from each of your active {{site.data.keyword.registryshort_notm}} regions. Create these activity events in one, or more, instance of {{site.data.keyword.logs_full_notm}}.

To set up an audit trail, complete the following steps:

1. Set up {{site.data.keyword.logs_full_notm}}, see Getting started with {{site.data.keyword.logs_full_notm}}.
2. Set up {{site.data.keyword.atracker_full_notm}}, see Getting started with {{site.data.keyword.atracker_full_notm}}.
3. Configure an {{site.data.keyword.logs_full_notm}} target, see Configuring an {{site.data.keyword.logs_full_notm}} instance as a target.

For more information about logging, see About {{site.data.keyword.logs_full_notm}} and Logging for {{site.data.keyword.registryshort_notm}}.

For more information about activity events, see About {{site.data.keyword.atracker_full_notm}} and Activity tracking events for {{site.data.keyword.registryshort_notm}}.

Monitor metrics for {{site.data.keyword.registryshort_notm}}

{: #gs_registry_monitor} {: step} {: help} {: support}

You can create a {{site.data.keyword.mon_short}} instance in the region that you want to monitor and enable platform metrics for it. Alternatively, you can enable platform metrics on an existing {{site.data.keyword.mon_short}} instance in that region.

For more information about setting up metrics, see Enabling metrics for {{site.data.keyword.registryshort_notm}} and Getting started with {{site.data.keyword.mon_short}}.

Next steps in {{site.data.keyword.registryshort_notm}}

{: #gs_get_start_next}

• Manage image security with Vulnerability Advisor.
• Review your service plans.
• Store and manage more images in your namespace.
• Define access policies.
• Set up clusters and worker nodes.