authorization: improve authorization debugging docs (#5549)

docs/admin/authorization/index.md

@@ -67,47 +67,70 @@ of the `bind` verb on `roles` and `clusterroles` resources in the `rbac.authoriz
 
 #### Checking API Access
 
-Kubernetes exposes the `subjectaccessreviews.v1.authorization.k8s.io` resource as a
+`kubectl` provides the `auth can-i` subcommand for quickly querying the API authorization layer.
-normal resource that allows external access to API authorizer decisions.  No matter which authorizer
+The command uses the `SelfSubjectAccessReview` API to determine if the current user can perform
-you choose to use, you can issue a `POST` with a `SubjectAccessReview` just like the webhook
+a given action, and works regardless of the authorization mode used.
-authorizer to the `apis/authorization.k8s.io/v1/subjectaccessreviews` endpoint and
+
-get back a response.  For instance:
 
 ```bash
-kubectl create --v=8 -f -  << __EOF__
+$ kubectl auth can-i create deployments --namespace dev
-{
+yes
-  "apiVersion": "authorization.k8s.io/v1",
+$ kubectl auth can-i create deployments --namespace prod
-  "kind": "SubjectAccessReview",
+no
-  "spec": {
-    "resourceAttributes": {
-      "namespace": "kittensandponies",
-      "verb": "get",
-      "group": "unicorn.example.org",
-      "resource": "pods"
-    },
-    "user": "jane",
-    "group": [
-      "group1",
-      "group2"
-    ],
-    "extra": {
-      "scopes": [
-        "openid",
-        "profile"
-      ]
-    }
-  }
-}
-__EOF__
-
---- snip lots of output ---
-
-I0913 08:12:31.362873   27425 request.go:908] Response Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1","metadata":{"creationTimestamp":null},"spec":{"resourceAttributes":{"namespace":"kittensandponies","verb":"GET","group":"unicorn.example.org","resource":"pods"},"user":"jane","group":["group1","group2"],"extra":{"scopes":["openid","profile"]}},"status":{"allowed":true}}
-subjectaccessreview "" created
 ```
 
-This is useful for debugging access problems, in that you can use this resource
+Administrators can combine this with ["user impersonation"](/docs/admin/authentication/#user-impersonation)
-to determine what access an authorizer is granting.
+to determine what action other users can perform.
+
+```bash
+$ kubectl auth can-i list secrets --namespace dev --as dave
+no
+```
+
+`SelfSubjectAccessReview` is part of the `authorization.k8s.io` API group, which exposes the
+API server authorization to external services. Other resources in this group include:
+
+* `SubjectAccessReview` - Access review for any user, not just the current one. Useful for delegating authorization decisions to the API server. For example, the kubelet and extension API servers use this to determine user access to their own APIs.
+* `LocalSubjectAccessReview` - Like `SubjectAccessReview` but restricted to a specific namespace.
+* `SelfSubjectRulesReview` - A review which returns the set of actions a user can perform within a namespace. Useful for users to quickly summarize their own access, or for UIs to hide/show actions.
+
+These APIs can be queried by creating normal Kubernetes resources, where the response "status"
+field of the returned object is the result of the query.
+
+```bash
+$ kubectl create -f - -o yaml << EOF
+{
+    "kind": "SelfSubjectAccessReview",
+    "apiVersion": "authorization.k8s.io/v1",
+    "spec": {
+         "resourceAttributes": {
+             "group": "apps",
+             "name": "deployments",
+             "verb": "create",
+             "namespace": "dev"
+         }
+     }
+}
+EOF
+{
+    "apiVersion": "authorization.k8s.io/v1",
+    "kind": "SelfSubjectAccessReview",
+    "metadata": {
+        "creationTimestamp": null
+    },
+    "spec": {
+        "resourceAttributes": {
+            "group": "apps",
+            "name": "deployments",
+            "namespace": "dev",
+            "verb": "create"
+        }
+    },
+    "status": {
+        "allowed": true
+    }
+}
+```
 
 ## Using Flags for Your Authorization Module