IBM Cloud Docs
Protecting cluster resources with context-based restrictions

Protecting cluster resources with context-based restrictions

Context-based restrictions give account owners and administrators the ability to define and enforce access restrictions for IBM Cloud® resources based on the context of access requests. Access to IBM Cloud Kubernetes Service resources can be controlled with context-based restrictions and identity and access management policies.

These restrictions work with traditional IAM policies, which are based on identity, to provide an extra 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. Since both IAM access and context-based restrictions enforce access, context-based restrictions offer protection even in the face of compromised or mismanaged credentials. For more information, see What are context-based restrictions.

A user must have the Administrator role on the IBM Cloud Kubernetes Service service to create, update, or delete rules. And a user must have either the Editor or Administrator role on the Context-based restrictions service to create, update, or delete network zones.

Any Activity Tracker or audit log events generated come from the context-based restrictions service, and not IBM Cloud Kubernetes Service. For more information, see Monitoring context-based restrictions.

Attempts to access the cluster control plane, which can be restricted by using the Cluster API type, do not generate Activity Tracker or audit log events.

How IBM Cloud Kubernetes Service integrates with context-based restrictions

You can create context-based restrictions (CBR) for IBM Cloud Kubernetes Service resources or for specific APIs. With Context-based restrictions, you can protect the following resources.

Protect IBM Cloud Kubernetes Service resources
Restrict access to clusters, resource groups, or regions.
Protect specific APIs
Restrict accessing to provisioning and managing clusters and workers. Or, restrict access to Kubernetes APIs such as viewing pods and nodes. For more information, see Protecting specific APIs.

Applications running on IBM Cloud Kubernetes Service clusters, for example web servers exposed by a Kubernetes LoadBalancer are not restricted by CBR rules.

Protecting cluster resources

You can create CBR rules to protect specific regions, and clusters.

Cluster
Protects a specific IBM Cloud Kubernetes Service cluster. If you select a cluster in your CBR rule, only traffic from resources in the network zones that you associate with the rule can interact with that cluster.
If you use the CLI, you can specify the --service-instance CLUSTER-ID option to protect a specific cluster.
If you use the API, you can specify "name": "serviceInstance","value": "CLUSTER-ID" in the resource attributes.
Region
Protects IBM Cloud Kubernetes Service resources in a specific region. If you select a region in your CBR rule, then only traffic from resources in the network zones that you associate with the rule can interact with resources in that region.
If you use the CLI, you can specify the --region REGION option to protect resources in a specific region.
If you use the API, you can specify "name": "region","value": "REGION" field in the resource attributes.
Resource group
Protects IBM Cloud Kubernetes Service resources in a specific resource group.
If you use the CLI, you can specify the --resource-group-id RESOURCE-GROUP-ID option to protect resources in a specific resource group.
If you use the API, you can specify "name": "resourceGroupId","value": "RESOURCE-GROUP-ID" field in the resource attributes.

Protecting specific APIs

You can create CBR rules to protect the following API types for IBM Cloud Kubernetes Service.

Cluster control plane APIs
Protect access to the APIs inside your clusters, such as the APIs for creating namespaces, pods, and more. CBR rules that apply to the cluster API type control access to your cluster API server, which includes all kubectl commands to that cluster. If you select the cluster control plane APIs in your CBR rule, then only traffic from resources in the network zones that associate with that rule can interact with the cluster control plane APIs. All other requests are blocked.
If you use the CLI, you can specify the --api-types option and the crn:v1:bluemix:public:containers-kubernetes::::api-type:cluster type.
If you use the API, you can specify "api_type_id": "crn:v1:bluemix:public:containers-kubernetes::::api-type:cluster" in the "operations" spec.
Management APIs
Protect access to the APIs for provisioning and managing clusters, worker pools, and more. CBR rules that apply to the management API type control access the IBM Cloud Kubernetes Service APIs, which includes all ibmcloud ks commands calls, such as ibmcloud ks clusters, ibmcloud ks cluster create, and more. If you select the management APIs in your CBR rule, then resources in the network zone that associate with the rule can interact with the management APIs.
If you use the CLI, you can specify the --api-types option and the crn:v1:bluemix:public:containers-kubernetes::::api-type:management type.
If you use the API, you can specify "api_type_id": "crn:v1:bluemix:public:containers-kubernetes::::api-type:management" in the "operations" spec.

To follow an example CBR scenario, see Setting up context-based restrictions.

Allowing IBM Cloud Kubernetes Service to access other IBM Cloud resources by using CBR

You must add the containers-kubernetes to your network zones for rules created against the following services.

