Cleaning up your namespaces in Container Registry

You can clean up your namespaceA collection of repositories that store images in a registry. A namespace is associated with an IBM Cloud account, which can include multiple namespaces. by choosing to retain only the most recent images in each repository in that namespace in IBM Cloud® Container Registry.

You can also choose whether to delete or retain your untagged images.

You can detect and delete old images from all the repositories in a namespace by running a one-off command ibmcloud cr retention-run, or by scheduling a policy by running the ibmcloud cr retention-policy-set command. You can choose the number of images that you want to keep in each repository in a namespace, all other images are automatically deleted. Both options keep the most recent images. The age of the image is determined by when the image was created, not when it was pushed to the registryA storage and distribution service that contains public or private images that are used to create containers.. The number of images that are kept is the same for each repository in that namespace.

When you run the ibmcloud cr retention-run and ibmcloud cr retention-policy-set commands, a list of images to delete is displayed, and you must confirm that you want to delete those images. After you run the ibmcloud cr retention-policy-set command the first time, the policy runs automatically and deletes any images that meet the criteria that are specified in the policy. Deleted images are stored in the trash for 30 days.

If you want to check what's in the trash, run the ibmcloud cr trash-list command. You can restore images from the trash by running the ibmcloud cr image-restore command.

If you want to check your policies, you can run the ibmcloud cr retention-policy-list command.

If you want to cancel a policy, update the retention policy so that it keeps all your images.

You can also clean up your namespace by deleting your untagged images.

Planning retention

The ibmcloud cr retention-run and ibmcloud cr retention-policy-set commands operate on a per-namespace basis. If you have multiple namespaces in your pipeline, you can apply different retention criteria for each namespace to best suit your requirements.

Consider a typical delivery pipeline with development, staging, and production environments. As code is delivered, continuous integration and continuous deployment pushes images into the registry and then deploys them straight to your development environment. After testing, some builds from development are promoted to staging, and then potentially onto production. In this scenario, the rate of image change is fastest in development and slowest in production. If all your environments pull images from the same namespace, it can be difficult to choose an appropriate number of images to retain due to this difference in velocity.

A good approach is to deliver all images into a development namespace, for example project-development, and then to use the ibmcloud cr image-tag command to tag the image into a different namespace when it is promoted to a higher stage of the pipeline. In the previous example, you can have three namespaces: development project-development, staging project-staging, and production project-production. When you are promoting from development to staging, images are tagged from the project-development namespace into the project-staging namespace, and the images from the project-staging namespace are used for deployment. Similarly, when you are promoting from staging to production, images are tagged from the project-staging namespace into the project-production namespace, and the project-production namespace images are used in the production deployment.

You gain the following advantages by using this technique:

You can choose different retention settings for development, staging, and production namespaces.
You minimize the chances of accidentally removing an image that might be in use in your staging or production environments, when compared with using a single namespace for all images.
You can use different IAM policies. For example, you can have more restrictive access to production images.
You can sign production images, but leave development and staging images unsigned.

Some build tools like Cloud Native Buildpacks and distroless base images produce images with the build date set to a specific constant rather than the real build time or with no build timestamp at all. If you want to use retention policies on namespaces that contain images that are built by using similar tools, be aware that images that do not have a created date and images that were created before 2013-01-19T00:13:39Z are always retained.

For more information, see the following topics for assistance:

Clean up your namespaces to keep a set number of images

Use the ibmcloud cr retention-run command to clean up a namespace by retaining a specified number of images for each repository within a namespace in IBM Cloud Container Registry. All other images in the namespace are deleted.

You can choose whether to exclude untagged images from the clean-up process.

The ibmcloud cr retention-run command lists the images to delete and gives you the option to cancel before deletion.

Where an image, within a repository, is referenced by multiple tags, that image is counted only once. Newest images are retained. Age is determined by when the image was created, not when it was pushed to the registry.

