Merge pull request #799 from ericchiang/thirdpartyresources

Documentation: warn admins not to edit dex ThirdPartyResources manually

Documentation/kubernetes.md

@@ -47,6 +47,8 @@ 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).
+
 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:
 
 * [coreos-kubernetes][coreos-kubernetes] repo for vagrant and VirtualBox users.

Documentation/storage.md

@@ -10,6 +10,8 @@ __NOTE:__ Dex requires Kubernetes version 1.4+.
 
 Kubernetes third party resources are a way for applications to create new resources types in the Kubernetes API. This allows dex to run on top of an existing Kubernetes cluster without the need for an external database. While this storage may not be appropriate for a large number of users, it's extremely effective for many Kubernetes use cases.
 
+The rest of this section will explore internal details of how dex uses `ThirdPartyResources`. __Admins should not interact with these resources directly__, except when debugging. These resources are only designed to store state and aren't meant to be consumed by humans. For modifying dex's state dynamically see the [API documentation](api.md).
+
 The `ThirdPartyResource` type acts as a description for the new resource a user wishes to create. The following an example of a resource managed by dex:
 
 ```
@@ -32,7 +34,7 @@ kind: OAuth2Client
 apiVersion: oidc.coreos.com/v1
 metadata:
   namespace: foobar
-  name: client-foo
+  name: ( opaque hash )
 
 # Custom fields defined by dex.
 clientID: "aclientid"