When a person uses the OpenShift Enterprise CLI or web console, their API token authenticates them to the OpenShift API. However, when a regular user’s credentials are not available, it is common for components to make API calls independently. For example:
Replication controllers make API calls to create or delete pods.
Applications inside containers could make API calls for discovery purposes.
External applications could make API calls for monitoring or integration purposes.
Service accounts provide a flexible way to control API access without sharing a regular user’s credentials.
Every service account has an associated user name that can be granted roles, just like a regular user. The user name is derived from its project and name:
For example, to add the view role to the robot service account in the top-secret project:
$ oc policy add-role-to-user view system:serviceaccount:top-secret:robot
Every service account is also a member of two groups:
Includes all service accounts in the system.
Includes all service accounts in the specified project.
For example, to allow all service accounts in all projects to view resources in the top-secret project:
$ oc policy add-role-to-group view system:serviceaccounts -n top-secret
To allow all service accounts in the managers project to edit resources in the top-secret project:
$ oc policy add-role-to-group edit system:serviceaccounts:managers -n top-secret
Three service accounts are automatically created in every project:
Used by build pods. It is given the system:image-builder role, which allows pushing images to any image stream in the project using the internal Docker registry.
Used by deployment pods and is given the system:deployer role, which allows viewing and modifying replication controllers and pods in the project.
Used to run all other pods unless they specify a different service account.
All service accounts in a project are given the system:image-puller role, which allows pulling images from any image stream in the project using the internal Docker registry.
Service accounts are API objects that exist within each project. They can be created or deleted like any other API object.
$ oc create serviceaccount robot serviceaccounts/robot
As soon as a service account is created, two secrets are automatically added to it:
an API token
credentials for the internal Docker registry
These can be seen by describing the service account:
$ oc describe serviceaccount robot Name: robot Labels: <none> Image pull secrets: robot-dockercfg-624cx Mountable secrets: robot-token-uzkbh robot-dockercfg-624cx Tokens: robot-token-8bhpp robot-token-uzkbh
The system ensures that service accounts always have an API token and internal Docker registry credentials.
The generated API token and Docker registry credentials do not expire, but they can be revoked by deleting the secret. When the secret is deleted, a new one is automatically generated to take its place.
In addition to providing API credentials, a pod’s service account determines which secrets the pod is allowed to use.
Pods use secrets in two ways:
image pull secrets, providing credentials used to pull images for the pod’s containers
mountable secrets, injecting the contents of secrets into containers as files
To allow a secret to be used as an image pull secret by a service account’s pods, run:
$ oc secrets add --for=pull \ serviceaccount/<serviceaccount-name> \ secret/<secret-name>
To allow a secret to be mounted by a service account’s pods, run:
$ oc secrets add --for=mount \ serviceaccount/<serviceaccount-name> \ secret/<secret-name>
This example creates and adds secrets to a service account:
$ oc secrets new secret-plans plan1.txt plan2.txt secret/secret-plans $ oc secrets new-dockercfg my-pull-secret \ --docker-username=mastermind \ --docker-password=12345 \ --firstname.lastname@example.org secret/my-pull-secret $ oc secrets add serviceaccount/robot secret/secret-plans --for=mount $ oc secrets add serviceaccount/robot secret/my-pull-secret --for=pull $ oc describe serviceaccount robot Name: robot Labels: <none> Image pull secrets: robot-dockercfg-624cx my-pull-secret Mountable secrets: robot-token-uzkbh robot-dockercfg-624cx secret-plans Tokens: robot-token-8bhpp robot-token-uzkbh
When a pod is created, it specifies a service account (or uses the default service account), and is allowed to use that service account’s API credentials and referenced secrets.
A file containing an API token for a pod’s service account is automatically mounted at /var/run/secrets/kubernetes.io/serviceaccount/token.
That token can be used to make API calls as the pod’s service account. This example calls the users/~ API to get information about the user identified by the token:
$ TOKEN="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" $ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \ "https://openshift.default.svc.cluster.local/oapi/v1/users/~" \ -H "Authorization: Bearer $TOKEN" kind: "User" apiVersion: "v1" metadata: name: "system:serviceaccount:top-secret:robot" selflink: "/oapi/v1/users/system:serviceaccount:top-secret:robot" creationTimestamp: null identities: null groups: - "system:serviceaccounts" - "system:serviceaccounts:top-secret"
The same token can be distributed to external applications that need to authenticate to the API.
Use the following syntax to to view a service account’s API token:
$ oc describe secret <secret-name>
$ oc describe secret robot-token-uzkbh -n top-secret Name: robot-token-uzkbh Labels: <none> Annotations: kubernetes.io/service-account.name=robot,kubernetes.io/service-account.uid=49f19e2e-16c6-11e5-afdc-3c970e4b7ffe Type: kubernetes.io/service-account-token Data token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... $ oc login --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... Logged into "https://server:8443" as "system:serviceaccount:top-secret:robot" using the token provided. You don't have any projects. You can try to create a new project, by running $ oc new-project <projectname> $ oc whoami system:serviceaccount:top-secret:robot