Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt

Use this file to discover all available pages before exploring further.

ServiceAccounts provide identities for pods running in a cluster. They enable pods to authenticate with the Kubernetes API and other services, and can be associated with secrets for credentials and image pull authentication.

​
Key Concepts

ServiceAccount

A namespace-scoped identity for pods to authenticate with the Kubernetes API and external services.

Secrets

Tokens and credentials automatically mounted into pods using the ServiceAccount.

ImagePullSecrets

Credentials for pulling container images from private registries.

Auto Mount

Whether to automatically mount the ServiceAccount token into pods.
ServiceAccounts are namespace-scoped resources. Each namespace has a default ServiceAccount that is automatically assigned to pods that don’t specify one.

​
Required Permissions

ActionPermission
View ServiceAccountsiam:project:infrastructure:kubernetes:read
Create ServiceAccountiam:project:infrastructure:kubernetes:write
Edit ServiceAccountiam:project:infrastructure:kubernetes:write
Delete ServiceAccountiam:project:infrastructure:kubernetes:delete

​
ServiceAccount Types

TypeDescription
SystemBuilt-in accounts (named default or prefixed with system:)
CustomUser-created ServiceAccounts
The default ServiceAccount exists in every namespace and should not be deleted. It is automatically used by pods that don’t specify a ServiceAccount.

​
How to View ServiceAccounts

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

Select Namespace

Choose a namespace to view ServiceAccounts in that namespace.
3

Filter and Search

Use the search box to find ServiceAccounts by name. Filter by type (System, Custom).

​
How to View ServiceAccount Details

1

Find the ServiceAccount

Locate the ServiceAccount in the list.
2

Click ServiceAccount Name

Click on the name to open the detail drawer.
3

Review Details

View ServiceAccount information including:
  • Overview: Name, namespace, type (system/custom), age
  • Secrets: List of associated secrets with token data
  • ImagePullSecrets: Registry credentials for pulling images
  • Auto Mount: Whether tokens are automatically mounted
  • Labels & Annotations: Metadata attached to the ServiceAccount

​
How to Create a ServiceAccount

1

Click Create ServiceAccount

Click the Create ServiceAccount button in the page header.
2

Write YAML

Enter the ServiceAccount manifest in YAML format. Key fields:
  • metadata.name - ServiceAccount name
  • metadata.namespace - Target namespace
  • automountServiceAccountToken - Whether to auto-mount tokens
  • imagePullSecrets - Optional registry credentials
3

Create

Click Create to apply the manifest.

​
How to Edit a ServiceAccount

1

Open Actions Menu

Click the actions menu (three dots) on the ServiceAccount row.
2

Click Edit YAML

Select Edit YAML to open the YAML editor.
3

Modify Configuration

Edit the ServiceAccount. You can modify:
  • automountServiceAccountToken
  • imagePullSecrets
  • Labels and annotations
4

Save

Click Update to apply changes.

​
How to Delete a ServiceAccount

1

Open Actions Menu

Click the actions menu on the ServiceAccount row.
2

Click Delete

Select Delete from the menu (disabled for default ServiceAccount).
3

Confirm

Confirm the deletion. Pods using this ServiceAccount may fail to function properly.
Deleting a ServiceAccount affects all pods that use it. Those pods will lose their identity and may fail to authenticate with the Kubernetes API or pull images from private registries.

​
Example ServiceAccounts

​
Basic ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-service-account
  namespace: default

​
Disable Auto-Mount Token

apiVersion: v1
kind: ServiceAccount
metadata:
  name: no-token-sa
  namespace: default
automountServiceAccountToken: false

​
With ImagePullSecrets

apiVersion: v1
kind: ServiceAccount
metadata:
  name: private-registry-sa
  namespace: production
imagePullSecrets:
  - name: docker-registry-secret
  - name: gcr-secret

​
Full Configuration

apiVersion: v1
kind: ServiceAccount
metadata:
  name: deployment-sa
  namespace: app-namespace
  labels:
    app: my-app
    environment: production
  annotations:
    description: "ServiceAccount for my-app deployments"
automountServiceAccountToken: true
imagePullSecrets:
  - name: private-registry-credentials
secrets:
  - name: app-token-secret

​
Key Fields

FieldDescriptionDefault
automountServiceAccountTokenAuto-mount API token into podstrue
secretsTokens for API authenticationAuto-generated
imagePullSecretsCredentials for private registriesNone

​
Auto Mount Token

The automountServiceAccountToken field controls whether the ServiceAccount token is automatically mounted into pods:
SettingBehavior
true (default)Token mounted at /var/run/secrets/kubernetes.io/serviceaccount
falseNo automatic token mount (more secure for pods that don’t need API access)
Set automountServiceAccountToken: false for pods that don’t need to interact with the Kubernetes API. This follows the principle of least privilege and improves security.

​
Troubleshooting

  • Verify the ServiceAccount has the correct imagePullSecrets
  • Check the Secret exists and contains valid registry credentials
  • Ensure the pod spec references the ServiceAccount
  • Verify the registry URL in the Secret matches the image reference
  • Check automountServiceAccountToken is not set to false
  • Verify RoleBindings/ClusterRoleBindings exist for the ServiceAccount
  • Check if the token Secret exists and is valid
  • Verify the ServiceAccount exists in the pod’s namespace
  • The default ServiceAccount cannot be deleted
  • Verify you have delete permission
  • Check if pods are still using this ServiceAccount
  • Check automountServiceAccountToken at both ServiceAccount and Pod spec levels
  • Pod spec setting overrides ServiceAccount setting
  • Verify the ServiceAccount is correctly referenced in the pod
  • Kubernetes 1.24+ uses bound service account tokens with expiration
  • Tokens are automatically refreshed by the kubelet
  • For long-running processes, ensure proper token refresh handling
  • Consider using projected volumes for token configuration
  • Verify the RoleBinding/ClusterRoleBinding references the correct ServiceAccount
  • Check the namespace is correct in the binding’s subject
  • Use kubectl auth can-i --as=system:serviceaccount:<namespace>:<name> to test

​
FAQ

Every namespace automatically has a default ServiceAccount. Pods that don’t specify a ServiceAccount use this one. It has minimal permissions by default and cannot be deleted.
Create a RoleBinding or ClusterRoleBinding that binds the ServiceAccount to a Role or ClusterRole:
subjects:
  - kind: ServiceAccount
    name: my-service-account
    namespace: my-namespace
Yes. Each application should have its own ServiceAccount with only the permissions it needs. This follows the principle of least privilege and limits the blast radius if an application is compromised.
ImagePullSecrets provide credentials for pulling container images from private registries. When a pod uses a ServiceAccount with imagePullSecrets, those credentials are automatically used to pull images.
Disable auto-mount when:
  • The pod doesn’t need to access the Kubernetes API
  • You want to improve security by not exposing credentials
  • You’re using a different authentication method
Set automountServiceAccountToken: false on the ServiceAccount or in the pod spec.
Starting with Kubernetes 1.24:
  • Tokens are no longer auto-generated as Secrets
  • Bound service account tokens are created on-demand with expiration
  • Tokens are automatically refreshed by the kubelet
  • Legacy token Secrets are not created by default
No. A pod can only use a ServiceAccount from its own namespace. To grant cross-namespace permissions, use ClusterRoleBindings or create identical ServiceAccounts in each namespace.
Use kubectl to test permissions:
kubectl auth can-i list pods \
  --as=system:serviceaccount:<namespace>:<sa-name>
Or check all RoleBindings/ClusterRoleBindings that reference the ServiceAccount.