---
name: Registry-registry_cbr
title: Securing Container Registry with context-based restrictions
description: Secure Container Registry by using context-based restrictions to define and enforce access rules based on the context of requests, in addition to IAM policies.
last-updated: 2026-08-11
---

> ## 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.

# Securing Container Registry with context-based restrictions
{: #registry-cbr}

Secure Container Registry by using context-based restrictions to define and enforce access rules based on the context of requests, in addition to IAM policies.
{: shortdesc}

These restrictions work with traditional IAM policies, which are based on identity, to provide another layer of protection. Unlike IAM policies, context-based restrictions don't assign access. Context-based restrictions check that an access request comes from an allowed context that you configure. Because both IAM access and context-based restrictions enforce access, context-based restrictions offer protection even in the face of compromised or mismanaged credentials. See [Layered security with context-based restrictions](https://cloud.ibm.com/docs/iam?topic=iam-context-restrictions-whatis&format=markdown) for more information.

A user must have the Administrator role on the Container Registry service to create, update, or delete rules. A user must also have either the Editor or Administrator role for context-based restrictions to create, update, or delete network zones. A user with the Viewer role for the context-based restrictions can add network zones to a rule.
{: note}

Any activity tracker audit events that are generated come from the context-based restrictions, not Container Registry. For more information, see [Monitoring context-based restrictions](https://cloud.ibm.com/docs/iam?topic=iam-cbr-monitor&format=markdown).

Container Registry is a service that is integrated with context-based restrictions. For more information, see [Services that are integrated with context-based restrictions](https://cloud.ibm.com/docs/iam?topic=iam-context-restrictions-whatis&format=markdown#cbr-adopters).

To find out how to protect your Container Registry resources with context-based restrictions, see the [Leveraging context-based restrictions to secure your resources](https://cloud.ibm.com/docs/iam?topic=iam-context-restrictions-tutorial&format=markdown) tutorial.

## How Container Registry integrates with context-based restrictions
{: #registry-cbr_overview}

You can create context-based restrictions for IBM Cloud Container Registry resources or for specific APIs. With context-based restrictions, you can protect resources, see [Protecting specific resources](#registry-cbr_protect).

## Protecting specific resources
{: #registry-cbr_protect}

When you set up context-based restrictions, the restrictions apply to everything for the selected service in the account unless you select a subset of resources. Container Registry supports the following subset of resources: `resource type = namespace` and `resource id = <your_image_namespace>`, where `<your_image_namespace>` is the namespace of your image. For more information about rules, see [Creating rules](https://cloud.ibm.com/docs/iam?topic=iam-context-restrictions-create&interface=ui&format=markdown#context-restrictions-create-rules).

For example, if your image is in the format `uk.icr.io/<my_project>/<my_image>:latest`, where `<my_project>` is the name of your project and `<my_image>` is the name of the image, the attribute types are as shown in the following table.

| Attribute type | Operator | Value |
| -------------- | -------- | ----- |
| `Region` | `string equals` | `London` |
| `Resource Type` | `string equals` | `namespace` |
| `Resource Name` | `string equals` | `<my_project>` |
{: caption="Example attribute types" caption-side="bottom"}
{: #table_registry_cbr_attributes}

The **Resource Name** value is a namespace, as shown by the [`ibmcloud cr namespace-list`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_namespace_list) command.

## Limitations
{: #registry-cbr_limitations}

Context-based restrictions protect only the actions that are associated with the [IBM Cloud Container Registry API](https://cloud.ibm.com/apidocs/container-registry) and the [Vulnerability Advisor 4 for IBM Cloud Container Registry API](https://cloud.ibm.com/apidocs/vulnerability-advisor). Actions that are associated with the following platform APIs are not protected by context-based restrictions. Reference the API documentation for the specific action IDs.

- [Resource Instance APIs](https://cloud.ibm.com/apidocs/resource-controller/resource-controller#list-resource-instances)
- [Resource Keys APIs](https://cloud.ibm.com/apidocs/resource-controller/resource-controller#list-resource-keys)
- [Resource Reclamations APIs](https://cloud.ibm.com/apidocs/resource-controller/resource-controller#list-reclamations)
- [IAM Policy APIs](https://cloud.ibm.com/apidocs/iam-policy-management#list-policies)
- [Global Search APIs](https://cloud.ibm.com/apidocs/search)
- [Global Tagging Attach tags](https://cloud.ibm.com/apidocs/tagging#attach-tag) API and [Global Tagging Detach tags](https://cloud.ibm.com/apidocs/tagging#detach-tag) API
- [Context-based Restriction Rule APIs](https://cloud.ibm.com/apidocs/context-based-restrictions#create-rule)
- [Secrets Manager APIs](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2)

## Creating rules
{: #registry-cbr_create_rules}

Define restrictions to Container Registry resources by creating rules.

### Creating rules in the IBM Cloud console
{: #registry-cbr_rules_ui}
{: ui}

To create rules in the IBM Cloud console, see [Creating rules](https://cloud.ibm.com/docs/iam?topic=iam-context-restrictions-create&interface=ui&format=markdown#context-restrictions-create-rules). When you are asked to select a service, select **Container Registry**. You can protect all resources, or specific resources, see [Protecting specific resources](#registry-cbr_protect).

The following attribute types for specific resources are available in the IBM Cloud console:

- `Region`
- `Resource Type`
- `Resource Name`

### Creating rules by using the CLI
{: #registry-cbr_rules_cli}
{: cli}

1. To create rules from the command-line interface (CLI), [install the context-based restrictions CLI plug-in](https://cloud.ibm.com/docs/cli?topic=cli-cbr-plugin&format=markdown#install-cbr-plugin).
2. You can use the [`ibmcloud cbr rule-create` command](https://cloud.ibm.com/docs/iam?topic=iam-cbr-plugin&format=markdown#cbr-cli-rule-create-command) to create rules for context-based restrictions. For more information, see [Creating rules by using the CLI](https://cloud.ibm.com/docs/iam?topic=iam-context-restrictions-create&interface=cli&format=markdown#context-restrictions-create-rules-cli).

The following example creates a rule that targets the Container Registry service and allows access to your namespace `my_namespace` only over the private network in `us-south`.

```txt
ibmcloud cbr rule-create --description 'Only allow access to my_namespace over the private network' --service-name container-registry --context-attributes endpointType=private --resource-attributes resourceType=namespace,resource=my_namespace --region us-south
```
{: pre}

### Creating rules by using the API
{: #registry-cbr_rules_api}
{: api}

To create rules in the API, see the [API docs](https://cloud.ibm.com/apidocs/context-based-restrictions#create-rule) and [Creating rules by using the API](https://cloud.ibm.com/docs/iam?topic=iam-context-restrictions-create&interface=api&format=markdown#context-restrictions-create-rules-api).

After you create a rule, it might take up to 10 minutes to before you can update that rule due to IAM TTL response caching.
{: note}

## Setting up region-based policies for context-based restrictions
{: #registry-cbr_region_policy}

For all regions other than `global` you can use the region field when you create a rule. So for example, in the CLI for `us-south` you use the `--region us-south` option. However, because `global` is a geography and not a region you must omit the `--region` option and add `geography=global` into the `--resource-attributes` field.

The following example shows the command in `us-south`, where `DESCRIPTION` is the description, `ACCOUNT_ID` is your IBM Cloud account ID, `NAMESPACE` is the namespace, and `NETWORK_ZONE_ID` is the network zone ID:

```txt
ibmcloud cbr rule-create --description "DESCRIPTION" --resource-attributes "accountId=ACCOUNT_ID,serviceName=container-registry,resourceType=namespace,resource=NAMESPACE" --context-attributes networkZoneId=NETWORK_ZONE_ID --output json --region us-south
```
{: pre}

The following example shows the command in `global`, where `DESCRIPTION` is the description, `ACCOUNT_ID` is your IBM Cloud account ID, `NAMESPACE` is the namespace, and `NETWORK_ZONE_ID` is the network zone ID:

```txt
ibmcloud cbr rule-create --description "DESCRIPTION" --resource-attributes "accountId=ACCOUNT_ID,serviceName=container-registry,resourceType=namespace,resource=NAMESPACE,geography=global" --context-attributes networkZoneId=NETWORK_ZONE_ID
```
{: pre}