> ## 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.

# Service Accounts

> Manage Kubernetes ServiceAccounts for pod identity and API access

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

<CardGroup cols={2}>
  <Card title="ServiceAccount" icon="user-circle">
    A namespace-scoped identity for pods to authenticate with the Kubernetes API and external services.
  </Card>

  <Card title="Secrets" icon="key">
    Tokens and credentials automatically mounted into pods using the ServiceAccount.
  </Card>

  <Card title="ImagePullSecrets" icon="image">
    Credentials for pulling container images from private registries.
  </Card>

  <Card title="Auto Mount" icon="plug">
    Whether to automatically mount the ServiceAccount token into pods.
  </Card>
</CardGroup>

<Info>
  ServiceAccounts are **namespace-scoped** resources. Each namespace has a `default` ServiceAccount that is automatically assigned to pods that don't specify one.
</Info>

## Required Permissions

| Action                | Permission                                     |
| --------------------- | ---------------------------------------------- |
| View ServiceAccounts  | `iam:project:infrastructure:kubernetes:read`   |
| Create ServiceAccount | `iam:project:infrastructure:kubernetes:write`  |
| Edit ServiceAccount   | `iam:project:infrastructure:kubernetes:write`  |
| Delete ServiceAccount | `iam:project:infrastructure:kubernetes:delete` |

## ServiceAccount Types

| Type       | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| **System** | Built-in accounts (named `default` or prefixed with `system:`) |
| **Custom** | User-created ServiceAccounts                                   |

<Warning>
  The `default` ServiceAccount exists in every namespace and should not be deleted. It is automatically used by pods that don't specify a ServiceAccount.
</Warning>

## How to View ServiceAccounts

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Select Namespace">
    Choose a namespace to view ServiceAccounts in that namespace.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find ServiceAccounts by name. Filter by type (System, Custom).
  </Step>
</Steps>

## How to View ServiceAccount Details

<Steps>
  <Step title="Find the ServiceAccount">
    Locate the ServiceAccount in the list.
  </Step>

  <Step title="Click ServiceAccount Name">
    Click on the name to open the detail drawer.
  </Step>

  <Step title="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
  </Step>
</Steps>

## How to Create a ServiceAccount

<Steps>
  <Step title="Click Create ServiceAccount">
    Click the **Create ServiceAccount** button in the page header.
  </Step>

  <Step title="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
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

## How to Edit a ServiceAccount

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the ServiceAccount row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the YAML editor.
  </Step>

  <Step title="Modify Configuration">
    Edit the ServiceAccount. You can modify:

    * `automountServiceAccountToken`
    * `imagePullSecrets`
    * Labels and annotations
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

## How to Delete a ServiceAccount

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the ServiceAccount row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu (disabled for `default` ServiceAccount).
  </Step>

  <Step title="Confirm">
    Confirm the deletion. Pods using this ServiceAccount may fail to function properly.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Example ServiceAccounts

### Basic ServiceAccount

```yaml theme={null}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-service-account
  namespace: default
```

### Disable Auto-Mount Token

```yaml theme={null}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: no-token-sa
  namespace: default
automountServiceAccountToken: false
```

### With ImagePullSecrets

```yaml theme={null}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: private-registry-sa
  namespace: production
imagePullSecrets:
  - name: docker-registry-secret
  - name: gcr-secret
```

### Full Configuration

```yaml theme={null}
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

| Field                            | Description                        | Default        |
| -------------------------------- | ---------------------------------- | -------------- |
| **automountServiceAccountToken** | Auto-mount API token into pods     | `true`         |
| **secrets**                      | Tokens for API authentication      | Auto-generated |
| **imagePullSecrets**             | Credentials for private registries | None           |

## Auto Mount Token

The `automountServiceAccountToken` field controls whether the ServiceAccount token is automatically mounted into pods:

| Setting          | Behavior                                                                   |
| ---------------- | -------------------------------------------------------------------------- |
| `true` (default) | Token mounted at `/var/run/secrets/kubernetes.io/serviceaccount`           |
| `false`          | No automatic token mount (more secure for pods that don't need API access) |

<Tip>
  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.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pod cannot pull images from private registry">
    * 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
  </Accordion>

  <Accordion title="Pod cannot authenticate with Kubernetes API">
    * 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
  </Accordion>

  <Accordion title="Cannot delete ServiceAccount">
    * The `default` ServiceAccount cannot be deleted
    * Verify you have delete permission
    * Check if pods are still using this ServiceAccount
  </Accordion>

  <Accordion title="Token not mounted in pod">
    * Check `automountServiceAccountToken` at both ServiceAccount and Pod spec levels
    * Pod spec setting overrides ServiceAccount setting
    * Verify the ServiceAccount is correctly referenced in the pod
  </Accordion>

  <Accordion title="ServiceAccount token expired or invalid">
    * 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
  </Accordion>

  <Accordion title="Permissions not working after binding">
    * 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
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is the default ServiceAccount?">
    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.
  </Accordion>

  <Accordion title="How do I grant permissions to a ServiceAccount?">
    Create a RoleBinding or ClusterRoleBinding that binds the ServiceAccount to a Role or ClusterRole:

    ```yaml theme={null}
    subjects:
      - kind: ServiceAccount
        name: my-service-account
        namespace: my-namespace
    ```
  </Accordion>

  <Accordion title="Should I create separate ServiceAccounts for each application?">
    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.
  </Accordion>

  <Accordion title="What are imagePullSecrets used for?">
    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.
  </Accordion>

  <Accordion title="When should I disable automountServiceAccountToken?">
    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.
  </Accordion>

  <Accordion title="How are ServiceAccount tokens managed in Kubernetes 1.24+?">
    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
  </Accordion>

  <Accordion title="Can a pod use a ServiceAccount from another namespace?">
    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.
  </Accordion>

  <Accordion title="How do I check what permissions a ServiceAccount has?">
    Use kubectl to test permissions:

    ```bash theme={null}
    kubectl auth can-i list pods \
      --as=system:serviceaccount:<namespace>:<sa-name>
    ```

    Or check all RoleBindings/ClusterRoleBindings that reference the ServiceAccount.
  </Accordion>
</AccordionGroup>