diff --git a/_data/reference.yml b/_data/reference.yml index c31e1ed2c5..6a4f0942ba 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -25,7 +25,10 @@ toc: section: - docs/admin/accessing-the-api.md - docs/admin/authentication.md - - docs/admin/authorization/index.md + - title: Authorization Plugins + section: + - docs/admin/authorization/index.md + - docs/admin/authorization/rbac.md - docs/admin/admission-controllers.md - docs/admin/service-accounts-admin.md - docs/api-reference/v1/operations.html diff --git a/docs/admin/authorization/index.md b/docs/admin/authorization/index.md index 7b6166ca50..b1f1015d1e 100644 --- a/docs/admin/authorization/index.md +++ b/docs/admin/authorization/index.md @@ -4,7 +4,7 @@ assignees: - lavalamp - deads2k - liggitt -title: Using Authorization Plugins +title: Authorization Plugin Overview --- In Kubernetes, authorization happens as a separate step from authentication. @@ -24,10 +24,8 @@ The following implementations are available, and are selected by flag: need authorization. - `--authorization-mode=ABAC` allows for a simple local-file-based user-configured authorization policy. ABAC stands for Attribute-Based Access Control. -authorization policy. - - `--authorization-mode=RBAC` is an experimental implementation which allows -for authorization to be driven by the Kubernetes API. -RBAC stands for Roles-Based Access Control. + - `--authorization-mode=RBAC` allows for authorization to be driven by policy +stored in the Kubernetes API. RBAC stands for Role-Based Access Control. - `--authorization-mode=Webhook` allows for authorization to be driven by a remote service using REST. @@ -213,311 +211,7 @@ and [enable the API version]( /docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster), with a `--runtime-config=` that includes `rbac.authorization.k8s.io/v1alpha1`. -### Privilege Escalation Prevention and Bootstrapping - -The `rbac.authorization.k8s.io` API group inherently attempts to prevent users -from escalating privileges. Simply put, __a user can't grant permissions they -don't already have even when the RBAC authorizer it disabled__. If "user-1" -does not have the ability to read secrets in "namespace-a", they cannot create -a binding that would grant that permission to themselves or any other user. - -When bootstrapping, superuser credentials should include the `system:masters` -group, for example by creating a client cert with `/O=system:masters`. This -gives those credentials full access to the API and allows an admin to then set -up bindings for other users. - -In Kubernetes versions 1.4 and 1.5, there was a similar flag that gave a user -full access: - -``` ---authorization-rbac-super-user=admin -``` - -__This flag will be removed in 1.6__. Admins should prefer the `system:masters` -group when setting up clusters. - -### Roles, RolesBindings, ClusterRoles, and ClusterRoleBindings - -The RBAC API Group 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, -`kubectl create -f (resource).yml` can be used with any of these examples, -though readers who wish to follow along should review the following 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. Permission are purely additive, rules may only omit -permissions they do not wish to grant. - -Here's an example of a role which grants read access to pods within the -"default" namespace. - -```yaml -kind: Role -apiVersion: rbac.authorization.k8s.io/v1alpha1 -metadata: - namespace: default - name: pod-reader -rules: - - apiGroups: [""] # The API group "" 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. - -```yaml -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1alpha1 -metadata: - # "namespace" omitted since ClusterRoles are not namespaced. - name: secret-reader -rules: - - apiGroups: [""] - resources: ["secrets"] - verbs: ["get", "watch", "list"] - nonResourceURLs: [] -``` - -`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. - -The following `RoleBinding` assigns the "pod-reader" role to the user "jane" -within the "default" namespace, and allows jane to read pods. - -```yaml -# This role binding allows "jane" to read pods in the namespace "default" -kind: RoleBinding -apiVersion: rbac.authorization.k8s.io/v1alpha1 -metadata: - name: read-pods - namespace: default -subjects: - - kind: User # May be "User", "Group" or "ServiceAccount" - name: jane -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. - -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`. - -```yaml -# This role binding allows "dave" to read secrets in the namespace "development" -kind: RoleBinding -apiVersion: rbac.authorization.k8s.io/v1alpha1 -metadata: - name: read-secrets - namespace: development # This binding only applies in the "development" namespace -subjects: - - kind: User # May be "User", "Group" or "ServiceAccount" - name: dave -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. - -```yaml -# This cluster role binding allows anyone in the "manager" group to read secrets in any namespace. -kind: ClusterRoleBinding -apiVersion: rbac.authorization.k8s.io/v1alpha1 -metadata: - name: read-secrets-global -subjects: - - kind: Group # May be "User", "Group" or "ServiceAccount" - name: manager -roleRef: - kind: ClusterRole -  name: secret-reader - apiGroup: rbac.authorization.k8s.io -``` - -### 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: - -``` -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 -to read both pods and pod logs, you would write: - -```yaml -kind: Role -apiVersion: rbac.authorization.k8s.io/v1alpha1 -metadata: - namespace: default - name: pod-and-pod-logs-reader -rules: - - apiGroups: [""] - resources: ["pods", "pods/log"] - verbs: ["get", "list"] -``` - -### Referring to Subjects - -RoleBindings and ClusterRoleBindings bind "subjects" to "roles". -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 -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 -reserved for Kubernetes system use, and so the admin should ensure -usernames should not contain this prefix by accident. - -Groups 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 groups 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. - -Service Accounts have usernames with the `system:` prefix and belong -to groups with the `system:` prefix. - -#### Role Binding Examples - -Only the `subjects` section of a RoleBinding object shown in the following examples. - -For a user called `alice@example.com`, specify - -```yaml -subjects: - - kind: User - name: "alice@example.com" -``` - -For a group called `frontend-admins`, specify: - -```yaml -subjects: - - kind: Group - name: "frontend-admins" -``` - -For the default service account in the kube-system namespace: - -```yaml -subjects: - - kind: ServiceAccount - name: default - namespace: kube-system -``` - -For all service accounts in the `qa` namespace: - -```yaml -subjects: -- kind: Group - name: system:serviceaccounts:qa -``` - -For all service accounts everywhere: - -```yaml -subjects: -- kind: Group - name: system:serviceaccounts -``` - -For all authenticated users: - -```yaml -subjects: -- kind: Group - name: system:authenticated -``` - -For all unauthenticated users: - -```yaml -subjects: -- kind: Group - name: system:unauthenticated -``` - -For all users: - -```yaml -subjects: -- kind: Group - name: system:authenticated -- kind: Group - name: system:unauthenticated -``` - -### `system:*` prefixed RBAC resources - -If an RBAC resource (`ClusterRole`, `ClusterRoleBinding`, etc) is prefixed with `system:*`, that indicates that -the resource is "owned" by the infrastructure. Modifications to these resources can result in non-functional clusters. - -One example is the `clusterrole/system:nodes`. This role is used to provide limited permissions to kubelets. If the -role is modified, its possible to prevent your kubelet from working. - -### Default ClusterRoles and ClusterRoleBindings - -When starting up an API server without any ClusterRoles or ClusterRoleBindings, the API server will bootstrap itself -with a set of default ClusterRoles and ClusterRoleBindings. Most of these are `system:*` prefixed, but some are not. -They are all labeled with `kubernetes.io/bootstrapping=rbac-defaults`. These are the most commonly used: - -|Default Role |Description - -|*admin* |A project manager. If used in a `RoleBinding`, an *admin* user will have -rights to view any Kubernetes resource in the project and modify any resource in the -project except for quota. - -|*cluster-admin* |A super-user role that can perform any action in any project. When -granted to a user within a local policy, they have full control over quota and -roles and every action on every resource in the project. - -|*cluster-status* |A role that can get basic cluster status information. - -|*edit* |A role that can modify most objects in a project, but does not have the -power to view or modify roles or bindings. - -|*view* |A role who cannot make any modifications, but can see most objects in a -project. They cannot view or modify roles or bindings. They cannot view secrets, -since those are escalating. - -|*system:auth-delegator*|A role which allows delegated authentication and authorization -checks. This is commonly used by add-on API servers for a unified authentication and -authorization experience. - -|*system:basic-user* |A role that can get basic information about himself. - -|*system:discovery*|A role which provides just enough power to access discovery and -negotiate an API level. - -### CLI helpers - -In order to ease the binding of `ClusterRoles`, two CLI helpers were created. `kubectl create rolebinding` and -`kubectl create clusterrolebinding`. See the CLI help for detailed usage, but they allow for usage like -`kubectl create clusterrolebinding cluster-admins --clusterrole=cluster-admin --user=root` and -`kubectl create rolebinding -n my-namespace viewers --clusterrole=view --user=collaborator --serviceaccount=other-ns:default`. +See [full RBAC documentation](/docs/admin/authorization/rbac/) for details. ## Webhook Mode diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md new file mode 100644 index 0000000000..ee0d891278 --- /dev/null +++ b/docs/admin/authorization/rbac.md @@ -0,0 +1,327 @@ +--- +assignees: +- erictune +- deads2k +- liggitt +title: Using RBAC Authorization +--- + +## RBAC Mode + +When specified "RBAC" (Role-Based Access Control) uses the +"rbac.authorization.k8s.io" API group to drive authorization decisions, +allowing admins to dynamically configure permission policies through the +Kubernetes API. + +As of 1.3 RBAC mode is in alpha and considered experimental. + +To use RBAC, you must both enable the authorization module with `--authorization-mode=RBAC`, +and [enable the API version]( +/docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster), +with a `--runtime-config=` that includes `rbac.authorization.k8s.io/v1alpha1`. + +### Privilege Escalation Prevention and Bootstrapping + +The `rbac.authorization.k8s.io` API group inherently attempts to prevent users +from escalating privileges. Simply put, __a user can't grant permissions they +don't already have even when the RBAC authorizer it disabled__. If "user-1" +does not have the ability to read secrets in "namespace-a", they cannot create +a binding that would grant that permission to themselves or any other user. + +When bootstrapping, superuser credentials should include the `system:masters` +group, for example by creating a client cert with `/O=system:masters`. This +gives those credentials full access to the API and allows an admin to then set +up bindings for other users. + +In Kubernetes versions 1.4 and 1.5, there was a similar flag that gave a user +full access: + +``` +--authorization-rbac-super-user=admin +``` + +__This flag will be removed in 1.6__. Admins should prefer the `system:masters` +group when setting up clusters. + +### Roles, RolesBindings, ClusterRoles, and ClusterRoleBindings + +The RBAC API Group 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, +`kubectl create -f (resource).yml` can be used with any of these examples, +though readers who wish to follow along should review the following 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. Permission are purely additive, rules may only omit +permissions they do not wish to grant. + +Here's an example of a role which grants read access to pods within the +"default" namespace. + +```yaml +kind: Role +apiVersion: rbac.authorization.k8s.io/v1alpha1 +metadata: + namespace: default + name: pod-reader +rules: + - apiGroups: [""] # The API group "" 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. + +```yaml +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1alpha1 +metadata: + # "namespace" omitted since ClusterRoles are not namespaced. + name: secret-reader +rules: + - apiGroups: [""] + resources: ["secrets"] + verbs: ["get", "watch", "list"] + nonResourceURLs: [] +``` + +`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. + +The following `RoleBinding` assigns the "pod-reader" role to the user "jane" +within the "default" namespace, and allows jane to read pods. + +```yaml +# This role binding allows "jane" to read pods in the namespace "default" +kind: RoleBinding +apiVersion: rbac.authorization.k8s.io/v1alpha1 +metadata: + name: read-pods + namespace: default +subjects: + - kind: User # May be "User", "Group" or "ServiceAccount" + name: jane +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. + +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`. + +```yaml +# This role binding allows "dave" to read secrets in the namespace "development" +kind: RoleBinding +apiVersion: rbac.authorization.k8s.io/v1alpha1 +metadata: + name: read-secrets + namespace: development # This binding only applies in the "development" namespace +subjects: + - kind: User # May be "User", "Group" or "ServiceAccount" + name: dave +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. + +```yaml +# This cluster role binding allows anyone in the "manager" group to read secrets in any namespace. +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1alpha1 +metadata: + name: read-secrets-global +subjects: + - kind: Group # May be "User", "Group" or "ServiceAccount" + name: manager +roleRef: + kind: ClusterRole +  name: secret-reader + apiGroup: rbac.authorization.k8s.io +``` + +### 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: + +``` +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 +to read both pods and pod logs, you would write: + +```yaml +kind: Role +apiVersion: rbac.authorization.k8s.io/v1alpha1 +metadata: + namespace: default + name: pod-and-pod-logs-reader +rules: + - apiGroups: [""] + resources: ["pods", "pods/log"] + verbs: ["get", "list"] +``` + +### Referring to Subjects + +RoleBindings and ClusterRoleBindings bind "subjects" to "roles". +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 +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 +reserved for Kubernetes system use, and so the admin should ensure +usernames should not contain this prefix by accident. + +Groups 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 groups 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. + +Service Accounts have usernames with the `system:` prefix and belong +to groups with the `system:` prefix. + +#### Role Binding Examples + +Only the `subjects` section of a RoleBinding object shown in the following examples. + +For a user called `alice@example.com`, specify + +```yaml +subjects: + - kind: User + name: "alice@example.com" +``` + +For a group called `frontend-admins`, specify: + +```yaml +subjects: + - kind: Group + name: "frontend-admins" +``` + +For the default service account in the kube-system namespace: + +```yaml +subjects: + - kind: ServiceAccount + name: default + namespace: kube-system +``` + +For all service accounts in the `qa` namespace: + +```yaml +subjects: +- kind: Group + name: system:serviceaccounts:qa +``` + +For all service accounts everywhere: + +```yaml +subjects: +- kind: Group + name: system:serviceaccounts +``` + +For all authenticated users: + +```yaml +subjects: +- kind: Group + name: system:authenticated +``` + +For all unauthenticated users: + +```yaml +subjects: +- kind: Group + name: system:unauthenticated +``` + +For all users: + +```yaml +subjects: +- kind: Group + name: system:authenticated +- kind: Group + name: system:unauthenticated +``` + +### `system:*` prefixed RBAC resources + +If an RBAC resource (`ClusterRole`, `ClusterRoleBinding`, etc) is prefixed with `system:*`, that indicates that +the resource is "owned" by the infrastructure. Modifications to these resources can result in non-functional clusters. + +One example is the `clusterrole/system:nodes`. This role is used to provide limited permissions to kubelets. If the +role is modified, its possible to prevent your kubelet from working. + +### Default ClusterRoles and ClusterRoleBindings + +When starting up an API server without any ClusterRoles or ClusterRoleBindings, the API server will bootstrap itself +with a set of default ClusterRoles and ClusterRoleBindings. Most of these are `system:*` prefixed, but some are not. +They are all labeled with `kubernetes.io/bootstrapping=rbac-defaults`. These are the most commonly used: + +|Default Role |Description + +|*admin* |A project manager. If used in a `RoleBinding`, an *admin* user will have +rights to view any Kubernetes resource in the project and modify any resource in the +project except for quota. + +|*cluster-admin* |A super-user role that can perform any action in any project. When +granted to a user within a local policy, they have full control over quota and +roles and every action on every resource in the project. + +|*cluster-status* |A role that can get basic cluster status information. + +|*edit* |A role that can modify most objects in a project, but does not have the +power to view or modify roles or bindings. + +|*view* |A role who cannot make any modifications, but can see most objects in a +project. They cannot view or modify roles or bindings. They cannot view secrets, +since those are escalating. + +|*system:auth-delegator*|A role which allows delegated authentication and authorization +checks. This is commonly used by add-on API servers for a unified authentication and +authorization experience. + +|*system:basic-user* |A role that can get basic information about himself. + +|*system:discovery*|A role which provides just enough power to access discovery and +negotiate an API level. + +### CLI helpers + +In order to ease the binding of `ClusterRoles`, two CLI helpers were created. `kubectl create rolebinding` and +`kubectl create clusterrolebinding`. See the CLI help for detailed usage, but they allow for usage like +`kubectl create clusterrolebinding cluster-admins --clusterrole=cluster-admin --user=root` and +`kubectl create rolebinding -n my-namespace viewers --clusterrole=view --user=collaborator --serviceaccount=other-ns:default`.