Skip to main content

​
User types in Kubernetes

Kubernetes clusters have several categories of users:
  • Administrators — manage the cluster
  • Developers — deploy or test applications
  • End-users — access applications running in the cluster
  • Third-party applications or bots — interact with the cluster for integration purposes

​
Authentication mechanisms

All user access is managed by the kube-apiserver. It authenticates every incoming request before processing it. Supported authentication methods:

Client certificates

The most common and recommended method for authenticating users and components.

Static password file

(Deprecated) A CSV file containing usernames and passwords passed to the kube-apiserver.

Static token file

A CSV file containing usernames and tokens passed to the kube-apiserver.

Identity provider (third-party)

External identity systems like LDAP or Kerberos.

Service account tokens

Used by processes and applications running inside pods.

​
Static password file (deprecated)

Create a CSV file with password, username, and user ID. Pass it to the kube-apiserver via --basic-auth-file. The configuration file is at /etc/kubernetes/manifests/kube-apiserver.yaml.
passwords.csv
# password, username, user Id, group (optional)
password1,joe_user,joe_userID
password1,joe_user,joe_userID,group1
Authenticate using curl: 
curl -v -k https://master-node-ip:6443/api/v1/pods -u "username:password"

​
Static token file

Create a CSV file with token, username, and user ID. Pass it to the kube-apiserver via --token-auth-file.
tokens.csv
# token, username, user Id, group (optional)
mjpuauwabcnIXBicj12cnXoaS,joe_user,joe_userID
ajpuauwabcnIXBicj12cnXoaS,joe_user,joe_userID,group1
Authenticate using curl: 
curl -v -k https://master-node-ip:6443/api/v1/pods --header "Authorization: Bearer <replace-your-token>"

​
Authenticate using kubeconfig

Refer to KubeConfig for more information.

​
Authenticate using kubectl proxy

kubectl proxy

​
Bootstrap token authentication

Bootstrap tokens authenticate with the kube-apiserver when creating a new cluster or joining a new node. They are valid for 24 hours by default.
Once a node has joined the cluster using a bootstrap token, the token expiration does not affect the node’s cluster membership. The node switches to client certificate authentication after joining. Bootstrap tokens are only used for the initial join process.
1

Create a bootstrap token

Two options are available:Using kubeadm (run on a node with kubeadm installed):
kubeadm token generate                           # generate and print a token (does not create it on the server)
kubeadm token create                             # create bootstrap token on the server
kubeadm token create --dry-run --print-join-command  # preview the secret YAML and join command
Manually: the bootstrap token format must match ^[a-z0-9]{6}\.[a-z0-9]{16}$.
2

Store the bootstrap token as a Kubernetes Secret

The secret must exist in the kube-system namespace.
bootstrap-token-07401b.yaml
apiVersion: v1
kind: Secret
metadata:
  name: bootstrap-token-07401b
  namespace: kube-system
type: bootstrap.kubernetes.io/token
stringData:
  description: "The default bootstrap token generated by 'kubeadm init'."
  token-id: 07401b
  token-secret: f395accd246ae52d
  usage-bootstrap-authentication: "true"
  usage-bootstrap-signing: "true"
  auth-extra-groups: system:bootstrappers:worker,system:bootstrappers:ingress,system:bootstrappers:kubeadm:default-node-token
FieldDescription
usage-bootstrap-authenticationToken can authenticate to kube-apiserver as a bearer token
usage-bootstrap-signingToken may sign the cluster-info ConfigMap
system:bootstrappers:workerPermissions for worker nodes joining the cluster
system:bootstrappers:ingressPermissions for ingress-specific nodes
system:bootstrappers:kubeadm:default-node-tokenDefault kubeadm node join permissions
3

Get the worker node join command

Run this on the control plane node:
kubeadm token create <token-id>.<token-secret> --dry-run --print-join-command
4

Join the worker node to the cluster

On the worker node (or via SSH), run the join command. Ensure kubeadm, kubelet, and kubectl are installed on the worker node.
# SSH into the worker node
ssh node1

# Run the join command (example output)
kubeadm join kind-cluster-control-plane:6443 \
  --token joisdm.akqtwa3n4swya2ol \
  --discovery-token-ca-cert-hash sha256:dae81a955efb64d6e568d1dafc6ad7a3c2afc6be65345c9bb86a3429440e4c07
5

Verify the worker node joined the cluster

Run this from the control plane node:
kubectl get nodes
6

Authenticate using the bootstrap secret (optional)

# Get the kube-apiserver address
kubectl cluster-info
kubectl config view

# Decode the token id and secret from the Kubernetes Secret
kubectl get secret bootstrap-token-07401b -n kube-system -o jsonpath='{.data.token-id}' | base64 --decode
kubectl get secret bootstrap-token-07401b -n kube-system -o jsonpath='{.data.token-secret}' | base64 --decode

export TOKEN=<decoded-token-id>.<decoded-token-secret>
curl -v -k -X GET https://kind-cluster-control-plane:6443/api/v1/pods --header "Authorization: Bearer $TOKEN"

​
Service account token authentication

1

Create a service account

data-sa.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: data-sa
2

Associate a secret with the service account

data-sa-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: data-sa-secret
  annotations:
    kubernetes.io/service-account.name: data-sa
type: kubernetes.io/service-account-token
3

Retrieve the token

kubectl get secret/data-sa-secret -o jsonpath='{.data.token}' | base64 -d
export TOKEN=<decoded-token>
4

Create a Role and RoleBinding

Grant the service account permission to list pods in the default namespace.
kubectl create role pod-reader --verb=list --resource=pods
kubectl create rolebinding pod-reader-binding --role=pod-reader --serviceaccount=default:data-sa
5

Authenticate using the service account token

curl -v -k -X GET https://kind-cluster-control-plane:6443/api/v1/namespaces/default/pods \
  --header "Authorization: Bearer $TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us