From 8b990438393b8690bab355aaf0ae620de4b9b012 Mon Sep 17 00:00:00 2001
From: Eric Chiang <eric.chiang.m@gmail.com>
Date: Wed, 26 Apr 2017 17:44:27 -0700
Subject: [PATCH] rbac: document resourceNames and note they can't be used for
 creates

---
 docs/admin/authorization/index.md |  1 +
 docs/admin/authorization/rbac.md  | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/admin/authorization/index.md b/docs/admin/authorization/index.md
index 131a2d66bc..1604d514c4 100644
--- a/docs/admin/authorization/index.md
+++ b/docs/admin/authorization/index.md
@@ -54,6 +54,7 @@ A request has the following attributes that can be considered for authorization:
   - what subresource 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 resource requests only); an empty string designates the [core API group](/docs/api/)
+  - the name of the resource being accessed (only for resource requests using `get`, `update`, `patch`, and `delete` verbs)
 
 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:
 
diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md
index c6fcb1278b..28349289e2 100644
--- a/docs/admin/authorization/rbac.md
+++ b/docs/admin/authorization/rbac.md
@@ -168,6 +168,28 @@ rules:
   verbs: ["get", "list"]
 ```
 
+Resources can also be referred to by name for certain requests through the `resourceNames` list.
+When specified, requests using the "get", "delete", "update", and "patch" verbs can be restricted
+to individual instances of a resource. To restrict a subject to only "get" and "update" a single
+configmap, you would write:
+
+```yaml
+kind: Role
+apiVersion: rbac.authorization.k8s.io/v1beta1
+metadata:
+  namespace: default
+  name: configmap-updater
+rules:
+- apiGroups: [""]
+  resources: ["configmap"]
+  resourceNames: ["my-configmap"]
+  verbs: ["update", "get"]
+```
+
+Notably, `resourceNames` can NOT be used to limit requests using the "create" verb because
+authorizers only have access to information that can be obtained from the request URL, method,
+and headers (resource names in a "create" request are part of the request body).
+
 #### Role Examples
 
 Only the `rules` section is shown in the following examples.