kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve ServiceAccount administration doc 

This PR fixes some nits in the doc and slightly revised the content to
conform to content guidelines.
pull/23842/head
Qiming Teng 2020-09-13 11:25:40 +08:00
parent 1996d94faa
commit 2ff3d1f7d3
1 changed files with 69 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
content/en/docs/reference/access-authn-authz/service-accounts-admin.md
View File

@ -23,96 +23,108 @@ incomplete features are referred to in order to better describe service accounts
Kubernetes distinguishes between the concept of a user account and a service account Kubernetes distinguishes between the concept of a user account and a service account
for a number of reasons: for a number of reasons:
- User accounts are for humans. Service accounts are for processes, which - User accounts are for humans. Service accounts are for processes, which run
run in pods. in pods.
- User accounts are intended to be global. Names must be unique across all - User accounts are intended to be global. Names must be unique across all
namespaces of a cluster, future user resource will not be namespaced. namespaces of a cluster. Service accounts are namespaced.
Service accounts are namespaced. - Typically, a cluster's user accounts might be synced from a corporate
- Typically, a cluster's User accounts might be synced from a corporate database, where new user account creation requires special privileges and is
database, where new user account creation requires special privileges and tied to complex business processes. Service account creation is intended to be
is tied to complex business processes. Service account creation is intended more lightweight, allowing cluster users to create service accounts for
to be more lightweight, allowing cluster users to create service accounts for specific tasks by following the principle of least privilege.
specific tasks (i.e. principle of least privilege). - Auditing considerations for humans and service accounts may differ.
- Auditing considerations for humans and service accounts may differ. - A config bundle for a complex system may include definition of various service
- 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
accounts for components of that system. Because service accounts can be created without many constraints and have namespaced names, such config is portable.
ad-hoc and have namespaced names, such config is portable.
## Service account automation ## Service account automation
Three separate components cooperate to implement the automation around service accounts: Three separate components cooperate to implement the automation around service accounts:
- A Service account admission controller - A `ServiceAccount` admission controller
- A Token controller - A Token controller
- A Service account controller - A `ServiceAccount` controller
### Service Account Admission Controller ### ServiceAccount Admission Controller
The modification of pods is implemented via a plugin 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 apiserver. called an [Admission Controller](/docs/reference/access-authn-authz/admission-controllers/).
It is part of the API server.
It acts synchronously to modify pods as they are created or updated. When this plugin is active 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: (and it is by default on most distributions), then it does the following when a pod is created or modified:
1. If the pod does not have a `ServiceAccount` set, it sets the `ServiceAccount` to `default`. 1. If the pod does not have a `serviceAccountName` set, it sets the
1. It ensures that the `ServiceAccount` referenced by the pod exists, and otherwise rejects it. `serviceAccountName` to `default`.
1. If the pod does not contain any `ImagePullSecrets`, then `ImagePullSecrets` of the `ServiceAccount` are added to the pod. 1. It ensures that the `serviceAccountName` referenced by the pod exists, and
1. It adds a `volume` to the pod which contains a token for API access. otherwise rejects it.
1. It adds a `volumeSource` to each container of the pod mounted at `/var/run/secrets/kubernetes.io/serviceaccount`. 1. If the pod does not contain any `imagePullSecrets`, then `imagePullSecrets`
of the ServiceAccount referenced by `serviceAccountName` are added to the pod.
1. It adds a `volume` to the pod which contains a token for API access
if neither the ServiceAccount `automountServiceAccountToken` nor the Pod's
`automountServiceAccountToken` is set to `false`.
1. It adds a `volumeSource` to each container of the pod mounted at
`/var/run/secrets/kubernetes.io/serviceaccount`, if the previous step has
created a volume for ServiceAccount token.
Starting from v1.13, you can migrate a service account volume to a projected volume when You can migrate a service account volume to a projected volume when
the `BoundServiceAccountTokenVolume` feature gate is enabled. the `BoundServiceAccountTokenVolume` feature gate is enabled.
The service account token will expire after 1 hour or the pod is deleted. See more details about [projected volume](/docs/tasks/configure-pod-container/configure-projected-volume-storage/). The service account token will expire after 1 hour or the pod is deleted. See
more details about
[projected volume](/docs/tasks/configure-pod-container/configure-projected-volume-storage/).
### Token Controller ### Token Controller
TokenController runs as part of controller-manager. It acts asynchronously. It: TokenController runs as part of `kube-controller-manager`. It acts asynchronously. It:
- observes serviceAccount creation and creates a corresponding Secret to allow API access. - watches ServiceAccount creation and creates a corresponding
- observes serviceAccount deletion and deletes all corresponding ServiceAccountToken Secrets. ServiceAccount token Secret to allow API access.
- observes secret addition, and ensures the referenced ServiceAccount exists, and adds a token to the secret if needed. - watches ServiceAccount deletion and deletes all corresponding ServiceAccount
- observes secret deletion and removes a reference from the corresponding ServiceAccount if needed. 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 the controller-manager by using You must pass a service account private key file to the token controller in
the `--service-account-private-key-file` option. The private key will be used to sign generated service account tokens. the `kube-controller-manager` using the `--service-account-private-key-file`
Similarly, you must pass the corresponding public key to the kube-apiserver using the `--service-account-key-file` flag. The private key is used to sign generated service account tokens.
option. The public key will be used to verify the tokens during authentication. 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.
#### To create additional API tokens #### To create additional API tokens
A controller loop ensures a secret with an API token exists for each service A controller loop ensures a Secret with an API token exists for each
account. To create additional API tokens for a service account, create a secret ServiceAccount. To create additional API tokens for a ServiceAccount, create a
of type `ServiceAccountToken` with an annotation referencing the service Secret of type `kubernetes.io/service-account-token` with an annotation
account, and the controller will update it with a generated token: referencing the ServiceAccount, and the controller will update it with a
generated token:
secret.json: Below is a sample configuration for such a Secret:
```json ```yaml
{ apiVersion: v1
"kind": "Secret", kind: Secret
"apiVersion": "v1", metadata:
"metadata": { name: mysecretname
"name": "mysecretname", annotations:
"annotations": { kubernetes.io/service-account.name: myserviceaccount
"kubernetes.io/service-account.name": "myserviceaccount" type: kubernetes.io/service-account-token
}
},
"type": "kubernetes.io/service-account-token"
}
``` ```
```shell ```shell
kubectl create -f ./secret.json kubectl create -f ./secret.yaml
kubectl describe secret mysecretname kubectl describe secret mysecretname
``` ```
#### To delete/invalidate a service account token #### To delete/invalidate a ServiceAccount token Secret
```shell ```shell
kubectl delete secret mysecretname kubectl delete secret mysecretname
``` ```
### Service Account Controller ### ServiceAccount controller
Service Account Controller manages ServiceAccount inside namespaces, and ensures A ServiceAccount controller manages the ServiceAccounts inside namespaces, and
a ServiceAccount named "default" exists in every active namespace. ensures a ServiceAccount named "default" exists in every active namespace.