IAM Identity service
Allow IBM Cloud Kubernetes Service to create tokens and API Keys like the cluster API Key and the IBM Cloud Container Registry token and API Key.
IAM Access Management Service
Allow IBM Cloud Kubernetes Service to create an IAM Access Policy for Reader service access role to IBM Cloud Container Registry.
IAM Access Groups Service
Allow IBM Cloud Kubernetes Service to look up access groups when syncing IAM access policies with RBAC in the cluster.
User Management
Allow IBM Cloud Kubernetes Service to access user information when syncing IAM access policies with RBAC in the cluster.
Key protect:
Allow IBM Cloud Kubernetes Service to enable encryption on the cluster.

Creating network zones

Network zones act as allowlists for the target resources you define when you create CBR rules. After you create a network zone, or allowlist, you can create rules that define which resources the network zone can access.

Make sure to add the containers-kubernetes service to your network zones for rules that apply to other IBM Cloud resources, such as a rule that protects IBM Cloud Object Storage or some cluster operations might fail. For more information, see Allowing IBM Cloud Kubernetes Service to access other IBM Cloud resources by using CBR.

Review the limitations before you create network zones.

Creating network zones from the API

You can create network zones by using the /v1/zones API. For more information, see the API docs. You can add the containers-kubernetes service to your network zones to allow IBM Cloud Kubernetes Service to access resources and services in your account.

You can include multiple address types in your network zone payload. For more information, see the example payload in the API docs.

Example payload to add IBM Cloud Kubernetes Service to a network zone. The serviceRef attribute for IBM Cloud Kubernetes Service is containers-kubernetes.

{
  "name": "Example zone 1",
  "description": "",
  "addresses": [
    {
      "type": "serviceRef",
      "ref": {
        "service_name": "containers-kubernetes",
        "account_id": "ACCOUNT-ID"
      }
    }
  ]
}

Example payload to add multiple services, IP addresses, and VPCs to a network zone.

{
  "name": "zone",
  "description": "",
  "addresses": [
    {
      "type": "ipAddress",
      "value": "192.168.0.0"
    },
    {
      "type": "vpc",
      "value": "crn:v1:bluemix:public:is:us-east:a/CRN"
    },
    {
      "type": "vpc",
      "value": "crn:v1:bluemix:public:is:us-south:a/CRN"
    },
    {
      "type": "serviceRef",
      "ref": {
        "service_name": "cloud-object-storage",
        "account_id": "ACCOUNT-ID"
      }
    },
    {
      "type": "serviceRef",
      "ref": {
        "service_name": "codeengine",
        "account_id": "ACCOUNT-ID"
      }
    },
    {
      "type": "serviceRef",
      "ref": {
        "service_name": "containers-kubernetes",
        "account_id": "ACCOUNT-ID"
      }
    },
    {
      "type": "serviceRef",
      "ref": {
        "service_type": "platform_service",
        "account_id": "ACCOUNT-ID"
      }
    },
    {
      "type": "serviceRef",
      "ref": {
        "service_name": "iam-groups",
        "account_id": "ACCOUNT-ID"
      }
    }
  ],
  "excluded": []
}

Creating network zones from the CLI

  1. To create network zones from the CLI, install the CBR CLI plug-in.

  2. You can use the cbr-zone-create command to add resources to network zones. For more information, see the CBR CLI reference. Note that the service_name for IBM Cloud Kubernetes Service is containers-kubernetes.

    To find a list of available service refs, run the ibmcloud cbr service-ref-targets command.

    Example command to add the containers-kubernetes service to a network zone.

    ibmcloud cbr zone-create --name example-zone-1 --description "Example zone 1" --service-ref service_name=containers-kubernetes
    

    The following example creates a network zone to allow a single public IP address to access. You can also use this example in conjunction with the one IP example rule. For more information about this scenario, see Setting up context-based restrictions.

    ibmcloud cbr zone-create --addresses 129.41.86.7 --description "Allow only client IP" --name allow-client-ip
    

Creating network zones from the console

  1. Determine the resources that you want add to your allowlist.
  2. Follow the steps to create context-based restrictions in the console. Add the Kubernetes service to your network zones to allow IBM Cloud Kubernetes Service to access services and resources in your account.

Creating rules

Define rules to protect access to resources in your account. The contexts that you define in your rules determine how the resources in your network zones (allowlists) can interact with the resources defined in the rule.

Review the limitations before you create rules.

Creating rules by using the API

Review the following example requests to create rules. For more information about the v1/rules API, see the API docs.

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.

The following example payload creates a rule that protects the CLUSTER-ID cluster. Only resources in the NETWORK-ZONE-ID zone can access the cluster. Since no operations are specified, resources in the NETWORK-ZONE-ID zone can access both the cluster and management APIs.

