fix service-account related doc

docs/admin/authorization.md

@@ -57,10 +57,11 @@ The following implementations are available, and are selected by flag:
 
 ### Request Attributes
 
-A request has 4 attributes that can be considered for authorization:
+A request has 5 attributes that can be considered for authorization:
   - user (the user-string which a user was authenticated as).
-  - whether the request is readonly (GETs are readonly)
-  - what resource is being accessed
+  - group (the list of group names the authenticated user is a member of).
+  - whether the request is readonly (GETs are readonly).
+  - what resource is being accessed.
     - applies only to the API endpoints, such as
         `/api/v1/namespaces/default/pods`.  For miscellaneous endpoints, like `/version`, the
         resource is the empty string.
@@ -78,7 +79,8 @@ The file format is [one JSON object per line](http://jsonlines.org/).  There sho
 one map per line.
 
 Each line is a "policy object".  A policy object is a map with the following properties:
-  - `user`, type string; the user-string from `--token-auth-file`
+  - `user`, type string; the user-string from `--token-auth-file`. If you specify `user`, it must match the username of the authenticated user.
+  - `group`, type string; if you specify `group`, it must match one of the groups of the authenticated user.
   - `readonly`, type boolean, when true, means that the policy only applies to GET
       operations.
   - `resource`, type string; a resource from an URL, such as `pods`.
@@ -151,7 +153,7 @@ type Authorizer interface {
 to determine whether or not to allow each API action.
 
 An authorization plugin is a module that implements this interface.
-Authorization plugin code goes in `pkg/auth/authorization/$MODULENAME`.
+Authorization plugin code goes in `pkg/auth/authorizer/$MODULENAME`.
 
 An authorization module can be completely implemented in go, or can call out
 to a remote authorization service.  Authorization modules can implement

docs/admin/service-accounts-admin.md

@@ -97,12 +97,13 @@ account, and the controller will update it with a generated token:
 secret.json:
 {
     "kind": "Secret",
+    "apiVersion": "v1",
     "metadata": {
         "name": "mysecretname",
         "annotations": {
             "kubernetes.io/service-account.name": "myserviceaccount"
         }
-	}
+    },
     "type": "kubernetes.io/service-account-token"
 }
 ```
@@ -118,6 +119,11 @@ kubectl describe secret mysecretname
 kubectl delete secret mysecretname
 ```
 
+### Service Account Controller
+
+Service Account Controller manages ServiceAccount inside namespaces, and ensures
+a ServiceAccount named "default" exists in every active namespace.
+
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admin/service-accounts-admin.md?pixel)]()

docs/design/secrets.md

@@ -322,8 +322,8 @@ type SecretType string
 
 const (
     SecretTypeOpaque              SecretType = "Opaque"                                 // Opaque (arbitrary data; default)
-    SecretTypeKubernetesAuthToken SecretType = "KubernetesAuth"      // Kubernetes auth token
-    SecretTypeDockerRegistryAuth  SecretType = "DockerRegistryAuth"  // Docker registry auth
+    SecretTypeServiceAccountToken SecretType = "kubernetes.io/service-account-token"    // Kubernetes auth token
+    SecretTypeDockercfg           SecretType = "kubernetes.io/dockercfg"                // Docker registry auth
     // FUTURE: other type values
 )
 

docs/user-guide/service-accounts.md

@@ -61,7 +61,7 @@ pods/podname -o yaml`), you can see the `spec.serviceAccount` field has been
 You can access the API using a proxy or with a client library, as described in
 [Accessing the Cluster](accessing-the-cluster.md#accessing-the-api-from-a-pod).
 
-## Using Multiple Service Accounts
+## Using Multiple Service Accounts.
 
 Every namespace has a default service account resource called "default".
 You can list this and any other serviceAccount resources in the namespace with this command:
@@ -120,6 +120,45 @@ $ kubectl delete serviceaccount/build-robot
 ```
 
 <!-- TODO: describe how to create a pod with no Service Account. -->
+Note that if a pod does not have a `ServiceAccount` set, the `ServiceAccount` will be set to `default`.
+
+## Manually create a service account API token.
+
+Suppose we have an existing service account named "build-robot" as mentioned above, and we create
+a new secret manually.
+
+```console
+$ cat > /tmp/build-robot-secret.yaml <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: build-robot-secret
+  annotations: 
+    kubernetes.io/service-account.name: build-robot
+type: kubernetes.io/service-account-token
+EOF
+$ kubectl create -f /tmp/build-robot-secret.yaml
+secrets/build-robot-secret
+```
+
+Now you can confirm that the newly built secret is populated with an API token for the "build-robot" service account.
+
+```console
+kubectl describe secrets/build-robot-secret 
+Name:   build-robot-secret
+Namespace:  default
+Labels:   <none>
+Annotations:  kubernetes.io/service-account.name=build-robot,kubernetes.io/service-account.uid=870ef2a5-35cf-11e5-8d06-005056b45392
+
+Type: kubernetes.io/service-account-token
+
+Data
+====
+ca.crt: 1220 bytes
+token:  
+```
+
+> Note that the content of `token` is elided here.
 
 ## Adding Secrets to a service account.
 
@@ -128,7 +167,6 @@ TODO: Test and explain how to use additional non-K8s secrets with an existing se
 TODO explain:
   - The token goes to: "/var/run/secrets/kubernetes.io/serviceaccount/$WHATFILENAME"
 
-
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/service-accounts.md?pixel)]()
 <!-- END MUNGE: GENERATED_ANALYTICS -->