authentication: document client-go exec plugins

docs/admin/authentication.md

@@ -683,3 +683,144 @@ rules:
   verbs: ["impersonate"]
   resourceNames: ["view", "development"]
 ```
+
+## client-go credential plugins
+
+{% assign for_k8s_version="v1.10" %}{% include feature-state-alpha.md %}
+
+`k8s.io/client-go` and tools using it such as `kubectl` and `kubelet` are able to execute an
+external command to receive user credentials.
+
+This feature is intended for client side integrations with IdPs, such as cloud IAM services, and
+protocols not natively supported by `k8s.io/client-go`, such as Kerberos, LDAP, and custom OAuth2
+flavors.
+
+### Configuration
+
+Credential plugins are configured through [`kubectl` config files](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
+as part of the user fields.
+
+```yaml
+apiVersion: v1
+kind: Config
+users:
+- name: my-user
+  user:
+    exec:
+      # Command to execute. Required.
+      command: "example-client-go-exec-plugin"
+
+      # API version to use when encoding and decoding the ExecCredentials
+      # resource. Required.
+      #
+      # The API version returned by the plugin MUST match the version encoded.
+      apiVersion: "client.authentication.k8s.io/v1alpha1"
+
+      # Environment variables to set when executing the plugin. Optional.
+      env:
+      - name: "FOO"
+        value: "bar"
+
+      # Arguments to pass when executing the plugin. Optional.
+      args:
+      - "arg1"
+      - "arg2"
+clusters:
+- name: my-cluster
+  cluster:
+    server: "https://172.17.4.100:6443"
+    certificate-authority: "/etc/kubernetes/ca.pem"
+contexts:
+- name: my-cluster
+  context:
+    cluster: my-cluster
+    user: my-user
+current-context: my-cluster
+```
+
+Relative command paths are interpreted as relative to the directory of the config file. If
+KUBECONFIG is set to `/home/jane/kubeconfig` and the exec command is `./bin/example-client-go-exec-plugin`,
+the binary `/home/jane/bin/example-client-go-exec-plugin` is executed.
+
+```yaml
+- name: my-user
+  user:
+    exec:
+      # Path relative to the directory of the kubeconfig
+      command: "./bin/example-client-go-exec-plugin"
+      apiVersion: "client.authentication.k8s.io/v1alpha1"
+```
+
+### Input and output formats
+
+When executing the command, `k8s.io/client-go` sets the `KUBERNETES_EXEC_INFO` environment
+variable to a JSON serialized [`ExecCredential`](https://github.com/kubernetes/client-go/tree/master/pkg/apis/clientauthentication)
+resource.
+
+```
+KUBERNETES_EXEC_INFO='{
+  "apiVersion": "client.authentication.k8s.io/v1alpha1",
+  "kind": "ExecCredential",
+  "spec": {
+    "interactive": true
+  }
+}'
+```
+
+When responding to a 401 HTTP status code (indicating invalid credentials), this object will
+include metadata about the response.
+
+```json
+{
+  "apiVersion": "client.authentication.k8s.io/v1alpha1",
+  "kind": "ExecCredential",
+  "spec": {
+    "response": {
+      "code": 401,
+      "header": {
+        "WWW-Authenticate": [
+          "Bearer realm=ldap.example.com"
+        ]
+      },
+    },
+    "interactive": true
+  }
+}
+```
+
+The executed command is expected to print an `ExceCredenial` to `stdout`. `k8s.io/client-go`
+will then use the returned bearer token in the `status` when authenticating against the
+Kubernetes API.
+
+```json
+{
+  "apiVersion": "client.authentication.k8s.io/v1alpha1",
+  "kind": "ExecCredential",
+  "status": {
+    "token": "my-bearer-token"
+  }
+}
+```
+
+Optionally, this output can include the expiry of the token formatted as a RFC3339 timestamp.
+If an expiry is omitted, the bearer token is cached until the server responds with a 401 HTTP
+status code.
+
+```json
+{
+  "apiVersion": "client.authentication.k8s.io/v1alpha1",
+  "kind": "ExecCredential",
+  "status": {
+    "token": "my-bearer-token",
+    "expirationTimestamp": "2018-03-05T17:30:20-08:00"
+  }
+}
+```
+
+### Interactive sessions
+
+When plugins are executed from an interactive session, `stdin` and `stderr` are exposed to the
+plugin to actively prompt the user for input for interactive logins.
+
+For example, a plugin could prompt for an LDAP username and password to exchange for a bearer
+token, perform an interactive device flow, or open a browser.