{
  "description": "Example rule 1",
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT-ID"
        },
        {
          "name": "serviceName",
          "value": "containers-kubernetes"
        },
        {
          "name": "serviceInstance",
          "value": "CLUSTER-ID"
        }
      ]
    }
  ],
  "contexts": [
    {
      "attributes": [
        {
          "name": "networkZoneId",
          "value": "NETWORK-ZONE-ID"
        },
        {
          "name": "endpointType",
          "value": "private"
        }
      ]
    }
  ]
}

The following example payload creates a rule that protects the CLUSTER-ID cluster. Only the resources defined in the NETWORK-ZONE-ID zone can access the cluster. Since the cluster API type is specified, resources in the NETWORK-ZONE-ID zone can access the cluster through the cluster APIs over the private network.

{
  "description": "Example rule 2",
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT-ID"
        },
        {
          "name": "serviceName",
          "value": "containers-kubernetes"
        },
        {
          "name": "serviceInstance",
          "value": "CLUSTER-ID"
        }
      ]
    }
  ],
  "operations": {
    "api_types": [
      {
        "api_type_id": "crn:v1:bluemix:public:containers-kubernetes::::api-type:cluster"
      }
    ]
  },
  "contexts": [
    {
      "attributes": [
        {
          "name": "networkZoneId",
          "value": "NETWORK-ZONE-ID"
        },
        {
          "name": "endpointType",
          "value": "private"
        }
      ]
    }
  ]
}

Creating rules from the CLI

  1. To create rules from the CLI, install the CBR CLI plug-in.
  2. You can use the ibmcloud cbr rule-create command to create CBR rules. For more information, see the CBR CLI reference. Note that the service_name for IBM Cloud Kubernetes Service is containers-kubernetes. To find a list of service names, run the ibmcloud cbr service-ref-targets command. To find a list of API types for a service, run the ibmcloud cbr api-types --service-name SERVICE command.

Example command to create a rule that uses the addresses key and the cluster API type and the ipAddress type.

ibmcloud cbr rule-create my-rule-1 --service-name containers-kubernetes --api-type crn:v1:bluemix:public:containers-kubernetes::::api-type:cluster --zone-id ZONE-ID

The following command creates a rule that protects the CLUSTER-ID cluster. Only resources in the NETWORK-ZONE-ID network zone can access the cluster. This rule includes both the cluster and management API types.

ibmcloud cbr rule-create my-rule-2 --service-name containers-kubernetes --service-instance CLUSTER-ID --zone-id NETWORK-ZONE-ID 

The following example command creates a rule that allows all private network connections, but allows only resources in the allow-client-ip network zone to connect to the cluster over the public network. For more information about this scenario, see Setting up context-based restrictions.

ibmcloud cbr rule-create --api-types crn:v1:bluemix:public:containers-kubernetes::::api-type:cluster --description "privateAccess=allowAll, publicAccess=oneIP" --service-name containers-kubernetes --service-instance CLUSTER-ID --context-attributes endpointType=private --context-attributes endpointType=public,networkZoneId=allow-client-ip

Creating rules from the console

  1. Review the available contexts and determine the rules you want to create.
  2. Follow the steps to create context-based restrictions in the console.

Limitations

  • After you create, enforce, or disable enforcement of a rule, it might take up to 10 minutes for the change to take effect.
  • IBM Cloud Kubernetes Service CBR rules that apply to all API types or the cluster API types must not reference network zones that contain IPv6 addresses. The APIs included in the cluster type don't support IPv6.
  • If you add IBM Cloud Kubernetes Service resources to private-only network zones, the APIs for getting and listing clusters are still accessible over the public network.
  • IBM Cloud Kubernetes Service CBR rules that apply to all API types or the cluster API types must not reference other services like IBM Cloud Object Storage or Key Protect
  • IBM Cloud Kubernetes Service CBR rules that apply to all API types or the cluster API type do not support Report-only enforcement for the cluster API type.
  • IBM Cloud Kubernetes Service CBR rules that apply to all API types or the cluster API types are limited to no more than 200 IPs/subnets for private rules, and 500 IPs/subnets for public rules.
  • Due to a limitation with how IBM Cloud Kubernetes Service fetches cluster details, the APIs for getting clusters and listing clusters are still accessible regardless of the CBR rules. This means clusters are still visible (read-only) in the console and CLI. When this limitation is addressed, you must add new rules to protect the APIs for getting clusters and listing clusters.
  • Some IBM Cloud Kubernetes Service clusters that were created before 8 October 2022 are not able to enforce public CBR rules for the cluster's APIserver. To check if your cluster supports these public cluster API type CBR rules, run the ibmcloud ks cluster get -c <CLUSTER-ID> command. If either of the Service Endpoint URLs starts with the https://cXXX (where XXX is any three digit number), then the cluster does support public CBR rules. If the Service Endpoint URLs starts with https://cX (where the number after the c is a single digit), then the cluster is not able to enforce public CBR rules for the cluster's APIserver. To use public CBR rules, you must create a new cluster.