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

RBAC doc cleanup

Browse Source
This commit is contained in:
Jordan Liggitt
2017-03-09 12:33:52 -05:00
committed by Andrew Chen
parent b60507278c
commit 8e0a24c6b0
1 changed files with 176 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/authorization/rbac.md
+176 -93
View File
@@ -17,22 +17,23 @@ As of 1.6 RBAC mode is in beta.
To enable RBAC, start the apiserver with `--authorization-mode=RBAC`. 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 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, `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 though readers who wish to follow along should review the section on
bootstrapping first. bootstrapping first.
In the RBAC API Group, roles hold a logical grouping of permissions. These ### Role and ClusterRole
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.
Here's an example of a role which grants read access to pods within the In the RBAC API, a role contains rules that represent a set of permissions.
"default" namespace. 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 ```yaml
kind: Role kind: Role
@@ -41,79 +42,89 @@ metadata:
namespace: default namespace: default
name: pod-reader name: pod-reader
rules: rules:
- apiGroups: [""] # The API group "" indicates the core API Group. - apiGroups: [""] # "" indicates the core API group
resources: ["pods"] resources: ["pods"]
verbs: ["get", "watch", "list"] verbs: ["get", "watch", "list"]
``` ```
`ClusterRoles` hold the same information as a `Role` but can apply to any A `ClusterRole` can be used to grant the same permissions as a `Role`,
namespace as well as non-namespaced resources (such as `Nodes`, but because they are cluster-scoped, they can also be used to grant access to:
`PersistentVolume`, etc.). The following `ClusterRole` can grant permissions to
read secrets in any namespace. * 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 ```yaml
kind: ClusterRole kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1beta1 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
rules: rules:
- apiGroups: [""] - apiGroups: [""]
resources: ["secrets"] resources: ["secrets"]
verbs: ["get", "watch", "list"] verbs: ["get", "watch", "list"]
``` ```
`RoleBindings` perform the task of granting the permission to a user or set of ### RoleBinding and ClusterRoleBinding
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" A role binding grants the permissions defined in a role to a user or set of users.
within the "default" namespace, and allows jane to read pods. 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 ```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 kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1beta1 apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
name: read-pods name: read-pods
namespace: default namespace: default
subjects: subjects:
- kind: User # May be "User", "Group" or "ServiceAccount" - kind: User
name: jane name: jane
apiGroup: rbac.authorization.k8s.io
roleRef: roleRef:
kind: Role kind: Role
name: pod-reader name: pod-reader
apiGroup: rbac.authorization.k8s.io apiGroup: rbac.authorization.k8s.io
``` ```
`RoleBindings` may also refer to a `ClusterRole`. However, a `RoleBinding` that A `RoleBinding` may also reference a `ClusterRole` to grant the permissions to namespaced
refers to a `ClusterRole` only applies in the `RoleBinding`'s namespace, not at resources defined in the `ClusterRole` within the `RoleBinding`'s namespace.
the cluster level. This allows admins to define a set of common roles for the This allows administrators to define a set of common roles for the entire cluster,
entire cluster, then reuse them in multiple namespaces. then reuse them within multiple namespaces.
For instance, even though the following `RoleBinding` refers to a `ClusterRole`, For instance, even though the following `RoleBinding` refers to a `ClusterRole`,
"dave" (the subject) will only be able read secrets in the "development" "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 ```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 kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1beta1 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 only grants permissions within the "development" namespace.
subjects: subjects:
- kind: User # May be "User", "Group" or "ServiceAccount" - kind: User
name: dave name: dave
apiGroup: rbac.authorization.k8s.io
roleRef: roleRef:
kind: ClusterRole kind: ClusterRole
name: secret-reader name: secret-reader
apiGroup: rbac.authorization.k8s.io apiGroup: rbac.authorization.k8s.io
``` ```
Finally a `ClusterRoleBinding` may be used to grant permissions in all 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 namespaces. The following `ClusterRoleBinding` allows any user in the group "manager" to read
"manager" to read secrets in any namespace. secrets in any namespace.
```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.
@@ -122,26 +133,27 @@ apiVersion: rbac.authorization.k8s.io/v1beta1
metadata: metadata:
name: read-secrets-global name: read-secrets-global
subjects: subjects:
- kind: Group # May be "User", "Group" or "ServiceAccount" - kind: Group
name: manager name: manager
apiGroup: rbac.authorization.k8s.io
roleRef: roleRef:
kind: ClusterRole kind: ClusterRole
 name: secret-reader  name: secret-reader
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
"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 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 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: to read both pods and pod logs, you would write:
```yaml ```yaml
@@ -151,19 +163,80 @@ metadata:
namespace: default namespace: default
name: pod-and-pod-logs-reader name: pod-and-pod-logs-reader
rules: rules:
- apiGroups: [""] - apiGroups: [""]
resources: ["pods", "pods/log"] resources: ["pods", "pods/log"]
verbs: ["get", "list"] 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. Subjects can be groups, users or service accounts.
Users are represented by strings. These can be plain usernames, like Users are represented by strings. These can be plain usernames, like
"alice", or email style names, like "bob@example.com", or numeric ids "alice", email-style names, like "bob@example.com", or numeric ids
as string. It is up to the Kubernetes admin to configure represented as a string. It is up to the Kubernetes admin to configure
the [authentication modules](/docs/admin/authentication/) to produce the [authentication modules](/docs/admin/authentication/) to produce
usernames in the desired format. The RBAC authorization system does usernames in the desired format. The RBAC authorization system does
not require any particular format. However, the prefix `system:` is 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. usernames do not contain this prefix by accident.
Group 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. Groups, like users, are represented as strings, and that string
to query group information for users.) Groups, like users, are represented has no format requirements, other than that the prefix `system:` is reserved.
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: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. 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 ```yaml
subjects: subjects:
- kind: User - kind: User
name: "alice@example.com" name: "alice@example.com"
apiGroup: rbac.authorization.k8s.io
``` ```
For a group called `frontend-admins`, specify: For a group named "frontend-admins":
```yaml ```yaml
subjects: subjects:
- kind: Group - kind: Group
name: "frontend-admins" name: "frontend-admins"
apiGroup: rbac.authorization.k8s.io
``` ```
For the default service account in the kube-system namespace: For the default service account in the kube-system namespace:
```yaml ```yaml
subjects: subjects:
- kind: ServiceAccount - kind: ServiceAccount
name: default name: default
namespace: kube-system namespace: kube-system
``` ```
For all service accounts in the `qa` namespace: For all service accounts in the "qa" namespace:
```yaml ```yaml
subjects: subjects:
- kind: Group - kind: Group
name: system:serviceaccounts:qa name: system:serviceaccounts:qa
apiGroup: rbac.authorization.k8s.io
``` ```
For all service accounts everywhere: For all service accounts everywhere:
@@ -222,37 +296,42 @@ For all service accounts everywhere:
subjects: subjects:
- kind: Group - kind: Group
name: system:serviceaccounts name: system:serviceaccounts
apiGroup: rbac.authorization.k8s.io
``` ```
For all authenticated users (1.5 and newer): For all authenticated users (version 1.5+):
```yaml ```yaml
subjects: subjects:
- kind: Group - kind: Group
name: system:authenticated name: system:authenticated
apiGroup: rbac.authorization.k8s.io
``` ```
For all unauthenticated users (1.5 and newer): For all unauthenticated users (version 1.5+):
```yaml ```yaml
subjects: subjects:
- kind: Group - kind: Group
name: system:unauthenticated name: system:unauthenticated
apiGroup: rbac.authorization.k8s.io
``` ```
For all users (1.5 and newer): For all users (version 1.5+):
```yaml ```yaml
subjects: subjects:
- kind: Group - kind: Group
name: system:authenticated name: system:authenticated
apiGroup: rbac.authorization.k8s.io
- kind: Group - kind: Group
name: system:unauthenticated 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. 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. 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. 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+. Auto-reconciliation is enabled in Kubernetes version 1.6+.
### Discovery roles ### Discovery Roles
<table> <table>
<colgroup><col width="25%"><col width="25%"><col></colgroup> <colgroup><col width="25%"><col width="25%"><col></colgroup>
@@ -293,7 +372,7 @@ Auto-reconciliation is enabled in Kubernetes version 1.6+.
</tr> </tr>
</table> </table>
### User-facing roles ### User-facing Roles
Some of the default roles are not `system:` prefixed. These are intended to be 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`), They include superuser roles (`cluster-admin`),
@@ -342,7 +421,7 @@ It does not allow viewing secrets, since those are escalating.</td>
</tr> </tr>
</table> </table>
### Core component roles ### Core Component Roles
<table> <table>
<colgroup><col width="25%"><col width="25%"><col></colgroup> <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> </tr>
</table> </table>
### Other component roles ### Other Component Roles
<table> <table>
<colgroup><col width="25%"><col width="25%"><col></colgroup> <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> </tr>
</table> </table>
### Controller roles ### Controller Roles
The [Kubernetes controller manager](/docs/admin/kube-controller-manager/) runs core control loops. 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. 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. 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, 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` 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: 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. * 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. * 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` ### `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` ### `kubectl create clusterrolebinding`
Grants a `ClusterRole` across the entire cluster, including all namespaces. Examples: 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 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. 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: 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: 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. 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. 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. You can replicate a permissive policy using RBAC role bindings.