OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Service Accounts

Overview

When a person uses the command line 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 can make API calls for discovery purposes

  • External applications can 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.

Usernames and groups

Every service account has an associated username that can be granted roles, just like a regular user. The username is derived from its project and name: system:serviceaccount:<project>:<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:

  • system:serviceaccounts, which includes all service accounts in the system

  • system:serviceaccounts:<project>, which 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

Enable service account authentication

Service accounts authenticate to the API using tokens signed by a private RSA key. The authentication layer verifies the signature using a matching public RSA key.

To enable service account token generation, update the master configuration serviceAccountConfig stanza to specify a privateKeyFile (for signing), and a matching public key file in the publicKeyFiles list:

serviceAccountConfig:
  ...
  masterCA: ca.crt (1)
  privateKeyFile: serviceaccounts.private.key (2)
  publicKeyFiles:
  - serviceaccounts.public.key (3)
  - ...
1 CA file used to validate the API server’s serving certificate
2 Private RSA key file (for token signing)
3 Public RSA key files (for token verification). If private key files are provided, then the public key component is used. Multiple public key files can be specified, and a token will be accepted if it can be validated by one of the public keys. This allows rotation of the signing key, while still accepting tokens generated by the previous signer.

Managed service accounts

Service accounts are required in each project to run builds, deployments, and other pods. The managedNames setting in the master configuration file controls which service accounts are automatically created in every project:

serviceAccountConfig:
  ...
  managedNames: (1)
  - builder (1)
  - deployer (2)
  - default (3)
  - ...
1 List of service accounts to automatically create in every project
2 A builder service account in each project is required by build pods, and is given the system:image-builder role, which allows pushing images to any image stream in the project using the internal Docker registry.
3 A deployer service account in each project is required by deployment pods, and is given the system:deployer role, which allows viewing and modifying replication controllers and pods in the project.
4 A default service account is used by 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.

Infrastructure service accounts

Several infrastructure controllers run using service account credentials. The following service accounts are created in the OpenShift infrastructure namespace at server start, and given the following roles cluster-wide:

  • The replication-controller service account is assigned the system:replication-controller role

  • The deployment-controller service account is assigned the system:deployment-controller role

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

To configure the namespace where those service accounts are created, set the openshiftInfrastructureNamespace field in the master configuration file:

policyConfig:
  ...
  openshiftInfrastructureNamespace: openshift-infra

Set limitSecretReferences field in master configuration file to true to require pod secret references to be whitelisted by their service accounts. Set its value to false to allow pods to reference any secret in the namespace.

serviceAccountConfig:
  ...
  limitSecretReferences: false