diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md index a9ce6210f4..cf08a0b6d0 100644 --- a/docs/admin/authorization/rbac.md +++ b/docs/admin/authorization/rbac.md @@ -17,22 +17,23 @@ As of 1.6 RBAC mode is in beta. To enable RBAC, start the apiserver with `--authorization-mode=RBAC`. -## Roles, RolesBindings, ClusterRoles, and ClusterRoleBindings +## API Overview -The RBAC API Group declares four top level types which will be covered in this +The RBAC API declares four top-level types which will be covered in this section. Users can interact with these resources as they would with any other -API resource. Through `kubectl`, direct calls to the API, etc. For instance, +API resource (via `kubectl`, API calls, etc.). For instance, `kubectl create -f (resource).yml` can be used with any of these examples, though readers who wish to follow along should review the section on bootstrapping first. -In the RBAC API Group, roles hold a logical grouping of permissions. These -permissions map very closely to ABAC policies, but only contain information -about requests being made. Permissions are purely additive, rules may only omit -permissions they do not wish to grant. +### Role and ClusterRole -Here's an example of a role which grants read access to pods within the -"default" namespace. +In the RBAC API, a role contains rules that represent a set of permissions. +Permissions are purely additive (there are no "deny" rules). +A role can be defined within a namespace with a `Role`, or cluster-wide with a `ClusterRole`. + +A `Role` can only be used to grant access to resources within a single namespace. +Here's an example `Role` in the "default" namespace that can be used to grant read access to pods: ```yaml kind: Role @@ -41,79 +42,89 @@ metadata: namespace: default name: pod-reader rules: - - apiGroups: [""] # The API group "" indicates the core API Group. - resources: ["pods"] - verbs: ["get", "watch", "list"] +- apiGroups: [""] # "" indicates the core API group + resources: ["pods"] + verbs: ["get", "watch", "list"] ``` -`ClusterRoles` hold the same information as a `Role` but can apply to any -namespace as well as non-namespaced resources (such as `Nodes`, -`PersistentVolume`, etc.). The following `ClusterRole` can grant permissions to -read secrets in any namespace. +A `ClusterRole` can be used to grant the same permissions as a `Role`, +but because they are cluster-scoped, they can also be used to grant access to: + +* cluster-scoped resources (like nodes) +* non-resource endpoints (like "/healthz") +* namespaced resources (like pods) across all namespaces (needed to run `kubectl get pods --all-namespaces`, for example) + +The following `ClusterRole` can be used to grant read access to secrets in any particular namespace, +or across all namespaces (depending on how it is [bound](#rolebinding-and-clusterrolebinding)): ```yaml kind: ClusterRole apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: - # "namespace" omitted since ClusterRoles are not namespaced. + # "namespace" omitted since ClusterRoles are not namespaced name: secret-reader rules: - - apiGroups: [""] - resources: ["secrets"] - verbs: ["get", "watch", "list"] +- apiGroups: [""] + resources: ["secrets"] + verbs: ["get", "watch", "list"] ``` -`RoleBindings` perform the task of granting the permission to a user or set of -users. They hold a list of subjects which they apply to, and a reference to the -`Role` being assigned. +### RoleBinding and ClusterRoleBinding -The following `RoleBinding` assigns the "pod-reader" role to the user "jane" -within the "default" namespace, and allows jane to read pods. +A role binding grants the permissions defined in a role to a user or set of users. +It holds a list of subjects (users, groups, or service accounts), and a reference to the role being granted. +Permissions can be granted within a namespace with a `RoleBinding`, or cluster-wide with a `ClusterRoleBinding`. + +A `RoleBinding` may reference a `Role` in the same namespace. +The following `RoleBinding` grants the "pod-reader" role to the user "jane" within the "default" namespace. +This allows "jane" to read pods in the "default" namespace. ```yaml -# This role binding allows "jane" to read pods in the namespace "default" +# This role binding allows "jane" to read pods in the "default" namespace. kind: RoleBinding apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: read-pods namespace: default subjects: - - kind: User # May be "User", "Group" or "ServiceAccount" - name: jane +- kind: User + name: jane + apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: pod-reader apiGroup: rbac.authorization.k8s.io ``` -`RoleBindings` may also refer to a `ClusterRole`. However, a `RoleBinding` that -refers to a `ClusterRole` only applies in the `RoleBinding`'s namespace, not at -the cluster level. This allows admins to define a set of common roles for the -entire cluster, then reuse them in multiple namespaces. +A `RoleBinding` may also reference a `ClusterRole` to grant the permissions to namespaced +resources defined in the `ClusterRole` within the `RoleBinding`'s namespace. +This allows administrators to define a set of common roles for the entire cluster, +then reuse them within multiple namespaces. For instance, even though the following `RoleBinding` refers to a `ClusterRole`, "dave" (the subject) will only be able read secrets in the "development" -namespace, the namespace of the `RoleBinding`. +namespace (the namespace of the `RoleBinding`). ```yaml -# This role binding allows "dave" to read secrets in the namespace "development" +# This role binding allows "dave" to read secrets in the "development" namespace. kind: RoleBinding apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: read-secrets - namespace: development # This binding only applies in the "development" namespace + namespace: development # This only grants permissions within the "development" namespace. subjects: - - kind: User # May be "User", "Group" or "ServiceAccount" - name: dave +- kind: User + name: dave + apiGroup: rbac.authorization.k8s.io roleRef: kind: ClusterRole name: secret-reader apiGroup: rbac.authorization.k8s.io ``` -Finally a `ClusterRoleBinding` may be used to grant permissions in all -namespaces. The following `ClusterRoleBinding` allows any user in the group -"manager" to read secrets in any namespace. +Finally, a `ClusterRoleBinding` may be used to grant permission at the cluster level and in all +namespaces. The following `ClusterRoleBinding` allows any user in the group "manager" to read +secrets in any namespace. ```yaml # This cluster role binding allows anyone in the "manager" group to read secrets in any namespace. @@ -122,26 +133,27 @@ apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: read-secrets-global subjects: - - kind: Group # May be "User", "Group" or "ServiceAccount" - name: manager +- kind: Group + name: manager + apiGroup: rbac.authorization.k8s.io roleRef: kind: ClusterRole  name: secret-reader apiGroup: rbac.authorization.k8s.io ``` -## Referring to Resources +### Referring to Resources Most resources are represented by a string representation of their name, such as "pods", just as it appears in the URL for the relevant API endpoint. However, some Kubernetes APIs involve a -"subresource" such as the logs for a pod. The URL for the pods logs endpoint is: +"subresource", such as the logs for a pod. The URL for the pods logs endpoint is: ``` GET /api/v1/namespaces/{namespace}/pods/{name}/log ``` In this case, "pods" is the namespaced resource, and "log" is a subresource of pods. To represent -this in an RBAC role, use a slash to delimit the resource and subresource names. To allow a subject +this in an RBAC role, use a slash to delimit the resource and subresource. To allow a subject to read both pods and pod logs, you would write: ```yaml @@ -151,19 +163,80 @@ metadata: namespace: default name: pod-and-pod-logs-reader rules: - - apiGroups: [""] - resources: ["pods", "pods/log"] - verbs: ["get", "list"] +- apiGroups: [""] + resources: ["pods", "pods/log"] + verbs: ["get", "list"] ``` -## Referring to Subjects +#### Role Examples -RoleBindings and ClusterRoleBindings bind "subjects" to "roles". +Only the `rules` section is shown in the following examples. + +Allow reading the resource "pods" in the core API group: + +```yaml +rules: +- apiGroups: [""] + resources: ["pods"] + verbs: ["get", "list", "watch"] +``` + +Allow reading/writing "deployments" in both the "extensions" and "apps" API groups: + +```yaml +rules: +- apiGroups: ["extensions", "apps"] + resources: ["deployments"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +``` + +Allow reading "pods" and reading/writing "jobs": + +```yaml +rules: +- apiGroups: [""] + resources: ["pods"] + verbs: ["get", "list", "watch"] +- apiGroups: ["batch", "extensions"] + resources: ["jobs"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +``` + +Allow reading a `ConfigMap` named "my-config" (must be bound with a `RoleBinding` to limit to a single `ConfigMap` in a single namespace): + +```yaml +rules: +- apiGroups: [""] + resources: ["configmaps"] + resourceNames: ["my-config"] + verbs: ["get"] +``` + +Allow reading the resource "nodes" in the core group (because a `Node` is cluster-scoped, this must be in a `ClusterRole` bound with a `ClusterRoleBinding` to be effective): + +```yaml +rules: +- apiGroups: [""] + resources: ["nodes"] + verbs: ["get", "list", "watch"] +``` + +Allow "GET" and "POST" requests to the non-resource endpoint "/healthz" and all subpaths (must be in a `ClusterRole` bound with a `ClusterRoleBinding` to be effective): + +```yaml +rules: +- nonResourceURLs: ["/healthz", "/healthz/*"] + verbs: ["get", "post"] +``` + +### Referring to Subjects + +A `RoleBinding` or `ClusterRoleBinding` binds a role to *subjects*. Subjects can be groups, users or service accounts. Users are represented by strings. These can be plain usernames, like -"alice", or email style names, like "bob@example.com", or numeric ids -as string. It is up to the Kubernetes admin to configure +"alice", email-style names, like "bob@example.com", or numeric ids +represented as a string. It is up to the Kubernetes admin to configure the [authentication modules](/docs/admin/authentication/) to produce usernames in the desired format. The RBAC authorization system does not require any particular format. However, the prefix `system:` is @@ -171,49 +244,50 @@ reserved for Kubernetes system use, and so the admin should ensure usernames do not contain this prefix by accident. Group information in Kubernetes is currently provided by the Authenticator -modules. (In the future we may add a separate way for the RBAC Authorizer -to query group information for users.) Groups, like users, are represented -by a string, and that string has no format requirements, other than that the -prefix `system:` is reserved. +modules. Groups, like users, are represented as strings, and that string +has no format requirements, other than that the prefix `system:` is reserved. -Service Accounts have usernames with the `system:serviceaccount` prefix and belong +[Service Accounts](/docs/user-guide/service-accounts/) have usernames with the `system:serviceaccount:` prefix and belong to groups with the `system:serviceaccounts` prefix. -### Role Binding Examples +#### Role Binding Examples -Only the `subjects` section of a RoleBinding object shown in the following examples. +Only the `subjects` section of a `RoleBinding` is shown in the following examples. -For a user called `alice@example.com`, specify +For a user named "alice@example.com": ```yaml subjects: - - kind: User - name: "alice@example.com" +- kind: User + name: "alice@example.com" + apiGroup: rbac.authorization.k8s.io ``` -For a group called `frontend-admins`, specify: +For a group named "frontend-admins": ```yaml subjects: - - kind: Group - name: "frontend-admins" +- kind: Group + name: "frontend-admins" + apiGroup: rbac.authorization.k8s.io ``` For the default service account in the kube-system namespace: ```yaml subjects: - - kind: ServiceAccount - name: default - namespace: kube-system +- kind: ServiceAccount + name: default + namespace: kube-system ``` -For all service accounts in the `qa` namespace: +For all service accounts in the "qa" namespace: ```yaml subjects: - kind: Group name: system:serviceaccounts:qa + apiGroup: rbac.authorization.k8s.io ``` For all service accounts everywhere: @@ -222,37 +296,42 @@ For all service accounts everywhere: subjects: - kind: Group name: system:serviceaccounts + apiGroup: rbac.authorization.k8s.io ``` -For all authenticated users (1.5 and newer): +For all authenticated users (version 1.5+): ```yaml subjects: - kind: Group name: system:authenticated + apiGroup: rbac.authorization.k8s.io ``` -For all unauthenticated users (1.5 and newer): +For all unauthenticated users (version 1.5+): ```yaml subjects: - kind: Group name: system:unauthenticated + apiGroup: rbac.authorization.k8s.io ``` -For all users (1.5 and newer): +For all users (version 1.5+): ```yaml subjects: - kind: Group name: system:authenticated + apiGroup: rbac.authorization.k8s.io - kind: Group name: system:unauthenticated + apiGroup: rbac.authorization.k8s.io ``` -## Default ClusterRoles and ClusterRoleBindings +## Default Roles and Role Bindings -API servers create a set of default ClusterRoles and ClusterRoleBindings. +API servers create a set of default `ClusterRole` and `ClusterRoleBinding` objects. Many of these are `system:` prefixed, which indicates that the resource is "owned" by the infrastructure. Modifications to these resources can result in non-functional clusters. One example is the `system:node` ClusterRole. This role defines permissions for kubelets. If the role is modified, it can prevent kubelets from working. @@ -272,7 +351,7 @@ Be aware that missing default permissions and subjects can result in non-functio Auto-reconciliation is enabled in Kubernetes version 1.6+. -### Discovery roles +### Discovery Roles @@ -293,7 +372,7 @@ Auto-reconciliation is enabled in Kubernetes version 1.6+.
-### User-facing roles +### User-facing Roles Some of the default roles are not `system:` prefixed. These are intended to be user-facing roles. They include superuser roles (`cluster-admin`), @@ -342,7 +421,7 @@ It does not allow viewing secrets, since those are escalating. -### Core component roles +### Core Component Roles @@ -378,7 +457,7 @@ See https://pr.k8s.io/40476 for details.
-### Other component roles +### Other Component Roles @@ -425,7 +504,7 @@ This is commonly used by add-on API servers for unified authentication and autho
-### Controller roles +### Controller Roles The [Kubernetes controller manager](/docs/admin/kube-controller-manager/) runs core control loops. When invoked with `--use-service-account-credentials`, each control loop is started using a separate service account. @@ -461,7 +540,7 @@ The RBAC API prevents users from escalating privileges by editing roles or role Because this is enforced at the API level, it applies even when the RBAC authorizer is not in use. A user can only create/update a role if they already have all the permissions contained in the role, -at the same scope as the role (cluster-wide for `ClusterRole` objects, within the same namespace or cluster-wide for `Role` objects). +at the same scope as the role (cluster-wide for a `ClusterRole`, within the same namespace or cluster-wide for a `Role`). For example, if "user-1" does not have the ability to list secrets cluster-wide, they cannot create a `ClusterRole` containing that permission. To allow a user to create/update roles: @@ -515,33 +594,37 @@ To bootstrap initial roles and role bindings: * Use a credential with the `system:masters` group, which is bound to the `cluster-admin` superuser role by the default bindings. * If your API server runs with the insecure port enabled (`--insecure-port`), you can also make API calls via that port, which does not enforce authentication or authorization. -## Command-line utilities +## Command-line Utilities -Two `kubectl` commands exist to grant roles to users, within a namespace, or across the entire cluster. +Two `kubectl` commands exist to grant roles within a namespace or across the entire cluster. ### `kubectl create rolebinding` -Grants a role or clusterrole within a specific namespace. Examples: +Grants a `Role` or `ClusterRole` within a specific namespace. Examples: -* Grant the `admin` `ClusterRole` to a user named `bob` in the namespace `acme`: +* Grant the `admin` `ClusterRole` to a user named "bob" in the namespace "acme": - `kubectl create rolebinding my-role-binding --clusterrole=admin --user=bob --namespace=acme` + `kubectl create rolebinding bob-admin-binding --clusterrole=admin --user=bob --namespace=acme` -* Grant the `view` `ClusterRole` to a service account named `myapp` in the namespace `acme`: +* Grant the `view` `ClusterRole` to a service account named "myapp" in the namespace "acme": - `kubectl create rolebinding my-role-binding --clusterrole=view --serviceaccount=acme:myapp --namespace=acme` + `kubectl create rolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp --namespace=acme` ### `kubectl create clusterrolebinding` Grants a `ClusterRole` across the entire cluster, including all namespaces. Examples: -* Grant the `cluster-admin` `ClusterRole` to a user named `root`: +* Grant the `cluster-admin` `ClusterRole` to a user named "root" across the entire cluster: - `kubectl create clusterrolebinding my-root-binding --clusterrole=cluster-admin --user=root` + `kubectl create clusterrolebinding root-cluster-admin-binding --clusterrole=cluster-admin --user=root` -* Grant the `system:node` `ClusterRole` to a user named `kubelet`: +* Grant the `system:node` `ClusterRole` to a user named "kubelet" across the entire cluster: - `kubectl create clusterrolebinding my-kubelet-binding --clusterrole=system:node --user=kubelet` + `kubectl create clusterrolebinding kubelet-node-binding --clusterrole=system:node --user=kubelet` + +* Grant the `view` `ClusterRole` to a service account named "myapp" in the namespace "acme" across the entire cluster: + + `kubectl create clusterrolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp` See the CLI help for detailed usage @@ -559,7 +642,7 @@ This allows the cluster administrator to grant particular roles to particular se While far more secure, this can be disruptive to existing workloads expecting to automatically receive API permissions. Here are two approaches for managing this transition: -### Parallel authorizers +### Parallel Authorizers Run both the RBAC and ABAC authorizers, and include the legacy ABAC policy: @@ -575,7 +658,7 @@ When run with a log level of 2 or higher (`--v=2`), you can see RBAC denials in You can use that information to determine which roles need to be granted to which users or service accounts. Once normal workloads are running with no RBAC denial messages in the server logs, the ABAC authorizer can be removed. -### Permissive RBAC permissions +### Permissive RBAC Permissions You can replicate a permissive policy using RBAC role bindings.