Improve RBAC documentation (kubernetes#11254)

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

* Add create role and create clusterrole help

* Add reconcile documentation

* Document roleRef restrictions

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