Merge branch 'master' of https://github.com/fbsolo/kubernetes.github.io

docs/admin/authentication.md

@@ -45,8 +45,13 @@ with the request:
 All values are opaque to the authentication system and only hold significance
 when interpreted by an [authorizer](/docs/admin/authorization/).
 
-Multiple authentication methods may be enabled at once. In these cases, the first
-authenticator to successfully authenticate the request short-circuits evaluation.
+You can enable multiple authentication methods at once. You should usually use at least two methods:
+
+ - service account tokens for service accounts
+ - at least one other method for user authentication.
+
+When multiple are enabled, the first authenticator module
+to successfully authenticate the request short-circuits evaluation.
 The API server does not guarantee the order authenticators run in.
 
 ### X509 Client Certs
@@ -189,7 +194,9 @@ verify ID token's signature and determine the end users identity.
 To enable the plugin, pass the following required flags:
 
 * `--oidc-issuer-url` URL of the provider which allows the API server to discover
-public signing keys. Only URLs which use the `https://` scheme are accepted.
+public signing keys. Only URLs which use the `https://` scheme are accepted.  This is typically
+the provider's URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".
+
 * `--oidc-client-id` A client id that all tokens must be issued for.
 
 Importantly, the API server is not an OAuth2 client, rather it can only be
@@ -212,6 +219,17 @@ other claims, such as `email`, depending on their provider.
 * `--oidc-groups-claim` JWT claim to use as the user's group. If the claim is present
 it must be an array of strings.
 
+Kubernetes does not provide an OpenID Connect Identity Provider.
+You can use an existing public OpenID Connect Identity Provider (such as Google, or [others](http://connect2id.com/products/nimbus-oauth-openid-connect-sdk/openid-connect-providers)).
+Or, you can run your own Identity Provider, such as CoreOS [dex](https://github.com/coreos/dex), [Keycloak](https://github.com/keycloak/keycloak) or CloudFoundary [UAA](https://github.com/cloudfoundry/uaa).
+
+The provider needs to support [OpenID connect discovery]https://openid.net/specs/openid-connect-discovery-1_0.html); not all do.
+
+Setup instructions for specific systems:
+
+- [UAA]: http://apigee.com/about/blog/engineering/kubernetes-authentication-enterprise
+- [Dex]: https://speakerdeck.com/ericchiang/kubernetes-access-control-with-dex
+
 ### Webhook Token Authentication
 
 Webhook authentication is a hook for verifying bearer tokens.

docs/user-guide/secrets/index.md

@@ -642,8 +642,6 @@ you must use `ls -la` to see them when listing directory contents.
 
 ### Use-case: Secret visible to one container in a pod
 
-<a name="use-case-two-containers"></a>
-
 Consider a program that needs to handle HTTP requests, do some complex business
 logic, and then sign some messages with an HMAC.  Because it has complex
 application logic, there might be an unnoticed remote file reading exploit in
@@ -688,7 +686,7 @@ Therefore, one Pod does not have access to the secrets of another pod.
 There may be several containers in a pod.  However, each container in a pod has
 to request the secret volume in its `volumeMounts` for it to be visible within
 the container.  This can be used to construct useful [security partitions at the
-Pod level](#use-case-two-containers).
+Pod level](#use-case-secret-visible-to-one-container-in-a-pod).
 
 ### Risks