RBAC doc cleanup
Jordan Liggitt
Andrew Chen
parent
b60507278c
commit
8e0a24c6b0
|
|
@ -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
|
||||
|
||||
<table>
|
||||
<colgroup><col width="25%"><col width="25%"><col></colgroup>
|
||||
|
|
@ -293,7 +372,7 @@ Auto-reconciliation is enabled in Kubernetes version 1.6+.
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
### 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.</td>
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
### Core component roles
|
||||
### Core Component Roles
|
||||
|
||||
<table>
|
||||
<colgroup><col width="25%"><col width="25%"><col></colgroup>
|
||||
|
|
@ -378,7 +457,7 @@ See <a href="https://pr.k8s.io/40476">https://pr.k8s.io/40476</a> for details.
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
### Other component roles
|
||||
### Other Component Roles
|
||||
|
||||
<table>
|
||||
<colgroup><col width="25%"><col width="25%"><col></colgroup>
|
||||
|
|
@ -425,7 +504,7 @@ This is commonly used by add-on API servers for unified authentication and autho
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
### 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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue