diff --git a/content/en/docs/tasks/configure-pod-container/configure-service-account.md b/content/en/docs/tasks/configure-pod-container/configure-service-account.md index 1777b5e41a5b9..2cc040aa288f9 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-service-account.md +++ b/content/en/docs/tasks/configure-pod-container/configure-service-account.md @@ -11,22 +11,20 @@ weight: 90 {{% capture overview %}} A service account provides an identity for processes that run in a Pod. -*This is a user introduction to Service Accounts. See also the +*This is a user introduction to Service Accounts. See also the [Cluster Admin Guide to Service Accounts](/docs/reference/access-authn-authz/service-accounts-admin/).* {{< note >}} This document describes how service accounts behave in a cluster set up -as recommended by the Kubernetes project. Your cluster administrator may have +as recommended by the Kubernetes project. Your cluster administrator may have customized the behavior in your cluster, in which case this documentation may not apply. {{< /note >}} When you (a human) access the cluster (for example, using `kubectl`), you are authenticated by the apiserver as a particular User Account (currently this is -usually `admin`, unless your cluster administrator has customized your -cluster). Processes in containers inside pods can also contact the apiserver. -When they do, they are authenticated as a particular Service Account (for example, -`default`). +usually `admin`, unless your cluster administrator has customized your cluster). Processes in containers inside pods can also contact the apiserver. +When they do, they are authenticated as a particular Service Account (for example, `default`). {{% /capture %}} @@ -43,16 +41,12 @@ When they do, they are authenticated as a particular Service Account (for exampl When you create a pod, if you do not specify a service account, it is automatically assigned the `default` service account in the same namespace. -If you get the raw json or yaml for a pod you have created (for example, `kubectl get pods/podname -o yaml`), -you can see the `spec.serviceAccountName` field has been -[automatically set](/docs/user-guide/working-with-resources/#resources-are-automatically-modified). +If you get the raw json or yaml for a pod you have created (for example, `kubectl get pods/ -o yaml`), you can see the `spec.serviceAccountName` field has been [automatically set](/docs/user-guide/working-with-resources/#resources-are-automatically-modified). -You can access the API from inside a pod using automatically mounted service account credentials, -as described in [Accessing the Cluster](/docs/user-guide/accessing-the-cluster/#accessing-the-api-from-a-pod). +You can access the API from inside a pod using automatically mounted service account credentials, as described in [Accessing the Cluster](/docs/user-guide/accessing-the-cluster/#accessing-the-api-from-a-pod). The API permissions of the service account depend on the [authorization plugin and policy](/docs/reference/access-authn-authz/authorization/#authorization-modules) in use. -In version 1.6+, you can opt out of automounting API credentials for a service account by setting -`automountServiceAccountToken: false` on the service account: +In version 1.6+, you can opt out of automounting API credentials for a service account by setting `automountServiceAccountToken: false` on the service account: ```yaml apiVersion: v1 @@ -85,6 +79,10 @@ You can list this and any other serviceAccount resources in the namespace with t ```shell kubectl get serviceAccounts +``` +The output is similar to this: + +``` NAME SECRETS AGE default 1 1d ``` @@ -98,13 +96,16 @@ kind: ServiceAccount metadata: name: build-robot EOF -serviceaccount/build-robot created ``` If you get a complete dump of the service account object, like this: ```shell kubectl get serviceaccounts/build-robot -o yaml +``` +The output is similar to this: + +``` apiVersion: v1 kind: ServiceAccount metadata: @@ -150,7 +151,6 @@ metadata: kubernetes.io/service-account.name: build-robot type: kubernetes.io/service-account-token EOF -secret/build-robot-secret created ``` Now you can confirm that the newly built secret is populated with an API token for the "build-robot" service account. @@ -159,6 +159,10 @@ Any tokens for non-existent service accounts will be cleaned up by the token con ```shell kubectl describe secrets/build-robot-secret +``` +The output is similar to this: + +``` Name: build-robot-secret Namespace: default Labels: @@ -181,10 +185,15 @@ The content of `token` is elided here. ## Add ImagePullSecrets to a service account First, create an imagePullSecret, as described [here](/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod). -Next, verify it has been created. For example: +Next, verify it has been created. For example: ```shell kubectl get secrets myregistrykey +``` + +The output is similar to this: + +``` NAME TYPE DATA AGE myregistrykey   kubernetes.io/.dockerconfigjson   1       1d ``` @@ -195,12 +204,15 @@ Next, modify the default service account for the namespace to use this secret as kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "myregistrykey"}]}' ``` -Interactive version requiring manual edit: +Interactive version requires manual edit: ```shell kubectl get serviceaccounts default -o yaml > ./sa.yaml +``` + +The output of the `sa.yaml` file is similar to this: -cat sa.yaml +```shell apiVersion: v1 kind: ServiceAccount metadata: @@ -212,13 +224,13 @@ metadata: uid: 052fb0f4-3d50-11e5-b066-42010af0d7b6 secrets: - name: default-token-uudge +``` -vi sa.yaml -[editor session not shown] -[delete line with key "resourceVersion"] -[add lines with "imagePullSecrets:"] +Using your editor of choice (for example `vi`), open the `sa.yaml` file, delete line with key `resourceVersion`, add lines with `imagePullSecrets:` and save. -cat sa.yaml +The output of the `sa.yaml` file is similar to this: + +```shell apiVersion: v1 kind: ServiceAccount metadata: @@ -231,9 +243,12 @@ secrets: - name: default-token-uudge imagePullSecrets: - name: myregistrykey +``` + +Finally replace the serviceaccount with the new updated `sa.yaml` file +```shell kubectl replace serviceaccount default -f ./sa.yaml -serviceaccounts/default ``` Now, any new pods created in the current namespace will have this added to their spec: @@ -274,32 +289,17 @@ This behavior is configured on a PodSpec using a ProjectedVolume type called pod with a token with an audience of "vault" and a validity duration of two hours, you would configure the following in your PodSpec: -```yaml -kind: Pod -apiVersion: v1 -spec: - containers: - - image: nginx - name: nginx - volumeMounts: - - mountPath: /var/run/secrets/tokens - name: vault-token - volumes: - - name: vault-token - projected: - sources: - - serviceAccountToken: - path: vault-token - expirationSeconds: 7200 - audience: vault +{{< codenew file="pods/pod-projected-svc-token.yaml" >}} + +Create the Pod: + +```shell +kubectl create -f https://k8s.io/examples/pods/pod-projected-svc-token.yaml ``` The kubelet will request and store the token on behalf of the pod, make the -token available to the pod at a configurable file path, and refresh the token as -it approaches expiration. Kubelet proactively rotates the token if it is older -than 80% of its total TTL, or if the token is older than 24 hours. +token available to the pod at a configurable file path, and refresh the token as it approaches expiration. Kubelet proactively rotates the token if it is older than 80% of its total TTL, or if the token is older than 24 hours. -The application is responsible for reloading the token when it rotates. Periodic -reloading (e.g. once every 5 minutes) is sufficient for most usecases. +The application is responsible for reloading the token when it rotates. Periodic reloading (e.g. once every 5 minutes) is sufficient for most usecases. {{% /capture %}} diff --git a/content/en/examples/examples_test.go b/content/en/examples/examples_test.go index 4eb80eaedd09c..d3624e23f8f52 100644 --- a/content/en/examples/examples_test.go +++ b/content/en/examples/examples_test.go @@ -453,6 +453,7 @@ func TestExampleObjectSchemas(t *testing.T) { "pod-multiple-configmap-env-variable": {&api.Pod{}}, "pod-nginx-specific-node": {&api.Pod{}}, "pod-nginx": {&api.Pod{}}, + "pod-projected-svc-token": {&api.Pod{}}, "pod-rs": {&api.Pod{}, &api.Pod{}}, "pod-single-configmap-env-variable": {&api.Pod{}}, "pod-with-node-affinity": {&api.Pod{}}, diff --git a/content/en/examples/pods/pod-projected-svc-token.yaml b/content/en/examples/pods/pod-projected-svc-token.yaml new file mode 100644 index 0000000000000..72b4ac2b520d3 --- /dev/null +++ b/content/en/examples/pods/pod-projected-svc-token.yaml @@ -0,0 +1,19 @@ +kind: Pod +apiVersion: v1 +metadata: + name: nginx +spec: + containers: + - image: nginx + name: nginx + volumeMounts: + - mountPath: /var/run/secrets/tokens + name: vault-token + volumes: + - name: vault-token + projected: + sources: + - serviceAccountToken: + path: vault-token + expirationSeconds: 7200 + audience: vault