From 19e65e224a2fb9e31dc8aa078e4aecaf30ff1d79 Mon Sep 17 00:00:00 2001
From: Jimmy Cuadra <jimmy@jimmycuadra.com>
Date: Tue, 27 Sep 2016 21:30:08 -0700
Subject: [PATCH] Document subresources in RBAC.

---
 docs/admin/authorization.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/admin/authorization.md b/docs/admin/authorization.md
index 1e7b180773..0c8508a1ec 100644
--- a/docs/admin/authorization.md
+++ b/docs/admin/authorization.md
@@ -323,6 +323,32 @@ roleRef:
   apiVersion: rbac.authorization.k8s.io/v1alpha1
 ```
 
+### Referring to Resources
+
+Most resources are represented by a string representation of their name, such as "pods", just as it
+appears in the URL for the relevant API endpoint. However, some Kubernetes APIs involve a
+"subresource" such as the logs for a pod. The URL for the pods logs endpoint is:
+
+```
+GET /api/v1/namespaces/{namespace}/pods/{name}/log
+```
+
+In this case, "pods" is the namespaced resource, and "log" is a subresource of pods. To represent
+this in an RBAC role, use a slash to delimit the resource and subresource names. To allow a subject
+to read both pods and pod logs, you would write:
+
+```yaml
+kind: Role
+apiVersion: rbac.authorization.k8s.io/v1alpha1
+metadata:
+  namespace: default
+  name: pod-and-pod-logs-reader
+rules:
+  - apiGroups: [""]
+    resources: ["pods", "pods/log"]
+    verbs: ["get", "list"]
+```
+
 ### Referring to Subjects
 
 RoleBindings and ClusterRoleBindings bind "subjects" to "roles".
@@ -351,6 +377,7 @@ to groups with the `system:` prefix.
 Only the `subjects` section of a RoleBinding object shown in the following examples.
 
 For a user called `alice@example.com`, specify
+
 ```yaml
 subjects:
   - kind: User
@@ -358,6 +385,7 @@ subjects:
 ```
 
 For a group called `frontend-admins`, specify:
+
 ```yaml
 subjects:
   - kind: Group
@@ -365,6 +393,7 @@ subjects:
 ```
 
 For the default service account in the kube-system namespace:
+
 ```yaml
 subjects:
  - kind: ServiceAccount
@@ -373,6 +402,7 @@ subjects:
 ```
 
 For all service accounts in the `qa` namespace:
+
 ```yaml
 subjects:
 - kind: Group
@@ -380,6 +410,7 @@ subjects:
 ```
 
 For all service accounts everywhere:
+
 ```yaml
 subjects:
 - kind: Group