Kubernetes example: Add RBAC resources and serviceAccount to YAML manifest, remove some references to deprecated TPR approach

Documentation/kubernetes.md

@@ -48,7 +48,7 @@ Additional notes:
 
 The dex repo contains scripts for running dex on a Kubernetes cluster with authentication through GitHub. The dex service is exposed using a [node port][node-port] on port 32000. This likely requires a custom `/etc/hosts` entry pointed at one of the cluster's workers.
 
-Because dex uses `ThirdPartyResources` to store state, no external database is needed. For more details see the [storage documentation](storage.md#kubernetes-third-party-resources).
+Because dex uses [CRDs](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) to store state, no external database is needed. For more details see the [storage documentation](storage.md#kubernetes-third-party-resources).
 
 There are many different ways to spin up a Kubernetes development cluster, each with different host requirements and support for API server reconfiguration. At this time, this guide does not have copy-pastable examples, but can recommend the following methods for spinning up a cluster:
 
@@ -61,7 +61,6 @@ To run dex on Kubernetes perform the following steps:
 2. Spin up a Kubernetes cluster with the appropriate flags and CA volume mount.
 3. Create secrets for TLS and for your [GitHub OAuth2 client credentials][github-oauth2].
 4. Deploy dex.
-5. Create and assign 'dex' cluster role to dex service account ([to enable dex to manage its CRDs, if RBAC authorization is used](https://github.com/dexidp/dex/blob/master/Documentation/storage.md#kubernetes-custom-resource-definitions-crds)).
 
 ### Generate TLS assets
 
@@ -140,7 +139,7 @@ Create the dex deployment, configmap, and node port service.
 $ kubectl create -f dex.yaml
 ```
 
-Assign cluster role to dex service account so it can create third party resources [Kubernetes third party resources](storage.md).
+The Dex pod requires access to manage [Custom Resource Definitions](https://github.com/dexidp/dex/blob/master/Documentation/storage.md#kubernetes-custom-resource-definitions-crds) within Kubernetes, so the example manifest also creates a service account and RBAC role bindings to provide these permissions.
 
 __Caveats:__ No health checking is configured because dex does its own TLS termination complicating the setup. This is a known issue and can be tracked [here][dex-healthz].
 

Documentation/storage.md

@@ -115,11 +115,15 @@ subjects:
 ```
 
 
-## Kubernetes third party resources(TPRs)
+## DEPRECATED: Kubernetes third party resources(TPRs)
 
-__NOTE:__ TPRs will be deprecated by Kubernetes version 1.8.
+__NOTE:__ TPRs are deprecated as of Kubernetes version 1.8.
 
-The default behavior of dex from release v2.7.0 onwards is to utitlize CRDs to manage its custom resources. If users would like to use dex with a Kubernetes version lower than 1.7, they will have to force dex to use TPRs instead of CRDs by setting the `UseTPR` flag in the storage configuration as shown below:
+The default behavior of dex from release v2.7.0 onwards is to utilize CRDs to manage its custom resources. If users would like to use dex with a Kubernetes version lower than 1.7, they will have to force dex to use TPRs instead of CRDs.
+
+These instructions have been preserved for anybody who needs to use an older version of Dex and/or Kubernetes, but this is not the recommended approach. See [Migrating from TPRs to CRDs](#migrating-from-tprs-to-crds) below for information on migrating an existing installation to the new approach.
+
+If you do wish to use TPRs, you may do so by setting the `UseTPR` flag in the storage configuration as shown below:
 
 ```
 storage:

examples/k8s/dex.yaml

@@ -11,6 +11,7 @@ spec:
       labels:
         app: dex
     spec:
+      serviceAccountName: dex # This is created below
       containers:
       - image: quay.io/dexidp/dex:v2.10.0
         name: dex
@@ -104,3 +105,35 @@ spec:
     nodePort: 32000
   selector:
     app: dex
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  labels:
+    app: dex
+  name: dex
+---
+apiVersion: rbac.authorization.k8s.io/v1beta1
+kind: ClusterRole
+metadata:
+  name: dex
+rules:
+- apiGroups: ["dex.coreos.com"] # API group created by dex
+  resources: ["*"]
+  verbs: ["*"]
+- apiGroups: ["apiextensions.k8s.io"]
+  resources: ["customresourcedefinitions"]
+  verbs: ["create"] # To manage its own resources, dex must be able to create customresourcedefinitions
+---
+apiVersion: rbac.authorization.k8s.io/v1beta1
+kind: ClusterRoleBinding
+metadata:
+  name: dex
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: dex
+subjects:
+- kind: ServiceAccount
+  name: dex           # Service account assigned to the dex pod, created above
+  namespace: default  # The namespace dex is running in