Chapter 11. Using bound service account tokens

Procedure

1. Optionally, set the service account issuer.

   This step is typically not required if the bound tokens are used only within the cluster.

   Warning

   If you update the serviceAccountIssuer field and there are bound tokens already in use, all bound tokens with the previous issuer value will be invalidated. Unless the holder of a bound token has explicit support for a change in issuer, the holder will not request a new bound token until pods have been restarted.

   If necessary, you can use the following command to manually restart all pods in the cluster. Be aware that running this command causes a service interruption, because it deletes every running pod in every namespace. These pods will automatically restart after they are deleted.

   $ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \
         do oc delete pods --all -n $I; \
         sleep 1; \
         done

   1. Edit the cluster Authentication object:

      $ oc edit authentications cluster

   2. Set the spec.serviceAccountIssuer field to the desired service account issuer value:

      spec:
        serviceAccountIssuer: https://test.default.svc 1

      1

      This value should be a URL from which the recipient of a bound token can source the public keys necessary to verify the signature of the token. The default is https://kubernetes.default.svc.

2. Configure a pod to use a bound service account token by using volume projection.

   1. Create a file called pod-projected-svc-token.yaml with the following contents:

      apiVersion: v1
      kind: Pod
      metadata:
        name: nginx
      spec:
        containers:
        - image: nginx
          name: nginx
          volumeMounts:
          - mountPath: /var/run/secrets/tokens
            name: vault-token
        serviceAccountName: build-robot 1
        volumes:
        - name: vault-token
          projected:
            sources:
            - serviceAccountToken:
                path: vault-token 2
                expirationSeconds: 7200 3
                audience: vault 4

      1

      A reference to an existing service account.

      2

      The path relative to the mount point of the file to project the token into.

      3

      Optionally set the expiration of the service account token, in seconds. The default is 3600 seconds (1 hour) and must be at least 600 seconds (10 minutes). The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.

      4

      Optionally set the intended audience of the token. The recipient of a token should verify that the recipient identity matches the audience claim of the token, and should otherwise reject the token. The audience defaults to the identifier of the API server.

   2. Create the pod:

      $ oc create -f pod-projected-svc-token.yaml

      The kubelet requests and stores the token on behalf of the pod, makes the token available to the pod at a configurable file path, and refreshes the token as it approaches expiration.

3. The application that uses the bound token must handle reloading the token when it rotates.

   The kubelet rotates the token if it is older than 80 percent of its time to live, or if the token is older than 24 hours.