Add RBAC default roles, CLI helpers, upgrade guide
Jordan Liggitt
Andrew Chen
parent
258755fbfe
commit
6e9fc80694
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<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
|
||||
rights to view any Kubernetes resource in the project and modify any resource in the
|
||||
project except for quota.
|
||||
<tr>
|
||||
<td>*cluster-admin*
|
||||
<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
|
||||
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.
|
||||
<tr>
|
||||
<td>*cluster-status*
|
||||
<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
|
||||
power to view or modify roles or bindings.
|
||||
<tr>
|
||||
<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
|
||||
project. They cannot view or modify roles or bindings. They cannot view secrets,
|
||||
since those are escalating.
|
||||
<tr>
|
||||
<td>*view*
|
||||
<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
|
||||
checks. This is commonly used by add-on API servers for a unified authentication and
|
||||
authorization experience.
|
||||
<tr>
|
||||
<td>*system:basic-user*
|
||||
<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
|
||||
negotiate an API level.
|
||||
<tr>
|
||||
<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
|
||||
`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
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue