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 Container Engine for Kubernetes (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 Container Engine for Kubernetes.

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

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.

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

Command
Copy
Try It
kubectl -n kube-system create serviceaccount <service-account-name>

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

Command
Copy
Try It
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.

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

Command
Copy
Try It
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:

Command
Copy
Try It
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
Obtain an authentication token for the kubeconfig-sa service account as follows:
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:
Copy
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

Create the service account token by entering:

Command
Copy
Try It
kubectl apply -f <filename>

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

Command
Copy
Try It
kubectl apply -f oke-kubeconfig-sa-token.yaml

View details of the secret by entering:

Command
Copy
Try It
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.

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:

Command
Copy
Try It
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:

Enter the following command:

Command
Copy
Try It
kubectl -n kube-system get secret oke-kubeconfig-sa-token -o jsonpath='{.data.token}'
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).
Copy the output from the base64 decoder.

Enter the following command:

Command
Copy
Try It
TOKEN=`[<base64-decoded-output>]`

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

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

Command
Copy
Try It
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:

Command
Copy
Try It
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.

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:

Command
Copy
Try It
kubectl config set-context --current --user=<service-account-name>

For example:

Command
Copy
Try It
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.

(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:

Command
Copy
Try It
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.

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



If you subsequently want to remove access to the cluster from the service account, delete the Kubernetes secret containing the service account authentication token by entering the following command:

Command
Copy
Try It
kubectl -n kube-system delete secret <secret-name>