whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add RBAC default roles, CLI helpers, upgrade guide

Browse Source
This commit is contained in:
Jordan Liggitt
2017-02-14 17:08:28 -05:00
committed by Andrew Chen
parent 258755fbfe
commit 6e9fc80694
2 changed files with 175 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/authorization/index.md
+3 -6
View File
@@ -204,14 +204,11 @@ When specified "RBAC" (Role-Based Access Control) uses the
allowing admins to dynamically configure permission policies through the allowing admins to dynamically configure permission policies through the
Kubernetes API. 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`, To enable RBAC, start the apiserver 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`.
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 ## Webhook Mode
docs/admin/authorization/rbac.md
+172 -74
View File
@@ -6,44 +6,15 @@ assignees:
title: Using RBAC Authorization 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 As of 1.6 RBAC mode is in beta.
"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 enable RBAC, start the apiserver with `--authorization-mode=RBAC`.
To use RBAC, you must both enable the authorization module with `--authorization-mode=RBAC`, ## Roles, RolesBindings, ClusterRoles, and ClusterRoleBindings
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 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 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 ```yaml
kind: Role kind: Role
apiVersion: rbac.authorization.k8s.io/v1alpha1 apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
namespace: default namespace: default
name: pod-reader name: pod-reader
@@ -79,7 +50,7 @@ read secrets in any namespace.
```yaml ```yaml
kind: ClusterRole kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1alpha1 apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
# "namespace" omitted since ClusterRoles are not namespaced. # "namespace" omitted since ClusterRoles are not namespaced.
name: secret-reader name: secret-reader
@@ -87,7 +58,6 @@ rules:
- apiGroups: [""] - apiGroups: [""]
resources: ["secrets"] resources: ["secrets"]
verbs: ["get", "watch", "list"] verbs: ["get", "watch", "list"]
nonResourceURLs: []
``` ```
`RoleBindings` perform the task of granting the permission to a user or set of `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 ```yaml
# This role binding allows "jane" to read pods in the namespace "default" # This role binding allows "jane" to read pods in the namespace "default"
kind: RoleBinding kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1alpha1 apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
name: read-pods name: read-pods
namespace: default namespace: default
@@ -125,7 +95,7 @@ namespace, the namespace of the `RoleBinding`.
```yaml ```yaml
# This role binding allows "dave" to read secrets in the namespace "development" # This role binding allows "dave" to read secrets in the namespace "development"
kind: RoleBinding kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1alpha1 apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
name: read-secrets name: read-secrets
namespace: development # This binding only applies in the "development" namespace 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 ```yaml
# This cluster role binding allows anyone in the "manager" group to read secrets in any namespace. # This cluster role binding allows anyone in the "manager" group to read secrets in any namespace.
kind: ClusterRoleBinding kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1alpha1 apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
name: read-secrets-global name: read-secrets-global
subjects: subjects:
@@ -157,7 +127,7 @@ roleRef:
apiGroup: rbac.authorization.k8s.io 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 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 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 ```yaml
kind: Role kind: Role
apiVersion: rbac.authorization.k8s.io/v1alpha1 apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
namespace: default namespace: default
name: pod-and-pod-logs-reader name: pod-and-pod-logs-reader
@@ -183,7 +153,7 @@ rules:
verbs: ["get", "list"] verbs: ["get", "list"]
``` ```
### Referring to Subjects ## Referring to Subjects
RoleBindings and ClusterRoleBindings bind "subjects" to "roles". RoleBindings and ClusterRoleBindings bind "subjects" to "roles".
Subjects can be groups, users or service accounts. 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 reserved for Kubernetes system use, and so the admin should ensure
usernames should not contain this prefix by accident. 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 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 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 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 Service Accounts have usernames with the `system:` prefix and belong
to groups with the `system:` prefix. 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. Only the `subjects` section of a RoleBinding object shown in the following examples.
@@ -277,51 +247,179 @@ subjects:
name: system:unauthenticated 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 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. 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 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. 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: They are all labeled with `kubernetes.io/bootstrapping=rbac-defaults`. These are the most commonly used:
|Default Role |Description <table>
<colgroup><col width="25%"><col width="25%"><col>
<tr>
<th>Default ClusterRole
<th>Default ClusterRoleBinding
<th>Description
|*admin* |A project manager. If used in a `RoleBinding`, an *admin* user will have <tr>
rights to view any Kubernetes resource in the project and modify any resource in the <td>*cluster-admin*
project except for quota. <td>`system:masters` group
<td>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 <tr>
granted to a user within a local policy, they have full control over quota and <td>*cluster-status*
roles and every action on every resource in the project. <td>None
<td>A role that allows read-only access to basic cluster status information.
|*cluster-status* |A role that can get basic cluster status information. <tr>
<td>*admin*
<td>None
<td>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 <tr>
power to view or modify roles or bindings. <td>*edit*
<td>None
<td>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 <tr>
project. They cannot view or modify roles or bindings. They cannot view secrets, <td>*view*
since those are escalating. <td>None
<td>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 <tr>
checks. This is commonly used by add-on API servers for a unified authentication and <td>*system:basic-user*
authorization experience. <td>`system:authenticated` and `system:unauthenticated` groups
<td>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. <tr>
<td>*system:discovery*
<td>`system:authenticated` and `system:unauthenticated` groups
<td>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 <tr>
negotiate an API level. <td>*system:auth-delegator*
<td>None
<td>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 </table>
In order to ease the binding of `ClusterRoles`, two CLI helpers were created. `kubectl create rolebinding` and ## Privilege Escalation Prevention and Bootstrapping
`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 The `rbac.authorization.k8s.io` API inherently prevents users
`kubectl create rolebinding -n my-namespace viewers --clusterrole=view --user=collaborator --serviceaccount=other-ns:default`. 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
```