Authz: Explain how to determine request verbs.

docs/admin/authorization.md

@@ -18,7 +18,7 @@ The following implementations are available, and are selected by flag:
 need authorization.
   - `--authorization-mode=ABAC` allows for a simple local-file-based user-configured
 authorization policy.  ABAC stands for Attribute-Based Access Control.
-authorization policy. 
+authorization policy.
   - `--authorization-mode=RBAC` is an experimental implementation which allows
 for authorization to be driven by the Kubernetes API.
 RBAC stands for Roles-Based Access Control.
@@ -43,17 +43,25 @@ A request has the following attributes that can be considered for authorization:
   - group (the list of group names the authenticated user is a member of).
   - whether the request is for an API resource.
   - the request path.
-    - allows authorizing access to miscellaneous endpoints like `/api` or
-`/healthz` (see [kubectl](#kubectl)).
+    - allows authorizing access to miscellaneous non-resource endpoints like `/api` or `/healthz` (see [kubectl](#kubectl)).
   - the request verb.
-    - API verbs like `get`, `list`, `create`, `update`, `watch`, `delete`, and
-`deletecollection` are used for API requests
-    - HTTP verbs like `get`, `post`, `put`, and `delete` are used for non-API
+    - API verbs `get`, `list`, `create`, `update`, `watch`, `delete`, and `deletecollection` are used for resource requests
+    - HTTP verbs `get`, `post`, `put`, and `delete` are used for non-resource
 requests
-  - what resource is being accessed (for API requests only)
-  - the namespace of the object being accessed (for namespaced API requests
+  - what resource is being accessed (for resource requests only)
+  - the namespace of the object being accessed (for namespaced resource requests
 only)
-  - the API group being accessed (for API requests only)
+  - the API group being accessed (for resource requests only)
+
+The request verb for a resource API endpoint can be determined by the HTTP verb used and whether or not the request acts on an individual resource or a collection of resources:
+
+HTTP verb | request verb
+----------|---------------
+POST      | create
+GET, HEAD | get (for individual resources), list (for collections)
+PUT       | update
+PATCH     | patch
+DELETE    | delete (for individual resources), deletecollection (for collections)
 
 We anticipate adding more attributes to allow finer grained access control and
 to assist in policy management.
@@ -97,17 +105,17 @@ A request has attributes which correspond to the properties of a policy object.
 When a request is received, the attributes are determined.  Unknown attributes
 are set to the zero value of its type (e.g. empty string, 0, false).
 
-A property set to "*" will match any value of the corresponding attribute.
+A property set to `"*"` will match any value of the corresponding attribute.
 
 The tuple of attributes is checked for a match against every policy in the
 policy file. If at least one line matches the request attributes, then the
 request is authorized (but may fail later validation).
 
 To permit any user to do something, write a policy with the user property set to
-"*".
+`"*"`.
 
 To permit a user to do anything, write a policy with the apiGroup, namespace,
-resource, and nonResourcePath properties set to "*".
+resource, and nonResourcePath properties set to `"*"`.
 
 ### Kubectl
 
@@ -130,11 +138,31 @@ up the verbosity:
 
 ### Examples
 
- 1. Alice can do anything to all resources:                  `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}`
- 2. Kubelet can read any pods:                               `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}}`
- 3. Kubelet can read and write events:                       `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}}`
- 4. Bob can just read pods in namespace "projectCaribou":    `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "bob", "namespace": "projectCaribou", "resource": "pods", "readonly": true}}`
- 5. Anyone can make read-only requests to all non-API paths: `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "*", "readonly": true, "nonResourcePath": "*"}}`
+ 1. Alice can do anything to all resources:
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}
+    ```
+ 2. Kubelet can read any pods:
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}}
+    ```
+ 3. Kubelet can read and write events:
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}}
+    ```
+ 4. Bob can just read pods in namespace "projectCaribou":
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "bob", "namespace": "projectCaribou", "resource": "pods", "readonly": true}}
+    ```
+ 5. Anyone can make read-only requests to all non-resource paths:
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "*", "readonly": true, "nonResourcePath": "*"}}
+    ```
 
 [Complete file example](http://releases.k8s.io/{{page.githubbranch}}/pkg/auth/authorizer/abac/example_policy_file.jsonl)
 
@@ -147,7 +175,7 @@ according to the naming convention:
 system:serviceaccount:<namespace>:<serviceaccountname>
 ```
 Creating a new namespace also causes a new service account to be created, of
-this form:*
+this form:
 
 ```shell
 system:serviceaccount:<namespace>:default