From f87e5058c9ffc9b112552fe8787646ffc64dd978 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Fri, 13 May 2022 19:19:26 +0100 Subject: [PATCH] Update ServiceAccount tasks in light of TokenRequest Now that TokenRequest is the default way to get a service account token for a Pod, update the task pages that relate to this. --- .../service-accounts-admin.md | 149 ++++++++++++++++-- .../configure-service-account.md | 37 ++++- 2 files changed, 167 insertions(+), 19 deletions(-) diff --git a/content/en/docs/reference/access-authn-authz/service-accounts-admin.md b/content/en/docs/reference/access-authn-authz/service-accounts-admin.md index 7007aa5a6aff6..9998cd532d108 100644 --- a/content/en/docs/reference/access-authn-authz/service-accounts-admin.md +++ b/content/en/docs/reference/access-authn-authz/service-accounts-admin.md @@ -40,21 +40,129 @@ kubectl create namespace examplens Kubernetes distinguishes between the concept of a user account and a service account for a number of reasons: -- User accounts are for humans. Service accounts are for processes, which run - in pods. -- User accounts are intended to be global. Names must be unique across all - namespaces of a cluster. In Kubernetes, service accounts are namespaced. -- Typically, a cluster's user accounts might be synced from a corporate +- User accounts are for humans. Service accounts are for application processes, + which (for Kubernetes) run in containers that are part of pods. +- User accounts are intended to be global: names must be unique across all + namespaces of a cluster. No matter what namespace you look at, a particular + username that represents a user represents the same user. + In Kubernetes, service accounts are namespaced: two different namespaces can + contain ServiceAccounts that have identical names. +- Typically, a cluster's user accounts might be synchronised from a corporate database, where new user account creation requires special privileges and is - tied to complex business processes. Service account creation is intended to be - more lightweight, allowing cluster users to create service accounts for - specific tasks by following the principle of least privilege. -- Auditing considerations for humans and service accounts may differ. -- A config bundle for a complex system may include definition of various service + tied to complex business processes. By contrast, service account creation is + intended to be more lightweight, allowing cluster users to create service accounts + for specific tasks on demand. Separating ServiceAccount creation from the steps to + onboard human users makes it easier for workloads to following the principle of + least privilege. +- Auditing considerations for humans and service accounts may differ; the separation + makes that easier to achieve. +- A configuration bundle for a complex system may include definition of various service accounts for components of that system. Because service accounts can be created - without many constraints and have namespaced names, such config is portable. + without many constraints and have namespaced names, such configuration is + usually portable. -## ServiceAccount admission controller +## Bound service account token volume mechanism {#bound-service-account-token-volume} + +{{< feature-state for_k8s_version="v1.22" state="stable" >}} + +By default, the Kubernetes control plane (specifically, the +[ServiceAccount admission controller](#service-account-admission-controller)) +adds a [projected volume](/docs/concepts/storage/projected-volumes/) to Pods, +and this volume includes a token for Kubernetes API access. + +Here's an example of how that looks for a launched Pod: + +```yaml +... + - name: kube-api-access- + projected: + defaultMode: 420 # decimal equivalent of octal 0644 + sources: + - serviceAccountToken: + expirationSeconds: 7200 + audience: api + path: token + - configMap: + items: + - key: ca.crt + path: ca.crt + name: kube-root-ca.crt + - downwardAPI: + items: + - fieldRef: + apiVersion: v1 + fieldPath: metadata.namespace + path: namespace +``` + +That manifest snippet defines a projected volume that consists of three sources. In this case, +each source also represents a single path within that volume. The three sources are: + +1. A `serviceAccountToken` source, that contains a token that the kubelet acquires from kube-apiserver + The kubelet fetches time-bound tokens using the TokenRequest API. A token served for a TokenRequest expires + either when the pod is deleted or after a defined lifespan (by default, that is 1 hour). + The token is bound to the specific Pod and has the kube-apiserver as its audience. + This mechanism superseded an earlier mechanism that added a volume based on a Secret, + where the Secret represented the ServiceAccount for the Pod, but did not expire. +1. A `configMap` source. The ConfigMap contains a bundle of certificate authority data. Pods can use these + certificates to make sure that they are connecting to your cluster's kube-apiserver (and not to middlebox + or an accidentally misconfigured peer). +1. A `downwardAPI` source that looks up the name of thhe namespace containing the Pod, and makes + that name information available to application code running inside the Pod. + +Any container within the Pod that mounts this particular volume can access the above information. + +{{< note >}} +There is no specific mechanism to invalidate a token issued via TokenRequest. If you no longer +trust a bound service account token for a Pod, you can delete that Pod. Deleting a Pod expires +its bound service account tokens. +{{< /note >}} + +## Manual Secret management for ServiceAccounts + +Versions of Kubernetes before v1.22 automatically created credentials for accessing +the Kubernetes API. This older mechanism was based on creating token Secrets that +could then be mounted into running Pods. + +In more recent versions, including Kubernetes v{{< skew currentVersion >}}, API credentials +are [obtained directly](#bound-service-account-token-volume) using the +[TokenRequest](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) API, +and are mounted into Pods using a projected volume. +The tokens obtained using this method have bounded lifetimes, and are automatically +invalidated when the Pod they are mounted into is deleted. + +You can still [manually create](/docs/tasks/configure-pod-container/configure-service-account/#manually-create-an-api-token-for-a-serviceaccount) a Secret to hold a service account token; for example, if you need a token that never expires. + +Once you manually create a Secret and link it to a ServiceAccount, the Kubernetes control plane automatically populates the token into that Secret. + +{{< note >}} +Although the manual mechanism for creating a long-lived ServiceAccount token exists, +using [TokenRequest](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) +to obtain short-lived API access tokens is recommended instead. +{{< /note >}} + +## Control plane details + +### Token controller + +The service account token controller runs as part of `kube-controller-manager`. +This controller acts asynchronously. It: + +- watches for ServiceAccount deletion and deletes all corresponding ServiceAccount + token Secrets. +- watches for ServiceAccount token Secret addition, and ensures the referenced + ServiceAccount exists, and adds a token to the Secret if needed. +- watches for Secret deletion and removes a reference from the corresponding + ServiceAccount if needed. + +You must pass a service account private key file to the token controller in +the `kube-controller-manager` using the `--service-account-private-key-file` +flag. The private key is used to sign generated service account tokens. +Similarly, you must pass the corresponding public key to the `kube-apiserver` +using the `--service-account-key-file` flag. The public key will be used to +verify the tokens during authentication. + +### ServiceAccount admission controller The modification of pods is implemented via a plugin called an [Admission Controller](/docs/reference/access-authn-authz/admission-controllers/). @@ -78,10 +186,14 @@ it does the following when a Pod is created or modified: 1. If the spec of the incoming Pod does already contain any `imagePullSecrets`, then the admission controller adds `imagePullSecrets`, copying them from the `ServiceAccount`. -### Bound service account token volume mechanism {#bound-service-account-token-volume} +### TokenRequest API {{< feature-state for_k8s_version="v1.22" state="stable" >}} +You use the [TokenRequest](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) +subresource of a ServiceAccount to obtain a time-bound token for that ServiceAccount. Usually you don't +need to call this API: the kubelet sets this up for you using a _projected volume_. + The Kubernetes control plane (specifically, the ServiceAccount admission controller) adds a projected volume to Pods, and the kubelet ensures that this volume contains a token that lets containers authenticate as the right ServiceAccount. @@ -131,11 +243,10 @@ See more details about [projected volumes](/docs/tasks/configure-pod-container/c ## Create additional API tokens {#create-token} -The control plane ensures that a Secret with an API token exists for each -ServiceAccount. To create additional API tokens for a ServiceAccount, create a +To create the first, or subsequent, long lived API token for a ServiceAccount, create a Secret of type `kubernetes.io/service-account-token` with an annotation -referencing the ServiceAccount, and the control plane will update that Secret with a -generated token. +referencing the ServiceAccount. The control plane then generates a long-lived token and +updates that Secret with that token data. Here is a sample manifest for such a Secret: @@ -268,3 +379,7 @@ flag. The private key is used to sign generated service account tokens. Similarly, you must pass the corresponding public key to the `kube-apiserver` using the `--service-account-key-file` flag. The public key will be used to verify the tokens during authentication. + +## {{% heading "whatsnext" %}} + +- Read more details about [projected volumes](/docs/concepts/storage/projected-volumes/). 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 b74a712a8ecc9..047146e595310 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 @@ -164,8 +164,38 @@ kubectl delete serviceaccount/build-robot ## Manually create an API token for a ServiceAccount +Suppose you have an existing service account named "build-robot" as mentioned earlier. + +You can get a time-limited API token for that ServiceAccount using `kubectl`: + +```shell +kubectl create token admin-user +``` + +The output from that command is a token that you can use to authenticate as that +ServiceAccount. You can request a specific token duration using the `--duration` +command line argument to `kubectl create token` (the actual duration of the issued +token might be shorter, or could even be longer). + +{{< note >}} +Versions of Kubernetes before v1.22 automatically created credentials for accessing +the Kubernetes API. This older mechanism was based on creating token Secrets that +could then be mounted into running Pods. +In more recent versions, including Kubernetes v{{< skew currentVersion >}}, API credentials +are obtained directly by using the [TokenRequest](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) API, +and are mounted into Pods using a [projected volume](/docs/reference/access-authn-authz/service-accounts-admin/#bound-service-account-token-volume). +The tokens obtained using this method have bounded lifetimes, and are automatically +invalidated when the Pod they are mounted into is deleted. + +You can still manually create a service account token Secret; for example, if you need a token that never expires. +However, using the [TokenRequest](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) +subresource to obtain a token to access the API is recommended instead. +{{< /note >}} + +### Manually create a long-lived API token for a ServiceAccount + If you want to obtain an API token for a ServiceAccount, you create a new Secret -with a special annotation, `kubernetes.io/service-account.name` +with a special annotation, `kubernetes.io/service-account.name`. ```shell kubectl apply -f - <}} -By design, `kubectl describe` hides the value of the token. +By design, `kubectl describe` hides the confidential data in a Secret. {{< /note >}} +When you delete a ServiceAccount that has an associated Secret, the Kubernetes +control plane automatically cleans up the long-lived token from that Secret. + ## Add ImagePullSecrets to a service account First, [create an imagePullSecret](/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod).