Service Accounts

You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4]

You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4]

Overview

When a person uses the OKD 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.

User Names and Groups

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:

  1. system:serviceaccount:<project>:<name>

For example, to add the view role to the robot service account in the top-secret project:

  1. $ oc policy add-role-to-user view system:serviceaccount:top-secret:robot

If you want to grant access to a specific service account in a project, you can use the -z flag. From the project to which the service account belongs, use the -z flag and specify the <serviceaccount_name>. This is highly recommended, as it helps prevent typos and ensures that access is granted only to the specified service account. For example:

  1.  $ oc policy add-role-to-user <role_name> -z <serviceaccount_name>

If not in the project, use the -n option to indicate the project namespace it applies to, as shown in the examples below.

Every service account is also a member of two groups:

system:serviceaccount

Includes all service accounts in the system.

system:serviceaccount:<project>

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:

  1. $ oc policy add-role-to-group view system:serviceaccount -n top-secret

To allow all service accounts in the managers project to edit resources in the top-secret project:

  1. $ oc policy add-role-to-group edit system:serviceaccount:managers -n top-secret

Default Service Accounts and Roles

Three service accounts are automatically created in every project:

Service AccountUsage

builder

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.

deployer

Used by deployment pods and is given the system:deployer role, which allows viewing and modifying replication controllers and pods in the project.

default

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.

Managing Service Accounts

Service accounts are API objects that exist within each project. To manage service accounts, you can use the oc command with the sa or serviceaccount object type or use the web console.

To get a list of existing service accounts in the current project:

  1. $ oc get sa
  2. NAME       SECRETS   AGE
  3. builder    2         2d
  4. default    2         2d
  5. deployer   2         2d

To create a new service account:

  1. $ oc create sa robot
  2. serviceaccount "robot" created

As soon as a service account is created, two secrets are automatically added to it:

  • an API token

  • credentials for the OpenShift Container Registry

These can be seen by describing the service account:

  1. $ oc describe sa robot
  2. Name:        robot
  3. Namespace:    project1
  4. Labels:        <none>
  5. Annotations:    <none>
  7. Image pull secrets:    robot-dockercfg-qzbhb
  9. Mountable secrets:     robot-token-f4khf
  10.                        robot-dockercfg-qzbhb
  12. Tokens:                robot-token-f4khf
  13.                        robot-token-z8h44

The system ensures that service accounts always have an API token and registry credentials.

The generated API token and 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.

Managing Allowed Secrets

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:

  1. $ oc secrets link --for=pull <serviceaccount-name> <secret-name>

To allow a secret to be mounted by a service account’s pods, run:

  1. $ oc secrets link --for=mount <serviceaccount-name> <secret-name>

Limiting secrets to only the service accounts that reference them is disabled by default. This means that if serviceAccountConfig.limitSecretReferences is set to false (the default setting) in the master configuration file, mounting secrets to a service account’s pods with the —for=mount option is not required. However, using the —for=pull option to enable using an image pull secret is required, regardless of the serviceAccountConfig.limitSecretReferences value.

This example creates and adds secrets to a service account:

  1. $ oc create secret generic secret-plans \
  2.     --from-file=plan1.txt \
  3.     --from-file=plan2.txt
  4. secret/secret-plans
  6. $ oc create secret docker-registry my-pull-secret \
  7.     --docker-username=mastermind \
  8.     --docker-password=12345 \
  9.     --docker-email=mastermind@example.com
  10. secret/my-pull-secret
  12. $ oc secrets link robot secret-plans --for=mount
  14. $ oc secrets link robot my-pull-secret --for=pull
  16. $ oc describe serviceaccount robot
  17. Name:               robot
  18. Labels:             <none>
  19. Image pull secrets:    robot-dockercfg-624cx
  20.                        my-pull-secret
  22. Mountable secrets:     robot-token-uzkbh
  23.                        robot-dockercfg-624cx
  24.                        secret-plans
  26. Tokens:                robot-token-8bhpp
  27.                        robot-token-uzkbh

Using a Service Account’s Credentials Inside a Container

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:

  1. $ TOKEN="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)"
  3. $ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
  4.     "https://openshift.default.svc.cluster.local/oapi/v1/users/~" \
  5.     -H "Authorization: Bearer $TOKEN"
  7. kind: "User"
  8. apiVersion: "user.openshift.io/v1"
  9. metadata:
  10.   name: "system:serviceaccount:top-secret:robot"
  11.   selflink: "/oapi/v1/users/system:serviceaccount:top-secret:robot"
  12.   creationTimestamp: null
  13. identities: null
  14. groups:
  15.   - "system:serviceaccount"
  16.   - "system:serviceaccount:top-secret"

Using a Service Account’s Credentials Externally

The same token can be distributed to external applications that need to authenticate to the API.

Use the following syntax to view a service account’s API token:

  1. $ oc describe secret <secret-name>

For example:

  1. $ oc describe secret robot-token-uzkbh -n top-secret
  2. Name:        robot-token-uzkbh
  3. Labels:        <none>
  4. Annotations:    kubernetes.io/service-account.name=robot,kubernetes.io/service-account.uid=49f19e2e-16c6-11e5-afdc-3c970e4b7ffe
  6. Type:    kubernetes.io/service-account-token
  8. Data
  10. token:    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  12. $ oc login --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  13. Logged into "https://server:8443" as "system:serviceaccount:top-secret:robot" using the token provided.
  15. You don't have any projects. You can try to create a new project, by running
  17.     $ oc new-project <projectname>
  19. $ oc whoami
  20. system:serviceaccount:top-secret:robot