---
name: solution-tutorials-cbr-enhanced-security
title: Enhance cloud security by applying context-based restrictions
description: This tutorial walks you through the process of implementing context-based restrictions (CBRs) in your IBM Cloud account. CBRs help you to secure the cloud environment further and move towards a zero trust architecture.
last-updated: 2025-10-16
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/solution-tutorials?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.

# Enhance cloud security by applying context-based restrictions
{: #cbr-enhanced-security}
{: toc-content-type="tutorial"}
{: toc-services="containers, cloud-object-storage, atracker, Registry, secrets-manager, appid, Cloudant, key-protect, cloud-logs"}
{: toc-completion-time="2h"}
{: toc-use-case="Cybersecurity"}

This tutorial may incur costs. Use the [Cost Estimator](https://cloud.ibm.com/estimator) to generate a cost estimate based on your projected usage.
{: tip}


This tutorial walks you through the process of implementing [context-based restrictions](https://cloud.ibm.com/docs/account?topic=account-context-restrictions-whatis&format=markdown) (CBRs) in your IBM Cloud account. CBRs help you to secure the cloud environment further and move towards a [zero trust architecture](https://en.wikipedia.org/wiki/Zero_trust_architecture){: external}.
{: shortdesc}

The tutorial discusses how to create network zones and context rules and how to verify that they work. In the tutorial, you learn how to create the CBR objects both in the browser console and as Infrastructure as Code with Terraform. You will also learn about criteria on how to define the access strategy for your cloud resources.

## Objectives
{: #cbr-security-objectives}

* Learn about context-based restrictions to protect your cloud resources
* Define network zones to identify traffic sources for allowed and denied access
* Create rules that define context for access to your cloud resources
* Know how to test and monitor context rules

The following diagram shows the solution architecture as used in the tutorial [Apply end to end security to a cloud application](https://cloud.ibm.com/docs/solution-tutorials?topic=solution-tutorials-cloud-e2e-security&format=markdown). The additional boxes with dashed, blue lines around the Kubernetes Service cluster, Container Registry, Key Protect, and Object Storage denote context-based restrictions implemented as context rules. Note that Secrets Manager could have been protected, too, but is only an optional service and not used in this tutorial.

![Architecture](images/solution67-cbr-enhanced-security/architecture-e2e-security-cbr.svg){: caption="Solution architecture" caption-side="bottom"}

## Before you begin
{: #cbr-security-prereqs}

This tutorial requires:
* IBM Cloud CLI,
* `docker` client to push and pull container images.

You will find instructions to download and install these tools for your operating environment in the [Getting started with solution tutorials](https://cloud.ibm.com/docs/solution-tutorials?topic=solution-tutorials-tutorials&format=markdown) guide.

To avoid the installation of these tools you can use the [Cloud Shell](https://cloud.ibm.com/shell) from the IBM Cloud console.
{: tip}


## Setup
{: #cbr-security-setup}
{: step}

In a later step, [Use Terraform to configure context-based restrictions](#cbr-security-terraform), you are going to deploy CBR objects as additional security layer on top of the resources used in the tutorial [Apply end to end security to a cloud application](https://cloud.ibm.com/docs/solution-tutorials?topic=solution-tutorials-cloud-e2e-security&format=markdown).

1. [Deploy resources using Terraform managed by Schematics](https://github.com/IBM-Cloud/secure-file-storage#deploy-resources-using-terraform-managed-by-schematics){: external} as described in the companion GitHub repository.

2. The [IBM Cloud Activity Tracker Event Routing](https://cloud.ibm.com/docs/atracker?topic=atracker-about&format=markdown) must be configured to route auditing events to an IBM Cloud Logs target instance. Route audit events as described in [configuring an IBM Logs target](https://cloud.ibm.com/docs/atracker?topic=atracker-getting-started-target-cloud-logs&format=markdown) if not currently configured in your account.

## Overview: Context-based restrictions
{: #cbr-security-strategy-overview}
{: step}

[Context-based restrictions (CBRs)](https://cloud.ibm.com/docs/account?topic=account-context-restrictions-whatis&format=markdown) provide the ability to define and enforce access restrictions for IBM Cloud resources based on the network location and the type of access requests. Because both IAM policies and context-based restrictions enforce access, context-based restrictions offer protection even in the face of compromised or mismanaged credentials.

A rule governs access to a resource identified by its service name and type as well as by additional attributes. They can include the region, resource group, and other service-specific properties. The attributes in a rule are mostly optional, so that you could govern, e.g., all Key Protect instances together, or target just a specific key ring in an identified Key Protect instance.

The context for a restriction is made up of network zones and service endpoints. You might want to define zones based on specific IP addresses or ranges, or by configuring traffic originating from one or more VPCs or cloud services. With that, access to the sample Key Protect instance might only be allowed from, e.g., a specific Object Storage instance, a well-known range of IP addresses, and only via the private endpoint.

Network zones can be used for the definition of multiple rules. Rules have an enforcement mode which is one of disabled, report-only, or enabled.

At the moment, not all cloud services support the report-only mode. Moreover, these services also do not generate any CBR-related log entries when enabled. Check the individual service documentation for details.
{: note}

![Context-based restrictions](images/solution67-cbr-enhanced-security/CBR-diagram.svg){: caption="A diagram that shows how context-based restrictions work" caption-side="bottom"}


## Create zone and rule
{: #cbr-security-zone-rule-create}
{: step}

For evaluating the impact of context-based restrictions, you are going to create a rule governing the access to a namespace in Container Registry. You start by creating that namespace, then a network zone to identify a VPC as traffic source.

1. Go to the [Container Registry namespaces](https://cloud.ibm.com/registry/namespaces) and note the name of the namespace configured earlier.
2. In the [IBM Cloud](/) console, click on the **Manage** menu and select [**Context-based restrictions**](https://cloud.ibm.com/context-based-restrictions). In the overview page, click on **Create a network zone**.
3. Enter **VPCzone** as name. Under **Allowed VPCs**, select the one with your Kubernetes Service cluster. Click **Next** to review, then **Create** the zone.
4. Next, create a rule using the zone by clicking on **Rules** in the navigation on the left, then **Create**.
5. Select **Container Registry** in the **Service** section and click **Next**.
5. Leave the **APIs** section with **All** Service APIs click **Next**.
6. Then, under **Resources**, choose **Specific resources**. Pick **Resource Type** as attribute and specify **namespace** as value. Add another condition and configure **Resource Name** as **NAMESPACE** (the same value as in step 1). Click **Review**, then **Continue**.
7. Select the **VPCzone** you created earlier from the list. Then use **Add** and **Continue** to get to the last step of the dialog. Mark the **Enforcement** as **Report-only**. Thereafter, **Create** the rule.

Be aware that CBR zones and rules are deployed asynchronously. It may take up to few minutes for them to become active (eventually consistent).
{: note}

## Test the rule and its enforcement modes
{: #cbr-security-in-action}
{: step}

1. In a new browser tab, open the [IBM Cloud Logs service](https://cloud.ibm.com/observability/logging){: external} and select the **Cloud Logs** tab and click the name of the instance that is receiving the auditing events.
2. Start a new session of [IBM Cloud Shell](https://cloud.ibm.com/shell) in another browser tab.
3. In the shell, perform the following commands:
   Set an environment variable to the cloud region you are going to use for the Container Registry, e.g., **us** or **de**.
   ```sh
   export REGION=us
   ```
   {: codeblock}

   Set another variable for the Container Registry namespace:
   ```sh
   export NAMESPACE=<YOUR_NAMESPACE>
   ```
   {: codeblock}

   Now log in to the Container Registry.
   ```sh
   ibmcloud cr login
   ```
   {: codeblock}

   Next, pull a container image to the shell environment.
   ```sh
   docker pull docker.io/library/hello-world:latest
   ```
   {: codeblock}

   Re-tag the image to upload it to your registry namespace.
   ```sh
   docker tag docker.io/library/hello-world $REGION.icr.io/$NAMESPACE/hello-world
   ```
   {: codeblock}

   Last, push the container image to the registry.
   ```sh
   docker push $REGION.icr.io/$NAMESPACE/hello-world
   ```
   {: codeblock}

4. Switch to the browser tab with the IBM Cloud Logs showing auditing logs. When in report mode, log entries are written to IBM Cloud Activity Tracker Event Routing when a rule matches, regardless of the decision outcome. The log record has details on the request. In the image below, the rule to allow access to a Container Registry namespace matched in report mode.

   ![Verify rules in report mode](images/solution67-cbr-enhanced-security/CBR_rule_warning_registry.png){: caption="A context restriction matched in reporting mode" caption-side="bottom"}

   As discussed, in report mode, all matching requests generate a log entry. In the event details you see an attribute **decision** with a value of either **Permit** or **Deny**. In the screenshot above it is **Deny**.

5. Back in the browser tab with the shell, list the container images in the namespace.
   ```sh
   ibmcloud cr images --restrict $NAMESPACE
   ```
   {: codeblock}

6. In a third browser tab, navigate to the [CBR rules](https://cloud.ibm.com/context-based-restrictions/rules). Next to the registry-related rule you created earlier, click on the dot menu and select **Edit**. Go to **Describe your rule (Step 3)** and switch the rule from **Report-only** to **Enabled**. Activate the change by pressing the **Apply** button.
7. Go back to the browser tab with IBM Cloud Shell. Issue the same command as before to list the images:
   ```sh
   ibmcloud cr images --restrict $NAMESPACE
   ```
   {: codeblock}

   This time, it should result in an error message that you are not authorized.
8. In the browser tab with the logs, you should find a new record similar to the following:
   ![Verify rules in enforced mode](images/solution67-cbr-enhanced-security/CBR_rule_denied_registry.png){: caption="A context restriction rendered a deny" caption-side="bottom"}


   The rule has been enforced and, based on how you tried to access the registry, the access has been denied. The reason is that rule allows access from a specific VPC only. The Cloud Shell environment and its IP address, as documented in the logs in the **requestData->environment** fields, differ. Therefore, the request is denied.

When working with the IBM Cloud Logs logs, you can utilize query strings like the following to easily find the relevant log records:
- When in report mode, `"context restriction" permit OR deny` returns the log lines with access which would have rendered a **Permit** or **Deny**.
- In report mode, you can use `"context restriction" permit` to only show access which would have been permitted. Similarly, use `"context restriction" deny` for denied access.
- Last, when in **enforced** mode, use a query string like `context restriction rendered` for log lines related to denied access.

Monitoring a new rule is recommended for 30 days prior to enforcing it. Learn more about [**Monitoring context-based restrictions**](https://cloud.ibm.com/docs/account?topic=account-cbr-monitor&format=markdown) both in report-only and enabled mode in the CBR documentation.
{: tip}

In order to prepare for the deployment of CBR objects with Terraform in a section further down, go to the browser tab with the [CBR rules](https://cloud.ibm.com/context-based-restrictions/rules). There, delete the previously created rule by clicking on its dot menu and selecting **Remove** and then confirming with **Delete**. Thereafter, click on **Network zones** and delete the previously created zone.

## Define the access strategy for your cloud resources
{: #cbr-security-strategy}
{: step}

To set up the right set of rules for context-based restrictions (CBRs), you should have defined the access strategy for your cloud resources. All resources should be protected by identity and access management (IAM). It means, that authentication and authorization checks should be performed before a user or service ID accesses a resource. CBRs add to the protection by cutting off network access based on origin criteria and other rules, but they do not replace proper IAM configuration. Additionally, many services support limiting network traffic to private endpoints, thereby already reducing access options.

You might find that some rules impact the comfort of administrating resources, e.g., through the browser console. Moreover, you need to make sure that you don't deny yourself access to resources, management dashboards and APIs. Thus, you have to account for bastion hosts, corporate networks, gateways and maybe even Cloud Shell. In addition, some services support a fine-grained distinction of data plane and control place access for CBR configuration, e.g., [Kubernetes Service cluster and management APIs](https://cloud.ibm.com/docs/containers?topic=containers-cbr&format=markdown#protect-api-types-cbr).

In summary, these questions should be asked:
* Are all resources protected by IAM and similar?
* How are the resources accessed, are they already limited to private endpoints where possible?
* Is it possible to separate data plane and control plane access?
* What is traffic related to usage, which to administrative work? How are emergencies handled?
* From where does the above traffic originate?

Use the report mode to be aware of activities matching the context-based restrictions. Do the rule-based decisions render a permit or deny? Does that match your expectation? To learn about activities and to handle them correctly with CBR rules, a test phase in reporting mode of at least a month is recommended. This allows for an iterative approach towards the desired set of network zones and context rules.

For this tutorial, we are going to define the following network zones:
* a zone for the Kubernetes Service cluster
* a zone for Object Storage
* for an IP range with the addresses of a home network (corporate or bastion) to serve as **homezone**

Thereafter, we are going to define context rules as follows:
* for the access to the [Key Protect instance](https://cloud.ibm.com/docs/key-protect?topic=key-protect-access-control-with-cbr&format=markdown) from zones:
   * Kubernetes Service cluster
   * Object Storage
* for the access to the [Object Storage instance and its bucket](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-setting-a-firewall&format=markdown) from zones:
   * Kubernetes Service cluster
   * homezone
* for the access to the [Container Registry and the namespace with the container image](https://cloud.ibm.com/docs/Registry?topic=Registry-iam&format=markdown#iam_cbr) from zones:
   * Kubernetes Service cluster
* for the access to the [Kubernetes Service cluster and its management API](https://cloud.ibm.com/docs/containers?topic=containers-cbr&format=markdown#protect-api-types-cbr) from zones:
   * homezone

All the above zones and rules can be deployed in either report-only or enforced mode with a single Terraform command. Note that the rules are not meant for production use, but as a sample to investigate usage and traffic in report-only mode.

The documentation has a [list of resources which are supported as service references](https://cloud.ibm.com/docs/account?topic=account-context-restrictions-whatis&format=markdown#service-attribute). You can also retrieve the list using the [CLI command **service-ref-targets**](https://cloud.ibm.com/docs/cli?topic=cli-cbr-plugin&format=markdown#cbr-cli-service-ref-targets-command) or the related API function [List available service reference targets](https://cloud.ibm.com/apidocs/context-based-restrictions#list-available-serviceref-targets).
{: tip}


## Use Terraform to configure context-based restrictions
{: #cbr-security-terraform}
{: step}

Instead of manually creating the network zones and context rules for a project, it is recommended to automate the deployment. Context-based restrictions can be deployed utilizing Infrastructure as Code (IaC) - namely [Terraform code](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?format=markdown). You can first deploy the zones and rules with rules in report-only mode for testing. Then, after thorough tests, switch to enforced mode by updating the deployed configuration.

### Terraform resources for zones and rules
{: #cbr-security-terraform-resources}


In the following, you will deploy the Terraform code to create a basic set of network zones and context rules. The code for zones is using the [**ibm_cbr_zone**](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/cbr_zone){: external} resource. The following shows a zone specification which identifies the Kubernetes cluster. Such a cluster is one of the [supported service references](https://cloud.ibm.com/docs/account?topic=account-context-restrictions-whatis&format=markdown#service-attribute).

```hcl
resource "ibm_cbr_zone" "cbr_zone_k8s" {
  account_id = data.ibm_iam_account_settings.team_iam_account_settings.account_id
  addresses {
    type = "serviceRef"
    ref {
      account_id       = data.ibm_iam_account_settings.team_iam_account_settings.account_id
      service_instance = data.ibm_container_vpc_cluster.cluster.id
      service_name     = "containers-kubernetes"
    }
  }
  description = "Zone with the Kubernetes cluster"
  name        = "cbr_zone_k8s"
}
```
{: codeblock}


The code for rules is using the [**ibm_cbr_rule**](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/cbr_rule){: external} resource. The Terraform configuration for a typical rule is shown below.
Similar to the browser UI, it has the following elements:
* Contexts to specify the zones
* Enforcement mode
* Resources it applies to, identified by attributes

```hcl
resource "ibm_cbr_rule" "cbr_rule_cos_k8s" {
  contexts {
    attributes {
      name  = "networkZoneId"
      value = ibm_cbr_zone.cbr_zone_k8s.id
    }
  }
  contexts {
    attributes {
      name  = "networkZoneId"
      value = ibm_cbr_zone.cbr_zone_homezone.id
    }
  }

  description      = "restrict COS access, limit to cluster"
  enforcement_mode = var.cbr_enforcement_mode
  resources {
    attributes {
      name  = "accountId"
      value = data.ibm_iam_account_settings.team_iam_account_settings.account_id
    }
    attributes {
      name     = "serviceInstance"
      operator = "stringEquals"
      value    = var.cos.guid
    }
    attributes {
      name     = "serviceName"
      operator = "stringEquals"
      value    = "cloud-object-storage"
    }
  }
}
```
{: codeblock}

### Deploy the Terraform resources
{: #cbr-security-terraform-deploy}

With the understanding of the CBR-related Terraform resources, it is time to deploy them on top of the existing resources to create zones and rules.

1. In the browser, navigate to the [IBM Cloud Schematics workspaces](https://cloud.ibm.com/schematics/workspaces). Select the workspace with the existing resources from the earlier setup.
2. Click on **Settings**. In the list of **Variables** and locate the row with **deploy_cbr**. Its value should be **false**, the default.
3. In the dot menu for the variable select **Edit**. Then, in the pop-up form, uncheck **Use default** to be able to change the value. Type **true** in the field for **Value of the variable called: deploy_cbr**. Thereafter, finish the update by clicking **Save**.
4. Once the settings page has updated, continue with **Generate plan** in the top. The plan output should indicate that CBR zones and rules would be created.
5. Create the CBR objects by using the **Apply plan** button.

By default, the enforcement mode is configured to **report-only**. You can change the variable **cbr_enforcement_mode** to the value **enabled** to enforce the restrictions.
{: tip}


## Test the context rules
{: #cbr-security-terraform-test}
{: step}

With the set of context-based restrictions deployed, it is time again to verify and test them. To verify the CBR objects, go to the [context-based restrictions overview](https://cloud.ibm.com/context-based-restrictions). Then, inspect the new [zones](https://cloud.ibm.com/context-based-restrictions/zones) and [rules](https://cloud.ibm.com/context-based-restrictions/rules).

Tests should be performed on Container Registry, Object Storage and Key Protect and validated by monitoring the logs as performed earlier. Because the zones and rules include an access restriction on the Container Registry, you can repeat the tests performed in section [Test the rule and its enforcement modes](#cbr-security-in-action).

To test the new rule for access to Object Storage, follow these steps:
1. In a browser tab, go to the [list of Object Storage instances](https://cloud.ibm.com/objectstorage). Click on the service name for the tutorial, e.g., **secure-file-storage-cos**.
2. In a second browser tab, visit the already used IBM Cloud Logs dashboard with the auditing logs.
3. Back in the tab with the Object Storage overview, in the list of **Buckets**, click on the storage bucket.
4. Use **Upload** to import a file into the bucket. Leave the setting as **Standard transfer** and use the **Upload files (objects)** area to select a file. Finish by clicking **Upload**.
5. Back in the browser tab with the auditing logs, there should be CBR-related log records titled `Context restriction matched while in report mode`. This is due to the fact that the rules have been deployed in **report** mode. Expand some records to check the reported **decision** and **isEnforced** data. Depending on the configured IP range for the homezone, **decision** might be **Permit** or **Deny**. The value for **isEnforced** should be **false** because of the reporting mode.

For further testing, you might want to change the IP range of the homezone. It is the variable **homezone_iprange** in the Schematics settings.

## Remove resources
{: #cbr-security-remove}
{: removeresources}


To remove the resource, use the browser and navigate to the [IBM Cloud Schematics workspaces overview](https://cloud.ibm.com/schematics/workspaces). Select the workspace, then in the **Actions** menu, first select **Destroy resources**, thereafter use **Delete workspace**.

## Related content
{: #cbr-security-12}
{: related}

* [What is Zero Trust?](https://www.ibm.com/think/topics/zero-trust){: external}
* [Best practices for organizing users, teams, applications](https://cloud.ibm.com/docs/account?topic=account-account_setup&format=markdown)