Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Using service accounts in applications

Service accounts overview

A service account is an OKD account that allows a component to directly access the API. Service accounts are API objects that exist within each project. Service accounts provide a flexible way to control API access without sharing a regular user’s credentials.

When you use the OKD CLI or web console, your API token authenticates you to the API. You can associate a component with a service account so that they can access the API without using a regular user’s credentials. For example, service accounts can allow:

  • Replication controllers to make API calls to create or delete pods.

  • Applications inside containers to make API calls for discovery purposes.

  • External applications to make API calls for monitoring or integration purposes.

Each service account’s user name is derived from its project and name:

system:serviceaccount:<project>:<name>

Every service account is also a member of two groups:

Group Description

system:serviceaccounts

Includes all service accounts in the system.

system:serviceaccounts:<project>

Includes all service accounts in the specified project.

Each service account automatically contains two secrets:

  • An API token

  • Credentials for the OpenShift Container Registry

The generated API token and registry credentials do not expire, but you can revoke them by deleting the secret. When you delete the secret, a new one is automatically generated to take its place.

Default service accounts

Your OKD cluster contains default service accounts for cluster management and generates more service accounts for each project.

Default cluster service accounts

Several infrastructure controllers run using service account credentials. The following service accounts are created in the OKD infrastructure project (openshift-infra) at server start, and given the following roles cluster-wide:

Service Account Description

replication-controller

Assigned the system:replication-controller role

deployment-controller

Assigned the system:deployment-controller role

build-controller

Assigned the system:build-controller role. Additionally, the build-controller service account is included in the privileged security context constraint to create privileged build pods.

Default project service accounts and roles

Three service accounts are automatically created in each project:

Service Account Usage

builder

Used by build pods. It is given the system:image-builder role, which allows pushing images to any imagestream in the project using the internal Docker registry.

deployer

Used by deployment pods and 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 imagestream in the project using the internal container image registry.

About automatically generated service account token secrets

When a service account is created, a service account token secret is automatically generated for it. This service account token secret, along with an automatically generated docker configuration secret, is used to authenticate to the internal OKD registry. Do not rely on these automatically generated secrets for your own use; they might be removed in a future OKD release.

Prior to OKD 4.11, a second service account token secret was generated when a service account was created. This service account token secret was used to access the Kubernetes API.

Starting with OKD 4.11, this second service account token secret is no longer created. This is because the LegacyServiceAccountTokenNoAutoGeneration upstream Kubernetes feature gate was enabled, which stops the automatic generation of secret-based service account tokens to access the Kubernetes API.

After upgrading to 4.14, any existing service account token secrets are not deleted and continue to function.

Workloads are automatically injected with a projected volume to obtain a bound service account token. If your workload needs an additional service account token, add an additional projected volume in your workload manifest. Bound service account tokens are more secure than service account token secrets for the following reasons:

  • Bound service account tokens have a bounded lifetime.

  • Bound service account tokens contain audiences.

  • Bound service account tokens can be bound to pods or secrets and the bound tokens are invalidated when the bound object is removed.

For more information, see Configuring bound service account tokens using volume projection.

You can also manually create a service account token secret to obtain a token, if the security exposure of a non-expiring token in a readable API object is acceptable to you. For more information, see Creating a service account token secret.

Additional resources

Creating service accounts

You can create a service account in a project and grant it permissions by binding it to a role.

Procedure

  1. Optional: To view the service accounts in the current project:

    $ oc get sa
    Example output
    NAME       SECRETS   AGE
builder    2         2d
default    2         2d
deployer   2         2d

  2. To create a new service account in the current project:

    $ oc create sa <service_account_name> (1)
    1 To create a service account in a different project, specify -n <project_name>.
    Example output
    serviceaccount "robot" created

    You can alternatively apply the following YAML to create the service account:

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: <service_account_name>
  namespace: <current_project>

  3. Optional: View the secrets for the service account:

    $ oc describe sa robot
    Example output
    Name:                robot
Namespace:           project1
Labels:	             <none>
Annotations:	     <none>
Image pull secrets:  robot-dockercfg-qzbhb
Mountable secrets:   robot-dockercfg-qzbhb
Tokens:              robot-token-f4khf
Events:              <none>