kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve RBAC documentation (#11254) 

* Add cross-namespace service account example, clarify binding wording

* Add create role and create clusterrole help

* Add reconcile documentation

* Document roleRef restrictions
pull/12465/head^2
Jordan Liggitt 2019-02-17 21:20:12 -05:00 committed by Kubernetes Prow Robot
parent ef8967997c
commit 9156340725
1 changed files with 135 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
content/en/docs/reference/access-authn-authz/rbac.md
View File

@ -148,6 +148,24 @@ roleRef:
apiGroup: rbac.authorization.k8s.io
```
You cannot modify which `Role` or `ClusterRole` a binding object refers to.
Attempts to change the `roleRef` field of a binding object will result in a validation error.
To change the `roleRef` field on an existing binding object, the binding object must be deleted and recreated.
There are two primary reasons for this restriction:
1. A binding to a different role is a fundamentally different binding.
Requiring a binding to be deleted/recreated in order to change the `roleRef`
ensures the full list of subjects in the binding is intended to be granted
the new role (as opposed to enabling accidentally modifying just the roleRef
without verifying all of the existing subjects should be given the new role's permissions).
2. Making `roleRef` immutable allows giving `update` permission on an existing binding object
to a user, which lets them manage the list of subjects, without being able to change the
role that is granted to those subjects.
The `kubectl auth reconcile` command-line utility creates or updates a manifest file containing RBAC objects,
and handles deleting and recreating binding objects if required to change the role they refer to.
See [command usage and examples](#kubectl-auth-reconcile) for more information.
### Referring to Resources
Most resources are represented by a string representation of their name, such as "pods", just as it
@ -738,46 +756,156 @@ To bootstrap initial roles and role bindings:
## Command-line Utilities
Two `kubectl` commands exist to grant roles within a namespace or across the entire cluster.
### `kubectl create role`
Creates a `Role` object defining permissions within a single namespace. Examples:
* Create a `Role` named "pod-reader" that allows user to perform "get", "watch" and "list" on pods:
```
kubectl create role pod-reader --verb=get --verb=list --verb=watch --resource=pods
```
* Create a `Role` named "pod-reader" with resourceNames specified:
```
kubectl create role pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod
```
* Create a `Role` named "foo" with apiGroups specified:
```
kubectl create role foo --verb=get,list,watch --resource=replicasets.apps
```
* Create a `Role` named "foo" with subresource permissions:
```
kubectl create role foo --verb=get,list,watch --resource=pods,pods/status
```
* Create a `Role` named "my-component-lease-holder" with permissions to get/update a resource with a specific name:
```
kubectl create role my-component-lease-holder --verb=get,list,watch,update --resource=lease --resource-name=my-component
```
### `kubectl create clusterrole`
Creates a `ClusterRole` object. Examples:
* Create a `ClusterRole` named "pod-reader" that allows user to perform "get", "watch" and "list" on pods:
```
kubectl create clusterrole pod-reader --verb=get,list,watch --resource=pods
```
* Create a `ClusterRole` named "pod-reader" with resourceNames specified:
```
kubectl create clusterrole pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod
```
* Create a `ClusterRole` named "foo" with apiGroups specified:
```
kubectl create clusterrole foo --verb=get,list,watch --resource=replicasets.apps
```
* Create a `ClusterRole` named "foo" with subresource permissions:
```
kubectl create clusterrole foo --verb=get,list,watch --resource=pods,pods/status
```
* Create a `ClusterRole` name "foo" with nonResourceURL specified:
```
kubectl create clusterrole "foo" --verb=get --non-resource-url=/logs/*
```
* Create a `ClusterRole` name "monitoring" with aggregationRule specified:
```
kubectl create clusterrole monitoring --aggregation-rule="rbac.example.com/aggregate-to-monitoring=true"
```
### `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":
* Within the namespace "acme", grant the permissions in the `admin` `ClusterRole` to a user named "bob":
```
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":
* Within the namespace "acme", grant the permissions in the `view` `ClusterRole` to the service account in the namespace "acme" named "myapp" :
```
kubectl create rolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp --namespace=acme
```
* Within the namespace "acme", grant the permissions in the `view` `ClusterRole` to a service account in the namespace "myappnamespace" named "myapp":
```
kubectl create rolebinding myappnamespace-myapp-view-binding --clusterrole=view --serviceaccount=myappnamespace: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" across the entire cluster:
* Across the entire cluster, grant the permissions in the `cluster-admin` `ClusterRole` to a user named "root":
```
kubectl create clusterrolebinding root-cluster-admin-binding --clusterrole=cluster-admin --user=root
```
* Grant the `system:node` `ClusterRole` to a user named "kubelet" across the entire cluster:
* Across the entire cluster, grant the permissions in the `system:node-proxier ` `ClusterRole` to a user named "system:kube-proxy":
```
kubectl create clusterrolebinding kubelet-node-binding --clusterrole=system:node --user=kubelet
kubectl create clusterrolebinding kube-proxy-binding --clusterrole=system:node-proxier --user=system:kube-proxy
```
* Grant the `view` `ClusterRole` to a service account named "myapp" in the namespace "acme" across the entire cluster:
* Across the entire cluster, grant the permissions in the `view` `ClusterRole` to a service account named "myapp" in the namespace "acme":
```
kubectl create clusterrolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp
```
### `kubectl auth reconcile` {#kubectl-auth-reconcile}
Creates or updates `rbac.authorization.k8s.io/v1` API objects from a manifest file.
Missing objects are created, and the containing namespace is created for namespaced objects, if required.
Existing roles are updated to include the permissions in the input objects,
and remove extra permissions if `--remove-extra-permissions` is specified.
Existing bindings are updated to include the subjects in the input objects,
and remove extra subjects if `--remove-extra-subjects` is specified.
Examples:
* Test applying a manifest file of RBAC objects, displaying changes that would be made:
```
kubectl auth reconcile -f my-rbac-rules.yaml --dry-run
```
* Apply a manifest file of RBAC objects, preserving any extra permissions (in roles) and any extra subjects (in bindings):
```
kubectl auth reconcile -f my-rbac-rules.yaml
```
* Apply a manifest file of RBAC objects, removing any extra permissions (in roles) and any extra subjects (in bindings):
```
kubectl auth reconcile -f my-rbac-rules.yaml --remove-extra-subjects --remove-extra-permissions
```
See the CLI help for detailed usage.
## Service Account Permissions