392 lines
16 KiB
Markdown
392 lines
16 KiB
Markdown
---
|
|
reviewers:
|
|
- bprashanth
|
|
- davidopp
|
|
- lavalamp
|
|
- liggitt
|
|
title: Managing Service Accounts
|
|
content_type: concept
|
|
weight: 50
|
|
---
|
|
|
|
<!-- overview -->
|
|
|
|
A _ServiceAccount_ provides an identity for processes that run in a Pod.
|
|
|
|
A process inside a Pod can use the identity of its associated service account to
|
|
authenticate to the cluster's API server.
|
|
|
|
For an introduction to service accounts, read [configure service accounts](/docs/tasks/configure-pod-container/configure-service-account/).
|
|
|
|
This task guide explains some of the concepts behind ServiceAccounts. The
|
|
guide also explains how to obtain or revoke tokens that represent
|
|
ServiceAccounts.
|
|
|
|
<!-- body -->
|
|
|
|
## {{% heading "prerequisites" %}}
|
|
|
|
{{< include "task-tutorial-prereqs.md" >}}
|
|
|
|
To be able to follow these steps exactly, ensure you have a namespace named
|
|
`examplens`.
|
|
If you don't, create one by running:
|
|
|
|
```shell
|
|
kubectl create namespace examplens
|
|
```
|
|
|
|
## User accounts versus service accounts
|
|
|
|
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 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. 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 configuration is
|
|
usually portable.
|
|
|
|
## 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-<random-suffix>
|
|
projected:
|
|
sources:
|
|
- serviceAccountToken:
|
|
path: token # must match the path the app expects
|
|
- 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/).
|
|
It is part of the API server.
|
|
This admission controller acts synchronously to modify pods as they are created.
|
|
When this plugin is active (and it is by default on most distributions), then
|
|
it does the following when a Pod is created:
|
|
|
|
1. If the pod does not have a `.spec.serviceAccountName` set, the admission controller sets the name of the
|
|
ServiceAccount for this incoming Pod to `default`.
|
|
1. The admission controller ensures that the ServiceAccount referenced by the incoming Pod exists. If there
|
|
is no ServiceAccount with a matching name, the admission controller rejects the incoming Pod. That check
|
|
applies even for the `default` ServiceAccount.
|
|
1. Provided that neither the ServiceAccount's `automountServiceAccountToken` field nor the
|
|
Pod's `automountServiceAccountToken` field is set to `false`:
|
|
- the admission controller mutates the incoming Pod, adding an extra
|
|
{{< glossary_tooltip text="volume" term_id="volume" >}} that contains
|
|
a token for API access.
|
|
- the admission controller adds a `volumeMount` to each container in the Pod,
|
|
skipping any containers that already have a volume mount defined for the path
|
|
`/var/run/secrets/kubernetes.io/serviceaccount`.
|
|
For Linux containers, that volume is mounted at `/var/run/secrets/kubernetes.io/serviceaccount`;
|
|
on Windows nodes, the mount is at the equivalent path.
|
|
1. If the spec of the incoming Pod does already contain any `imagePullSecrets`, then the
|
|
admission controller adds `imagePullSecrets`, copying them from the `ServiceAccount`.
|
|
|
|
### 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.
|
|
You don't need to call this to obtain an API token for use within a container, since
|
|
the kubelet sets this up for you using a _projected volume_.
|
|
|
|
If you want to use the TokenRequest API from `kubectl`, see
|
|
[Manually create an API token for a ServiceAccount](/docs/tasks/configure-pod-container/configure-service-account/#manually-create-an-api-token-for-a-serviceaccount).
|
|
|
|
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.
|
|
|
|
(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.)
|
|
|
|
Here's an example of how that looks for a launched Pod:
|
|
|
|
```yaml
|
|
...
|
|
- name: kube-api-access-<random-suffix>
|
|
projected:
|
|
defaultMode: 420 # decimal equivalent of octal 0644
|
|
sources:
|
|
- serviceAccountToken:
|
|
expirationSeconds: 3607
|
|
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 combines information from three sources:
|
|
|
|
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.
|
|
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. This `downwardAPI` volume makes the name of the namespace container the Pod available
|
|
to application code running inside the Pod.
|
|
|
|
Any container within the Pod that mounts this volume can access the above information.
|
|
|
|
## Create additional API tokens {#create-token}
|
|
|
|
{{< caution >}}
|
|
Only create long-lived API tokens if the [token request](#tokenrequest-api) mechanism
|
|
is not suitable. The token request mechanism provides time-limited tokens; because these
|
|
expire, they represent a lower risk to information security.
|
|
{{< /caution >}}
|
|
|
|
To create a non-expiring, persisted API token for a ServiceAccount, create a
|
|
Secret of type `kubernetes.io/service-account-token` with an annotation
|
|
referencing the ServiceAccount. The control plane then generates a long-lived token and
|
|
updates that Secret with that generated token data.
|
|
|
|
Here is a sample manifest for such a Secret:
|
|
|
|
{{< codenew file="secret/serviceaccount/mysecretname.yaml" >}}
|
|
|
|
To create a Secret based on this example, run:
|
|
```shell
|
|
kubectl -n examplens create -f https://k8s.io/examples/secret/serviceaccount/mysecretname.yaml
|
|
```
|
|
|
|
To see the details for that Secret, run:
|
|
|
|
```shell
|
|
kubectl -n examplens describe secret mysecretname
|
|
```
|
|
|
|
The output is similar to:
|
|
```
|
|
Name: mysecretname
|
|
Namespace: examplens
|
|
Labels: <none>
|
|
Annotations: kubernetes.io/service-account.name=myserviceaccount
|
|
kubernetes.io/service-account.uid=8a85c4c4-8483-11e9-bc42-526af7764f64
|
|
|
|
Type: kubernetes.io/service-account-token
|
|
|
|
Data
|
|
====
|
|
ca.crt: 1362 bytes
|
|
namespace: 9 bytes
|
|
token: ...
|
|
```
|
|
|
|
If you launch a new Pod into the `examplens` namespace, it can use the `myserviceaccount`
|
|
service-account-token Secret that you just created.
|
|
|
|
## Delete/invalidate a ServiceAccount token {#delete-token}
|
|
|
|
If you know the name of the Secret that contains the token you want to remove:
|
|
|
|
```shell
|
|
kubectl delete secret name-of-secret
|
|
```
|
|
|
|
Otherwise, first find the Secret for the ServiceAccount.
|
|
|
|
```shell
|
|
# This assumes that you already have a namespace named 'examplens'
|
|
kubectl -n examplens get serviceaccount/example-automated-thing -o yaml
|
|
```
|
|
The output is similar to:
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: ServiceAccount
|
|
metadata:
|
|
annotations:
|
|
kubectl.kubernetes.io/last-applied-configuration: |
|
|
{"apiVersion":"v1","kind":"ServiceAccount","metadata":{"annotations":{},"name":"example-automated-thing","namespace":"examplens"}}
|
|
creationTimestamp: "2019-07-21T07:07:07Z"
|
|
name: example-automated-thing
|
|
namespace: examplens
|
|
resourceVersion: "777"
|
|
selfLink: /api/v1/namespaces/examplens/serviceaccounts/example-automated-thing
|
|
uid: f23fd170-66f2-4697-b049-e1e266b7f835
|
|
secrets:
|
|
- name: example-automated-thing-token-zyxwv
|
|
```
|
|
Then, delete the Secret you now know the name of:
|
|
```shell
|
|
kubectl -n examplens delete secret/example-automated-thing-token-zyxwv
|
|
```
|
|
|
|
The control plane spots that the ServiceAccount is missing its Secret,
|
|
and creates a replacement:
|
|
|
|
```shell
|
|
kubectl -n examplens get serviceaccount/example-automated-thing -o yaml
|
|
```
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: ServiceAccount
|
|
metadata:
|
|
annotations:
|
|
kubectl.kubernetes.io/last-applied-configuration: |
|
|
{"apiVersion":"v1","kind":"ServiceAccount","metadata":{"annotations":{},"name":"example-automated-thing","namespace":"examplens"}}
|
|
creationTimestamp: "2019-07-21T07:07:07Z"
|
|
name: example-automated-thing
|
|
namespace: examplens
|
|
resourceVersion: "1026"
|
|
selfLink: /api/v1/namespaces/examplens/serviceaccounts/example-automated-thing
|
|
uid: f23fd170-66f2-4697-b049-e1e266b7f835
|
|
secrets:
|
|
- name: example-automated-thing-token-4rdrh
|
|
```
|
|
|
|
## Clean up
|
|
|
|
If you created a namespace `examplens` to experiment with, you can remove it:
|
|
```shell
|
|
kubectl delete namespace examplens
|
|
```
|
|
|
|
## Control plane details
|
|
|
|
### ServiceAccount controller
|
|
|
|
A ServiceAccount controller manages the ServiceAccounts inside namespaces, and
|
|
ensures a ServiceAccount named "default" exists in every active namespace.
|
|
|
|
### Token controller
|
|
|
|
The service account token controller runs as part of `kube-controller-manager`.
|
|
This controller acts asynchronously. It:
|
|
|
|
- watches for ServiceAccount creation and creates a corresponding
|
|
ServiceAccount token Secret to allow API access.
|
|
- 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.
|
|
|
|
## {{% heading "whatsnext" %}}
|
|
|
|
- Read more details about [projected volumes](/docs/concepts/storage/projected-volumes/).
|