Adding a Service Account Authentication Token to a Kubeconfig File

Find out how to add a service account authentication token to the kubeconfig file of a Kubernetes cluster you've created using Kubernetes Engine (OKE).

When you set up the kubeconfig file for a cluster, by default it contains an Oracle Cloud Infrastructure CLI command to generate a short-lived, cluster-scoped, user-specific authentication token. The authentication token generated by the CLI command is appropriate to authenticate individual users accessing the cluster using kubectl and the Kubernetes Dashboard.

However, the generated authentication token is not appropriate to authenticate processes and tools accessing the cluster, such as continuous integration and continuous delivery (CI/CD) tools. To ensure access to the cluster, such tools require long-lived, non-user-specific authentication tokens.

One solution is to use a Kubernetes service account, as described in this topic. Having created a service account, you bind it to a clusterrolebinding that has cluster administration permissions. You create an authentication token for the service account, which is stored as a Kubernetes secret. You can then add the service account (and its associated service account authentication token) as a user definition in the kubeconfig file itself. Other tools can then use the service account authentication token when accessing the cluster.

Note that to run the commands in this topic, you must have the appropriate permissions. See About Access Control and Kubernetes Engine (OKE).

To add a service account authentication token to a kubeconfig file:

1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig configuration file and (if necessary) set the KUBECONFIG environment variable to point to the file. Note that you must set up your own kubeconfig file. You cannot access a cluster using a kubeconfig file that a different user set up. See Setting Up Cluster Access.

2. In a terminal window, create a new service account in the kube-system namespace by entering the following kubectl command:

   kubectl -n kube-system create serviceaccount <service-account-name>

   For example, to create a service account called kubeconfig-sa, enter:

   kubectl -n kube-system create serviceaccount kubeconfig-sa

   The output from the above command confirms the creation of the service account. For example:

   serviceaccount/kubeconfig-sa created

   Note that creating the service account in the kube-system namespace is recommended good practice, and is assumed in the instructions in this topic. However, if you prefer, you can create the service account in another namespace to which you have access.

3. Create a new clusterrolebinding with cluster administration permissions and bind it to the service account you just created by entering the following kubectl command:

   kubectl create clusterrolebinding <binding-name> --clusterrole=cluster-admin --serviceaccount=kube-system:<service-account-name>

   For example, to create a clusterrolebinding called add-on-cluster-admin and bind it to the kubeconfig-sa service account, enter:

   kubectl create clusterrolebinding add-on-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:kubeconfig-sa

   The output from the above command confirms the creation of the clusterrolebinding. For example:

   clusterrolebinding.rbac.authorization.k8s.io/add-on-cluster-admin created

4. Obtain an authentication token for the kubeconfig-sa service account as follows:
   1. In a text editor, create a file (for example, called oke-kubeconfig-sa-token.yaml) to create a secret (for example, named oke-kubeconfig-sa-token) with the following content:

      apiVersion: v1
      kind: Secret
      metadata:
        name: oke-kubeconfig-sa-token
        namespace: kube-system
        annotations:
          kubernetes.io/service-account.name: kubeconfig-sa
      type: kubernetes.io/service-account-token

   2. Create the service account token by entering:

      kubectl apply -f <filename>

      where <filename> is the name of the file you created earlier. For example:

      kubectl apply -f oke-kubeconfig-sa-token.yaml

   3. View details of the secret by entering:

      kubectl describe secrets oke-kubeconfig-sa-token -n kube-system

      The output from the above command includes an authentication token (a long alphanumeric string) as the value of the token: element, as shown below:

      Name:         oke-kubeconfig-sa-token
      Namespace:    kube-system
      Labels:       <none>
      Annotations:  kubernetes.io/service-account.name: kubeconfig-sa
      kubernetes.io/service-account.uid: 6d0fda1c-b456-44b3-25fd-4a824bef1936
      Type:  kubernetes.io/service-account-token
      Data
      ====
      ca.crt:     1289 bytes
      namespace:  11 bytes
      token:      bxYk______rz15A

      In the example above, bxYk______rz15A (abbreviated for readability) is the authentication token.

5. Obtain the value of the service account authentication token and assign its value (decoded from base64) to an environment variable. These instructions assume you specify TOKEN as the name of the environment variable. The commands to enter depend on the operating system:

   • To obtain the value of the service account authentication token in a MacOS, Linux, or Unix environment, enter the following command:

     TOKEN=`kubectl -n kube-system get secret oke-kubeconfig-sa-token -o jsonpath='{.data.token}' | base64 --decode`

   • To obtain the value of the service account authentication token in a Windows environment:

     1. Enter the following command:

        kubectl -n kube-system get secret oke-kubeconfig-sa-token -o jsonpath='{.data.token}'

     2. Copy the output from the above command and paste it into a base64 decoder (for example, https://www.base64decode.org, https://www.base64decode.net, or similar).
     3. Copy the output from the base64 decoder.

     4. Enter the following command:

        TOKEN=`[<base64-decoded-output>]`

        where <base64-decoded-output> is the output you copied from the base64 decorder.

6. Add the service account (and its authentication token) as a new user definition in the kubeconfig file by entering the following kubectl command:

   kubectl config set-credentials <service-account-name> --token=$TOKEN

   The service account (and its authentication token) is added to the list of users defined in the kubeconfig file.

   For example, to add the kubeconfig-sa service account and its authentication token to the kubeconfig file, enter:

   kubectl config set-credentials kubeconfig-sa --token=$TOKEN

   The output from the above command confirms the service account has been added to the kubeconfig file. For example:

   User "kubeconfig-sa" set.

7. Set the user specified in the kubeconfig file for the current context to be the new service account user you created, by entering the following kubectl command:

   kubectl config set-context --current --user=<service-account-name>

   For example:

   kubectl config set-context --current --user=kubeconfig-sa

   The output from the above command confirms the current context has been changed. For example:

   Context "context-ctdiztdhezd" modified.

8. (Optional) To verify that authentication works as expected, run a kubectl command to confirm that the service account user can be successfully authenticated using the service account authentication token.

   For example, if you have previously deployed a sample Nginx application on the cluster (see Deploying a Sample Nginx App on a Cluster Using Kubectl), enter the following command:

   kubectl get pods -n kube-system

   The output from the above command shows the pods running on the cluster. If the command runs successfully, the service account user in the kubeconfig file has been successfully authenticated using the service account authentication token.

9. Distribute the kubeconfig file as necessary to enable other processes and tools (such as continuous integration and continuous delivery (CI/CD) tools) to access the cluster.

kubectl -n kube-system delete secret <secret-name>