Understanding RBAC permissions

What are the types of RBAC roles?

• A Kubernetes role is scoped to resources within a specific namespace, such as a deployment or service.
• A Kubernetes cluster role is scoped to cluster-wide resources, such as worker nodes, or to namespace-scoped resources that can be found in each namespace, like pods.

What are RBAC role bindings and cluster role bindings?

Role bindings apply RBAC roles or cluster roles to a specific namespace. When you use a role binding to apply a role, you give a user access to a specific resource in a specific namespace. When you use a role binding to apply a cluster role, you give a user access to namespace-scoped resources that can be found in each namespace, like pods, but only within a specific namespace.

Cluster role bindings apply RBAC cluster roles to all namespaces in the cluster. When you use a cluster role binding to apply a cluster role, you give a user access to cluster-wide resources, like worker nodes, or to namespace-scoped resources in every namespace, like pods.

What do these roles look like in my cluster?

If you want users to be able to interact with Kubernetes resources from within a cluster, you must assign user access to one or more namespaces through IBM Cloud IAM service access roles. Every user who is assigned a service access role is automatically assigned a corresponding RBAC cluster role. These RBAC cluster roles are predefined and permit users to interact with Kubernetes resources in your cluster. Additionally, a role binding is created to apply the cluster role to a specific namespace, or a cluster role binding is created to apply the cluster role to all namespaces.

To learn more about the actions permitted by each RBAC role, check out the IBM Cloud IAM service access roles reference topic. To see the permissions that are granted by each RBAC role to individual Kubernetes resources, check out Kubernetes resource permissions per RBAC role.

Can I create custom roles or cluster roles?

If you are making your own custom RBAC policies, make sure that you do not edit the existing IBM role bindings that are in the cluster, or create custom role bindings with the same name as the existing IBM bindings. Changes that you make to the IBM-provided RBAC role bindings are not retained on updates.

The view, edit, admin, and cluster-admin cluster roles are predefined roles that are automatically created when you assign a user the corresponding IBM Cloud IAM service access role. To grant other Kubernetes permissions, you can create custom RBAC permissions. Custom RBAC roles are in addition to and don't change or override any RBAC roles that you might have assigned with service access roles. Note that to create custom RBAC permissions, you must have the IAM Manager service access role that gives you the cluster-admin Kubernetes RBAC role. However, the other users don't need an IAM service access role if you manage your own custom Kubernetes RBAC roles.

When do I need to use custom cluster role bindings and role bindings?

You might want to authorize who can create and update pods in your cluster. With pod security policies (PSPs), you can use existing cluster role bindings that come with your cluster, or create your own.

You might also want to integrate add-ons to your cluster. For example, when you set up Helm in your cluster

Creating custom RBAC permissions for users, groups, or service accounts

The view, edit, admin, and cluster-admin cluster roles are automatically created when you assign the corresponding IBM Cloud IAM service access role. Do you need your cluster access policies to be more granular than these predefined permissions allow? No problem! You can create custom RBAC roles and cluster roles.

You can assign custom RBAC roles and cluster roles to individual users, groups of users, or service accounts. When a binding is created for a group, it affects any user that is added or removed from that group. When you add users to a group, they get the access rights of the group in addition to any individual access rights that you grant them. If they are removed, their access is revoked. Note that you can't add service accounts to access groups.

If you want to assign access to a container process that runs in pods, such as a continuous delivery toolchain, you can use Kubernetes ServiceAccounts. To follow a tutorial that demonstrates how to set up service accounts for Travis and Jenkins and to assign custom RBAC roles to the service accounts, see the blog post Kubernetes ServiceAccounts for use in automated systems.

To prevent breaking changes, don't change the predefined view, edit, admin, and cluster-admin cluster roles. Custom RBAC roles are in addition to and don't change or override any RBAC roles that you might have assigned with IBM Cloud IAM service access roles.

• Namespace access: To allow a user, access group, or service account to access a resource within a specific namespace, choose one of the following combinations:

  • Create a role, and apply it with a role binding. This option is useful for controlling access to a unique resource that exists only in one namespace, like an app deployment.
  • Create a cluster role, and apply it with a role binding. This option is useful for controlling access to general resources in one namespace, like pods.

• Cluster-wide access: To allow a user or an access group to access cluster-wide resources or resources in all namespaces, create a cluster role, and apply it with a cluster role binding. This option is useful for controlling access to resources that are not scoped to namespaces, like worker nodes, or resources in all namespaces in your cluster, like pods in each namespace.

• Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

• Ensure you that have the Manager IAM service access role for all namespaces.

• To assign access to individual users or users in an access group, ensure that the user or group has been assigned at least one IAM platform access role at the IBM Cloud Kubernetes Service service level.

To create custom RBAC permissions,

1. Create a .yaml file similar to the following to define the role or cluster role.

   kind: Role
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
       namespace: default
       name: my_role
   rules:
   - apiGroups: [""]
       resources: ["pods"]
       verbs: ["get", "watch", "list"]
   - apiGroups: ["apps", "extensions"]
       resources: ["daemonsets", "deployments"]
       verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
   

   Understanding the YAML parameters

   Parameter	Description
   kind	Use Role to grant access to resources within a specific namespace. Use ClusterRole to grant access to cluster-wide resources such as worker nodes, or to namespace-scoped resources such as pods in all namespaces.
   metadata.namespace	For kind Role only: Specify the Kubernetes namespace to which access is granted.
   rules.apiGroups	Specify the Kubernetes API groups that you want users to be able to interact with, such as "apps", "batch", or "extensions". For access to the core API group at REST path api/v1, leave the group blank: [""].
   rules.resources	Specify the Kubernetes resource types to which you want to grant access, such as "daemonsets", "deployments", "events", or "ingresses". If you specify "nodes", then the kind must be ClusterRole.
   rules.verbs	Specify the types of actions that you want users to be able to do, such as "get", "list", "describe", "create", or "delete".

