From 6e9fc806942690e883375d9477860495f4c183ab Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Tue, 14 Feb 2017 17:08:28 -0500 Subject: [PATCH] Add RBAC default roles, CLI helpers, upgrade guide --- docs/admin/authorization/index.md | 9 +- docs/admin/authorization/rbac.md | 246 +++++++++++++++++++++--------- 2 files changed, 175 insertions(+), 80 deletions(-) diff --git a/docs/admin/authorization/index.md b/docs/admin/authorization/index.md index b1f1015d1e..7fecce9570 100644 --- a/docs/admin/authorization/index.md +++ b/docs/admin/authorization/index.md @@ -204,14 +204,11 @@ When specified "RBAC" (Role-Based Access Control) uses the allowing admins to dynamically configure permission policies through the Kubernetes API. -As of 1.3 RBAC mode is in alpha and considered experimental. +As of 1.6 RBAC mode is in beta. -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`. +To enable RBAC, start the apiserver with `--authorization-mode=RBAC`. -See [full RBAC documentation](/docs/admin/authorization/rbac/) for details. +For details about administrating and using RBAC, view the [RBAC guide](/docs/admin/authorization/rbac). ## Webhook Mode diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md index ee0d891278..194ba0edf0 100644 --- a/docs/admin/authorization/rbac.md +++ b/docs/admin/authorization/rbac.md @@ -6,44 +6,15 @@ assignees: title: Using RBAC Authorization --- -## RBAC Mode +Role-Based Access Control ("RBAC") uses the "rbac.authorization.k8s.io" API group +to drive authorization decisions, allowing admins to dynamically configure policies +through the Kubernetes API. -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.6 RBAC mode is in beta. -As of 1.3 RBAC mode is in alpha and considered experimental. +To enable RBAC, start the apiserver with `--authorization-mode=RBAC`. -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 +## 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 @@ -62,7 +33,7 @@ Here's an example of a role which grants read access to pods within the ```yaml kind: Role -apiVersion: rbac.authorization.k8s.io/v1alpha1 +apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: namespace: default name: pod-reader @@ -79,7 +50,7 @@ read secrets in any namespace. ```yaml kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1alpha1 +apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: # "namespace" omitted since ClusterRoles are not namespaced. name: secret-reader @@ -87,7 +58,6 @@ rules: - apiGroups: [""] resources: ["secrets"] verbs: ["get", "watch", "list"] - nonResourceURLs: [] ``` `RoleBindings` perform the task of granting the permission to a user or set of @@ -100,7 +70,7 @@ 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 +apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: read-pods namespace: default @@ -125,7 +95,7 @@ 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 +apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: read-secrets namespace: development # This binding only applies in the "development" namespace @@ -145,7 +115,7 @@ namespaces. The following `ClusterRoleBinding` allows any user in the group ```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 +apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: read-secrets-global subjects: @@ -157,7 +127,7 @@ roleRef: 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 @@ -173,7 +143,7 @@ to read both pods and pod logs, you would write: ```yaml kind: Role -apiVersion: rbac.authorization.k8s.io/v1alpha1 +apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: namespace: default name: pod-and-pod-logs-reader @@ -183,7 +153,7 @@ rules: verbs: ["get", "list"] ``` -### Referring to Subjects +## Referring to Subjects RoleBindings and ClusterRoleBindings bind "subjects" to "roles". Subjects can be groups, users or service accounts. @@ -197,7 +167,7 @@ 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 +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 groups information for users.) Groups, like users, are represented by a string, and that string has no format requirements, other than that the @@ -206,7 +176,7 @@ prefix `system:` is reserved. Service Accounts have usernames with the `system:` prefix and belong to groups with the `system:` prefix. -#### Role Binding Examples +### Role Binding Examples Only the `subjects` section of a RoleBinding object shown in the following examples. @@ -277,51 +247,179 @@ subjects: name: system:unauthenticated ``` -### `system:*` prefixed RBAC resources +## `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. +role is modified, it's possible to prevent your kubelet from working. -### Default ClusterRoles and ClusterRoleBindings +## Default ClusterRoles and ClusterRoleBindings -When starting up an API server without any ClusterRoles or ClusterRoleBindings, the API server will bootstrap itself +When starting 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 + ++ + + + + + + + + +
Default ClusterRole +Default ClusterRoleBinding +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* +`system:masters` group +A super-user role that allows performing any action on any resource. +When used in a `ClusterRoleBinding`, it gives full control over every resource in the cluster and in all namespaces. +When used in a `RoleBinding`, if gives full control over every resource in the rolebinding's namespace. -|*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* +None +A role that allows read-only access to basic cluster status information. -|*cluster-status* |A role that can get basic cluster status information. +
*admin* +None +A role for a namespace manager, intended to be granted within a namespace using a `RoleBinding`. +If used in a `RoleBinding`, allows read/write access to most resources in a namespace, +including the ability to create roles and rolebindings within the namespace. +It does not allow write access to resource quota. -|*edit* |A role that can modify most objects in a project, but does not have the -power to view or modify roles or bindings. +
*edit* +None +A role that allows read/write access to most objects in a namespace. +It does not allow viewing or modifying roles or rolebindings. -|*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. +
*view* +None +A role that allows read-only access to see most objects in a namespace. +It does not allow viewing roles or rolebindings. +It does not allow viewing 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* +`system:authenticated` and `system:unauthenticated` groups +A role that allows a user read-only access to basic information about themselves. -|*system:basic-user* |A role that can get basic information about himself. +
*system:discovery* +`system:authenticated` and `system:unauthenticated` groups +A role that allows read-only access to API discovery endpoints needed to discover +and negotiate an API level. -|*system:discovery*|A role which provides just enough power to access discovery and -negotiate an API level. +
*system:auth-delegator* +None +A role which allows delegated authentication and authorization checks. +This is commonly used by add-on API servers for unified authentication and authorization. -### 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`. +## Privilege Escalation Prevention and Bootstrapping + +The `rbac.authorization.k8s.io` API inherently prevents users +from escalating privileges by editing roles or role bindings. +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. + +For bootstrapping the first roles, it becomes necessary for someone to get around these limitations. +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 bootstrap bindings. +* If your API server serves with the insecure port enabled (--insecure-port), you can also make API calls via that port, which does not enforce authentication or authorization. + +To allow a user to create/modify roles: + +1. Grant them a role that allows them to create/update `Role` or `ClusterRole` resources, as desired. +2. Grant them a role that includes all the permissions you would want them to be able to include in a `Role` or `ClusterRole`. If they attempt to create or modify a `Role` or `ClusterRole` to include permissions they themselves have not been granted, they will be rejected. + +To allow a user to create/modify role bindings: + +1. Grant them a role that allows them to create/update `RoleBinding` or `ClusterRoleBinding` resources, as desired. +2. Grant them permissions needed to bind particular roles: + * implicitly, by giving them the permissions contained in the roles + * explicitly, by giving them permission to perform the "bind" verb on the particular roles or clusterroles desired. + +## CLI helpers + +In order to ease the binding of `ClusterRoles`, two CLI helpers exist: + +### `kubectl create rolebinding` + +Grants a role or clusterrole within a specific namespace. Examples: + +* 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` + +* 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 clusterrolebinding` + +Grants a `ClusterRole` across the entire cluster, including all namespaces. Examples: + +* Grant the `cluster-admin` `ClusterRole` to a user named `root`: + + `kubectl create clusterrolebinding my-root-binding --clusterrole=cluster-admin --user=root` + +* Grant the `system:node` `ClusterRole` to a user named `kubelet`: + + `kubectl create clusterrolebinding my-kubelet-binding --clusterrole=system:node --user=kubelet` + +See the CLI help for detailed usage + +## Upgrading from 1.5 + +Prior to Kubernetes 1.6, many deployments used very permissive ABAC policies, +including granting full API access to all service accounts. + +The default RBAC policies grant scoped permissions to control-plane components, nodes, +and controllers, and grant *no permissions* to service accounts outside the `kube-system` namespace +(beyond those given to unauthenticated users). + +This allows the cluster administrator to grant particular roles to particular service accounts as needed. + +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 + +Run both the RBAC and ABAC authorizers, and include the legacy ABAC policy: + +``` +--authorization-mode=RBAC,ABAC --authorization-policy-file=mypolicy.jsonl +``` + +The RBAC authorizer will attempt to authorize requests first. If it denies an API request, +the ABAC authorizer is then run. This means that any request allowed by *either* the RBAC +or ABAC policies is allowed. + +When run with a log level of 2 or higher (`--v=2`), you can see RBAC denials in the apiserver log. +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 + +You can replicate a permissive policy using RBAC role bindings. + +**WARNING: The following policy allows ALL service accounts to act as cluster administrators. +Any application running in a container receives service account credentials automatically, +and could perform any action against the API, including viewing secrets and modifying permissions. +This is not a recommended policy.** + +``` +kubectl create clusterrolebinding permissive-binding \ + --clusterrole=cluster-admin \ + --user=admin \ + --user=kubelet \ + --group=system:serviceaccounts +```