From 84ee91fcaf4fa4f15c6d5b4c35aa7b37a37d0deb Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Sun, 17 Feb 2019 21:20:12 -0500 Subject: [PATCH] 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 --- .../docs/reference/access-authn-authz/rbac.md | 142 +++++++++++++++++- 1 file changed, 135 insertions(+), 7 deletions(-) diff --git a/content/en/docs/reference/access-authn-authz/rbac.md b/content/en/docs/reference/access-authn-authz/rbac.md index b90509b924341..cccdcf255d43d 100644 --- a/content/en/docs/reference/access-authn-authz/rbac.md +++ b/content/en/docs/reference/access-authn-authz/rbac.md @@ -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