2. Create the role or cluster role in your cluster.

   kubectl apply -f my_role.yaml
   

3. Verify that the role or cluster role is created.

   • Role:

     kubectl get roles -n <namespace>
     

   • Cluster role:

     kubectl get clusterroles
     

4. Bind users to the role or cluster role by creating a .yaml file. Note the unique URL to use for each subject's name.

   kind: RoleBinding
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
       name: my_role_binding
       namespace: default
   subjects:
   - kind: User
       name: IAM#user1@example.com
       apiGroup: rbac.authorization.k8s.io
   - kind: Group
       name: team1
       apiGroup: rbac.authorization.k8s.io
   - kind: ServiceAccount
       name: <service_account_name>
       namespace: <kubernetes_namespace>
   roleRef:
       kind: Role
       name: my_role
       apiGroup: rbac.authorization.k8s.io
   

   Understanding the YAML parameters

   Parameter	Description
   kind	Specify RoleBinding for a namespace-specific Role or ClusterRole. Specify ClusterRoleBinding for a cluster-wide ClusterRole.
   apiVersion	For clusters that run Kubernetes 1.8 or later, use rbac.authorization.k8s.io/v1. For earlier versions, use apiVersion: rbac.authorization.k8s.io/v1beta1.
   metadata.namespace	For kind RoleBinding: Specify the Kubernetes namespace to which access is granted. For kind ClusterRoleBinding: Don't use the namespace field.
   metadata.name	Name the role binding or cluster role binding.
   subjects.kind	Specify the kind as one of the following: User: Bind the RBAC role or cluster role to an individual user in your account. Group: Bind the RBAC role or cluster role to an IBM Cloud IAM access group in your account. ServiceAccount: Bind the RBAC role or cluster role to a service account in a namespace in your cluster.
   subjects.name	For User: Append the individual user's email address to IAM# as follows: IAM#user@email.com. For Group: Specify the name of the IBM Cloud IAM access group in your account. For ServiceAccount: Specify the service account name.
   subjects.apiGroup	For User or Group: Use rbac.authorization.k8s.io. For ServiceAccount: Don't include this field.
   subjects.namespace	For ServiceAccount only: Specify the name of the Kubernetes namespace that the service account is deployed to.
   roleRef.kind	Enter the same value as the kind in the role .yaml file: Role or ClusterRole.
   roleRef.name	Enter the name of the role .yaml file.
   roleRef.apiGroup	Use rbac.authorization.k8s.io.

5. Create the role binding or cluster role binding resource in your cluster.

   kubectl apply -f my_role_binding.yaml
   

6. Verify that the binding is created.

   kubectl get rolebinding -n <namespace>
   

7. Optional: To enforce the same level of user access in other namespaces, you can copy the role bindings for those roles or cluster roles to other namespaces.

   1. Copy the role binding from one namespace to another namespace.

      kubectl get rolebinding <role_binding_name> -o yaml | sed 's/<namespace_1>/<namespace_2>/g' | kubectl -n <namespace_2> create -f -
      

      For example, copy the custom-role role binding from the default namespace to the testns namespace.

      kubectl get rolebinding custom-role -o yaml | sed 's/default/testns/g' | kubectl -n testns create -f -
      

   2. Verify that the role binding is copied. If you added an IBM Cloud IAM access group to the role binding, each user in that group is added individually, not as an access group ID.

      kubectl get rolebinding -n <namespace_2>
      

Now that you created and bound a custom Kubernetes RBAC role or cluster role, follow up with users. Ask them to test an action that they have permission to complete due to the role, such as deleting a pod.

Extending existing permissions by aggregating cluster roles

You can extend your users' existing permissions by aggregating, or combining, cluster roles with other cluster roles. When you assign a user an IBM Cloud service access role, the user is added to a corresponding Kubernetes RBAC cluster role. However, you might want to allow certain users to perform additional operations.

For example, a user with the namespace-scoped admin cluster role can't use the kubectl top pods command to view pod metrics for all the pods in the namespace. You might aggregate a cluster role so that users in the admin cluster role are authorized to run the top pods command. For more information, see the Kubernetes docs.

Error from server (Forbidden): pods.metrics.k8s.io is forbidden: User "IAM#myname@example.com" can't list resource "pods" in API group "metrics.k8s.io" in the namespace "mynamespace"

Checking RBAC roles

Verify your custom RBAC or synchronized IAM service access to RBAC roles in your IBM Cloud Kubernetes Service cluster.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  creationTimestamp: 2018-05-23T14:34:24Z
  name: ibm-view
  namespace: default
  resourceVersion: "8192510"
  selfLink: /apis/rbac.authorization.k8s.io/v1/namespaces/default/rolebindings/ibm-view
  uid: 63f62887-5e96-11e8-8a75-b229c11ba64a
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: IAM#user@email.com
- apiGroup: rbac.authorization.k8s.io
  kind: group
  name: team1

Kubernetes service access roles and corresponding RBAC roles

The following table shows the Kubernetes resource permissions that are granted by each service access role and its corresponding RBAC role.