If you want to restore a deleted image, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected image by running the ibmcloud cr image-restore command.

To reduce the number of images in each repository within your namespace by using the CLI, complete the following steps:

Log in to IBM Cloud by running the ibmcloud login command.
Choose the registry in which you want to clean up your images by running the following command and selecting the appropriate region:
```
ibmcloud cr region-set
```
To retain the most recent images and delete the others, run one the following commands:
- If you want to clean up both tagged and untagged images, run the following command:
```
ibmcloud cr retention-run --images <image_count> <namespace>
```
  Where <image_count> is the number of images that you want to retain for each repository within your namespace <namespace>.
- If you want to clean up tagged images only and retain all untagged images, run the following command:
```
ibmcloud cr retention-run --retain-untagged --images <image_count> <namespace>
```
  Where <image_count> is the number of images that you want to retain for each repository within your namespace <namespace>.
If an image that you're expecting to see doesn't show in the list that is produced, see Why doesn't the retention command show all the images? for assistance.
Verify that the images were deleted by running the following command, and check that the images do not show in the list.
```
ibmcloud cr image-list
```
If the listing images command times out, see Why is it timing out when I list images? for assistance.

Set a retention policy for your namespaces

You can set a retention policy for your namespaces to retain only images that meet your criteria. The retention policy runs automatically to clean up your namespaces.

You can choose whether to exclude untagged images from the clean-up process.

You can use the ibmcloud cr retention-policy-set command to set a policy that retains a specified number of images for each repository within a namespace in IBM Cloud Container Registry. All other images in the namespace are deleted and moved to the trash. When you set a policy it runs immediately, then it runs daily. You can set only one policy in each namespace.

If you delete an image in error, you can restore the image by using the ibmcloud cr trash-list and ibmcloud cr image-restore commands.

To set a policy and immediately move your deleted images to the trash, complete the following steps:

Log in to IBM Cloud by running the ibmcloud login command.
Choose the registry in which you want to clean up your images by running the following command and selecting the appropriate region:
```
ibmcloud cr region-set
```
To set a policy that retains the most recent images and deletes the others, run one of the following commands:
- If you want to clean up both tagged and untagged images, run the following command:
```
ibmcloud cr retention-policy-set --images <image_count> <namespace>
```
  Where <image_count> is the number of images that you want to retain for each repository within your namespace <namespace>.
  
  A list of images to delete is displayed.
- If you want to clean up tagged images only and retain all untagged images, run the following command:
```
ibmcloud cr retention-policy-set --retain-untagged --images <image_count> <namespace>
```
  Where <image_count> is the number of images that you want to retain for each repository within your namespace <namespace>.
  
  A list of images to delete is displayed.
Review the list of images. To run the policy and delete the images, confirm that you want to set the policy.

If you don't want to delete those images, choose No. The policy is not set and the images are not deleted.
Verify that the images were deleted by running the following command, and check that the images show in the list.
```
ibmcloud cr trash-list
```
Verify that the policy is set by running the ibmcloud cr retention-policy-list command, and check that the policy that you set for the namespace retains the required number of images. If you set the policy to retain all untagged images, ensure that the Retain all untagged column has the value true.
```
ibmcloud cr retention-policy-list
```

Update a retention policy to keep all your images

All namespaces have a default policy that keeps all images. You can return a policy to the default state.

You can use the ibmcloud cr retention-policy-set command to set the policy back to the default state by running the following command, where <namespace> is your namespace:

ibmcloud cr retention-policy-set --images All <namespace>

Clean up your namespaces by deleting untagged images

You can clean up your namespace and reduce your bills by deleting your untagged images in the namespace and optionally output the results in JSON format.

If you want to delete your untagged images and output the results in JSON format, run the following ibmcloud cr image-prune-untagged command, where <namespace> is your namespace:

ibmcloud cr image-prune-untagged [--force | -f [--output json]] --restrict <namespace>