You are viewing documentation for Kubernetes version: v1.19
Kubernetes v1.19 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
Managing Service Accounts
This is a Cluster Administrator guide to service accounts. You should be familiar with configuring Kubernetes service accounts.
Support for authorization and user accounts is planned but incomplete. Sometimes incomplete features are referred to in order to better describe service accounts.
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 processes, which run in pods.
- User accounts are intended to be global. Names must be unique across all namespaces of a cluster. Service accounts are namespaced.
- Typically, a cluster's user accounts might be synced 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 accounts for components of that system. Because service accounts can be created without many constraints and have namespaced names, such config is portable.
Service account automation
Three separate components cooperate to implement the automation around service accounts:
- A Token controller
ServiceAccount Admission Controller
The modification of pods is implemented via a plugin called an Admission Controller. It is part of the API server. It acts synchronously to modify pods as they are created or updated. When this plugin is active (and it is by default on most distributions), then it does the following when a pod is created or modified:
- If the pod does not have a
serviceAccountNameset, it sets the
- It ensures that the
serviceAccountNamereferenced by the pod exists, and otherwise rejects it.
- If the pod does not contain any
imagePullSecretsof the ServiceAccount referenced by
serviceAccountNameare added to the pod.
- It adds a
volumeto the pod which contains a token for API access if neither the ServiceAccount
automountServiceAccountTokennor the Pod's
automountServiceAccountTokenis set to
- It adds a
volumeSourceto each container of the pod mounted at
/var/run/secrets/kubernetes.io/serviceaccount, if the previous step has created a volume for ServiceAccount token.
You can migrate a service account volume to a projected volume when
BoundServiceAccountTokenVolume feature gate is enabled.
The service account token will expire after 1 hour or the pod is deleted. See
more details about
TokenController runs as part of
kube-controller-manager. It acts asynchronously. It:
- watches ServiceAccount creation and creates a corresponding ServiceAccount token Secret to allow API access.
- watches ServiceAccount deletion and deletes all corresponding ServiceAccount token Secrets.
- watches ServiceAccount token Secret addition, and ensures the referenced ServiceAccount exists, and adds a token to the Secret if needed.
- watches 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
kube-controller-manager using the
flag. The private key is used to sign generated service account tokens.
Similarly, you must pass the corresponding public key to the
--service-account-key-file flag. The public key will be used to
verify the tokens during authentication.
To create additional API tokens
A controller loop ensures a Secret with an API token exists for each
ServiceAccount. To create additional API tokens for a ServiceAccount, create a
Secret of type
kubernetes.io/service-account-token with an annotation
referencing the ServiceAccount, and the controller will update it with a
Below is a sample configuration for such a Secret:
apiVersion: v1 kind: Secret metadata: name: mysecretname annotations: kubernetes.io/service-account.name: myserviceaccount type: kubernetes.io/service-account-token
kubectl create -f ./secret.yaml kubectl describe secret mysecretname
To delete/invalidate a ServiceAccount token Secret
kubectl delete secret mysecretname
A ServiceAccount controller manages the ServiceAccounts inside namespaces, and ensures a ServiceAccount named "default" exists in every active namespace.