diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md index 7315d27fbba..5dc95b2e933 100644 --- a/content/en/docs/reference/_index.md +++ b/content/en/docs/reference/_index.md @@ -76,6 +76,10 @@ operator to use or manage a cluster. * [kube-proxy configuration (v1alpha1)](/docs/reference/config-api/kube-proxy-config.v1alpha1/) * [`audit.k8s.io/v1` API](/docs/reference/config-api/apiserver-audit.v1/) +## Config APIs + +* [Client authentication API (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/) + ## Design Docs An archive of the design docs for Kubernetes functionality. Good starting points are diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index 0a830586f0d..d09ffa23a23 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -955,7 +955,8 @@ When run from an interactive session, `stdin` is exposed directly to the plugin. [TTY check](https://godoc.org/golang.org/x/crypto/ssh/terminal#IsTerminal) to determine if it's appropriate to prompt a user interactively. -To use bearer token credentials, the plugin returns a token in the status of the `ExecCredential`. +To use bearer token credentials, the plugin returns a token in the status of the +[`ExecCredential`](/docs/reference/config-api/client-authentication.v1beta1/#client-authentication-k8s-io-v1beta1-ExecCredential) ```json { @@ -1005,6 +1006,7 @@ RFC3339 timestamp. Presence or absence of an expiry has the following impact: } } ``` + To enable the exec plugin to obtain cluster-specific information, set `provideClusterInfo` on the `user.exec` field in the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/). The plugin will then be supplied with an environment variable, `KUBERNETES_EXEC_INFO`. @@ -1029,3 +1031,8 @@ The following `ExecCredential` manifest describes a cluster information sample. } } ``` + +## {{% heading "whatsnext" %}} + +* Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/) + diff --git a/content/en/docs/reference/config-api/client-authentication.v1beta1.md b/content/en/docs/reference/config-api/client-authentication.v1beta1.md new file mode 100644 index 00000000000..e78edd23f65 --- /dev/null +++ b/content/en/docs/reference/config-api/client-authentication.v1beta1.md @@ -0,0 +1,252 @@ +--- +title: Client Authentication (v1beta1) +content_type: tool-reference +package: client.authentication.k8s.io/v1beta1 +auto_generated: true +--- + + +## Resource Types + + +- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential) + + + + +## `ExecCredential` {#client-authentication-k8s-io-v1beta1-ExecCredential} + + + + + +ExecCredential is used by exec-based plugins to communicate credentials to +HTTP transports. + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
apiVersion
string		client.authentication.k8s.io/v1beta1
kind
string		ExecCredential
spec [Required]
+ExecCredentialSpec +		 + Spec holds information passed to the plugin by the transport.
status
+ExecCredentialStatus +		 + Status is filled in by the plugin and holds the credentials that the transport +should use to contact the API.
+ + + +## `Cluster` {#client-authentication-k8s-io-v1beta1-Cluster} + + + + +**Appears in:** + +- [ExecCredentialSpec](#client-authentication-k8s-io-v1beta1-ExecCredentialSpec) + + +Cluster contains information to allow an exec plugin to communicate +with the kubernetes cluster being authenticated to. + +To ensure that this struct contains everything someone would need to communicate +with a kubernetes cluster (just like they would via a kubeconfig), the fields +should shadow "k8s.io/client-go/tools/clientcmd/api/v1".Cluster, with the exception +of CertificateAuthority, since CA data will always be passed to the plugin as bytes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
server [Required]
+string +		 + Server is the address of the kubernetes cluster (https://hostname:port).
tls-server-name
+string +		 + TLSServerName is passed to the server for SNI and is used in the client to +check server certificates against. If ServerName is empty, the hostname +used to contact the server is used.
insecure-skip-tls-verify
+bool +		 + InsecureSkipTLSVerify skips the validity check for the server's certificate. +This will make your HTTPS connections insecure.
certificate-authority-data
+[]byte +		 + CAData contains PEM-encoded certificate authority certificates. +If empty, system roots should be used.
proxy-url
+string +		 + ProxyURL is the URL to the proxy to be used for all requests to this +cluster.
config
+k8s.io/apimachinery/pkg/runtime.RawExtension +		 + Config holds additional config data that is specific to the exec +plugin with regards to the cluster being authenticated to. + +This data is sourced from the clientcmd Cluster object's +extensions[client.authentication.k8s.io/exec] field: + +clusters: +- name: my-cluster + cluster: + ... + extensions: + - name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config + extension: + audience: 06e3fbd18de8 # arbitrary config + +In some environments, the user config may be exactly the same across many clusters +(i.e. call this exec plugin) minus some details that are specific to each cluster +such as the audience. This field allows the per cluster config to be directly +specified with the cluster info. Using this field to store secret data is not +recommended as one of the prime benefits of exec plugins is that no secrets need +to be stored directly in the kubeconfig.
+ + + +## `ExecCredentialSpec` {#client-authentication-k8s-io-v1beta1-ExecCredentialSpec} + + + + +**Appears in:** + +- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential) + + +ExecCredentialSpec holds request and runtime specific information provided by +the transport. + + + + + + + + + + + + + +
FieldDescription
cluster
+Cluster +		 + Cluster contains information to allow an exec plugin to communicate with the +kubernetes cluster being authenticated to. Note that Cluster is non-nil only +when provideClusterInfo is set to true in the exec provider config (i.e., +ExecConfig.ProvideClusterInfo).
+ + + +## `ExecCredentialStatus` {#client-authentication-k8s-io-v1beta1-ExecCredentialStatus} + + + + +**Appears in:** + +- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential) + + +ExecCredentialStatus holds credentials for the transport to use. + +Token and ClientKeyData are sensitive fields. This data should only be +transmitted in-memory between client and exec plugin process. Exec plugin +itself should at least be protected via file permissions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
expirationTimestamp
+meta/v1.Time +		 + ExpirationTimestamp indicates a time when the provided credentials expire.
token [Required]
+string +		 + Token is a bearer token used by the client for request authentication.
clientCertificateData [Required]
+string +		 + PEM-encoded client TLS certificates (including intermediates, if any).
clientKeyData [Required]
+string +		 + PEM-encoded private key for the above certificate.
+ +