Service Account

Welcome to this lesson on Kubernetes service accounts. In this article, we explore how service accounts serve as the backbone for authenticating and authorizing machine-to-cluster interactions. While closely related to authentication, authorization, and role-based access control topics, this guide specifically focuses on creating and managing service accounts as part of our Kubernetes curriculum.

There are two primary account types in Kubernetes:

• User Accounts: For human users such as administrators and developers.
• Service Accounts: For machine users, such as monitoring tools (e.g., Prometheus) or CI/CD systems like Jenkins.

Example: Kubernetes Dashboard Application

Consider a simple dashboard application, “my Kubernetes dashboard,” built in Python. When deployed, it queries the Kubernetes API to retrieve the list of Pods and displays them on a web page. For secure communication with the Kubernetes API, the application uses a service account to authenticate.

Creating a Service Account

To create a service account for your application, run the following command. In this example, we create a service account named dashboard-sa:

kubectl create serviceaccount dashboard-sa

After creation, list all service accounts with:

kubectl get serviceaccount

The output might look similar to:

NAME          SECRETS   AGE
default       1         218d
dashboard-sa  1         4d

Inspect the newly created service account along with its token by executing:

kubectl describe serviceaccount dashboard-sa

This command will show details including the associated token (stored as a secret), such as:

Name:                dashboard-sa
Namespace:           default
Labels:              <none>
Annotations:         <none>
Image pull secrets:  <none>
Mountable secrets:   dashboard-sa-token-kbbdm
Tokens:              dashboard-sa-token-kbbdm
Events:              <none>

The token is stored in a Secret object. To view the token, describe the corresponding secret:

kubectl describe secret dashboard-sa-token-kbbdm

Use the token as a bearer authentication token when accessing the Kubernetes API. For example:

curl https://192.168.56.70:6443/api --insecure --header "Authorization: Bearer eyJhbgG…"

Automatic Token Mounting in Pods

When a third-party application is deployed on a Kubernetes cluster, the service account token is automatically mounted as a volume inside the Pod. This allows your application to read the token from a well-known location rather than providing it manually.

By default, each namespace in Kubernetes includes a service account named default. When a Pod is created without specifying a service account, Kubernetes mounts the default service account’s token into the Pod. Consider the following minimal Pod definition:

apiVersion: v1
kind: Pod
metadata:
  name: my-kubernetes-dashboard
spec:
  containers:
    - name: my-kubernetes-dashboard
      image: my-kubernetes-dashboard

To inspect the Pod, run:

kubectl describe pod my-kubernetes-dashboard

A typical output displays that a secret (e.g., default-token-j4hkv) is mounted at /var/run/secrets/kubernetes.io/serviceaccount:

Name:         my-kubernetes-dashboard
Namespace:    default
Status:       Running
IP:           10.244.0.15
Containers:
  my-kubernetes-dashboard:
    Image:      my-kubernetes-dashboard
Mounts:
  /var/run/secrets/kubernetes.io/serviceaccount from default-token-j4hkv (ro)
Volumes:
  default-token-j4hkv:
    Type:        Secret (a volume populated by a Secret)
    SecretName:  default-token-j4hkv
    Optional:    false

Inside the Pod, you can list the mounted secret files:

kubectl exec -it my-kubernetes-dashboard -- ls /var/run/secrets/kubernetes.io/serviceaccount

And to view the token:

kubectl exec -it my-kubernetes-dashboard -- cat /var/run/secrets/kubernetes.io/serviceaccount/token

The file named token contains the bearer token used for accessing the Kubernetes API. Keep in mind that the default service account has limited permissions geared towards basic API queries.

Using a Custom Service Account in Pods

To use a service account other than the default (for example, dashboard-sa), update your Pod definition by specifying the serviceAccountName field:

apiVersion: v1
kind: Pod
metadata:
  name: my-kubernetes-dashboard
spec:
  containers:
    - name: my-kubernetes-dashboard
      image: my-kubernetes-dashboard
  serviceAccountName: dashboard-sa

After recreating the Pod (since you cannot change the service account for an existing Pod), inspect it with:

kubectl describe pod my-kubernetes-dashboard

You should notice that the volume now mounts the token belonging to dashboard-sa:

Mounts:
  /var/run/secrets/kubernetes.io/serviceaccount from dashboard-sa-token-kbbdm (ro)

If you prefer to disable the automatic mounting of the service account token, set the automountServiceAccountToken field to false:

apiVersion: v1
kind: Pod
metadata:
  name: my-kubernetes-dashboard
spec:
  automountServiceAccountToken: false
  containers:
    - name: my-kubernetes-dashboard
      image: my-kubernetes-dashboard

Changes in Kubernetes Versions 1.22 and 1.24

Starting with Kubernetes 1.22, enhancements were made to how service account tokens are handled. Previously, creating a service account automatically produced a Secret with a non-expiring token. Now, tokens are generated via the token request API and mounted as projected volumes with a defined lifetime.

The following is an example Pod manifest that reflects the new token provisioning method:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  namespace: default
spec:
  containers:
    - image: nginx
      name: nginx
      volumeMounts:
        - mountPath: /var/run/secrets/kubernetes.io/serviceaccount
          name: kube-api-access-6mtg8
          readOnly: true
  volumes:
    - name: kube-api-access-6mtg8
      projected:
        defaultMode: 420
        sources:
          - serviceAccountToken:
              expirationSeconds: 3607
              path: token
          - configMap:
              name: kube-root-ca.crt
              items:
                - key: ca.crt
                  path: ca.crt
          - downwardAPI:
              items:
                - fieldRef:
                    apiVersion: v1
                    fieldPath: metadata.namespace

In this configuration, the token is automatically requested with a specified validity (e.g., 3607 seconds) and is mounted through a projected volume rather than a pre-created secret.

With Kubernetes version 1.24, further improvements (as detailed in Kubernetes Enhancement Proposal 2799) have minimized the use of secret-based service account tokens. Now, when a service account is created, a token is not automatically generated. Instead, explicitly generate a token using this command if needed:

kubectl create token dashboard-sa

This command produces a token that is both audience-bound and time-limited. You can adjust the expiration using additional options. If you prefer the legacy behavior of creating non-expiring tokens stored in Secrets (though this method is less secure), manually create a Secret object with the proper annotation:

apiVersion: v1
kind: Secret
type: kubernetes.io/service-account-token
metadata:
  name: mysecretname
  annotations:
    kubernetes.io/service-account.name: dashboard-sa

Ensure that the service account (dashboard-sa) already exists before creating this Secret.

Summary

In this lesson, you learned how to:

• Create a service account and retrieve its token (either stored as a Secret or generated via the token request API).
• Automatically mount the service account token into Pods for in-cluster applications.
• Customize Pod definitions to use a specific service account or disable automatic token mounting.
• Understand the improvements in Kubernetes versions 1.22 and 1.24 regarding bound, time-limited tokens using the token request API.

For further reading, refer to the official Kubernetes documentation and relevant enhancement proposals.