Kubernetes (K8s)

The Kubernetes (K8s) Auth Method uses K8s JWTs in order to authenticate the K8s application (e.g. a pod). Throughout the process, this K8s JWT is never shared with Akeyless or any other third party, but only with the Akeyless Gateway that is controlled and operated in the customer environment. It is therefore considered a trusted machine.


  • Akeyless Gateway with network access to the K8s cluster.

  • K8s v1.21 and higher.



Required Gateway Access Permissions

To set K8s Authentication method, make sure you have Access Permissions on your Gateway to manage the K8s Auth

Authentication Strategies

Akeyless supports several authentication strategies to interact with the K8s cluster. Each of the below links describes the entire flow of creating the Akeyless K8s Auth Method. Choose the one that works for you and follow the entire flow:



ServiceAccount approaches work based on K8s bearer tokens, whereas Certificate-based Authentication works based on a certificate and private key

Using Akeyless Gateway ServiceAccount

In order to work with your Gateway Service Account the following K8s role should be assigned to the Service Account that runs your Gateway, Please make sure to adjust the ServiceAccount:name and namespace fields according to your environment:

cat << EOF > akl_gw_sa_token_reviewer.yaml 
apiVersion: v1
kind: ServiceAccount
  name: <Gateway SA Name>
  namespace: default
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
  name: role-tokenreview-binding
  namespace: default
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:auth-delegator
- kind: ServiceAccount
  name: <Gateway SA Name>
  namespace: default 

Apply the changes:

kubectl apply -f akl_gw_sa_token_reviewer.yaml

Create K8s Auth Method

Use the Akeyless CLI to create the Kubernetes auth method which will restrict access to 2 different pods, named mypod1 and mypod2 from the namespace my-namespace-a. The result contains an Access Id and a private key that you will need later for the K8S Auth configuration in your Gateway:

akeyless create-auth-method-k8s -n my-k8s-auth-method --bound-pod-names mypod1 \
    --bound-pod-names mypod2 --bound-namespaces my-namespace-a --json

Upon successful creation, the response:

  "access_id": "p-abcdefg1234",
  "prv_key": "LS0tLS1CRUdJTiBSUlNDUUxt.....QVRFIEtFWS0tLS0tCg=="



Save returned private key & AccessID for next steps inside an environment variables $PRV_KEY and $ACCESS_ID

Create K8s Gateway Auth Config Using Gateway ServiceAccount

Use the Akeyless CLI to create the K8S auth config:

akeyless gateway-create-k8s-auth-config  --name k8s-conf \
--gateway-url <https://Your-Akeyless-GW-URL>:8000 \
--access-id $ACCESS_ID \
--signing-key $PRV_KEY \


  • name: The config name (will be used during the authentication process).

  • gateway-url: Akeyless Gateway Configuration Manager URL (port 8000).

  • access-id: The Access Id of the Kubernetes auth method that was created.

  • signing-key: The private key (The key that was created when the Kubernetes auth method was created).

  • use-gw-service-account: Extract all the relevant information using the Gateway Service Account.

Authenticate from a pod in your K8s cluster

  1. Create a namespace with a name that the auth method access is restricted to:
kubectl create namespace my-namespace-a
  1. In this namespace, create a pod with a name that the auth method access is restricted to:
kubectl run mypod1 --image=nginx -n my-namespace-a
  1. Start an interactive shell session on the pod and perform the following commands in the pod:
kubectl exec --stdin=true --namespace my-namespace-a  --tty=true mypod1 -- /bin/sh
  1. Install Akeyless CLI inside your pod:
curl -o akeyless https://akeyless-cli.s3.us-east-2.amazonaws.com/cli/latest/production/cli-linux-amd64
chmod +x akeyless
  1. Authenticate via your Kubernetes auth method as follows:
./akeyless auth --access-id $ACCESS_ID \
    --access-type k8s \
    --gateway-url https://<Your-GW-URL>:8000 \
    --k8s-auth-config-name k8s-conf


  • access-id: The Access Id of the Kubernetes auth method that was created.

  • access-type: the access type - k8s

  • gateway-url: Akeyless Gateway Configuration Manager URL (port 8000).

  • k8s-auth-config-name: The K8s auth config name in your Gateway.

Upon successful authentication, the response will be:

Authentication succeeded.
Token: t-bb7b...3564a7c9



Delete the private key and Access ID which you stored as an environment variables $PRV_KEY and $ACCESS_ID

Available claims for K8s Auth

The following list of claims can be configured within Akeyless Access Roles (RBAC) to control and segregate the relevant policy for K8s.

"pod_name"   # available only when "token request projection" is enabled on your Kubernetes cluster
"pod_uid"    # available only when "token request projection" is enabled on your Kubernetes cluster

Each claim can be enforced as part of your role association to enforce the right policy for your items.

Enable token request projection on Minikube

To enable token request projection on a managed K8s cluster you can follow this guide.

To get this to work with Minikube you can start your cluster with the following configuration.

minikube start \
    --vm-driver=none \
    --extra-config=apiserver.service-account-signing-key-file=/var/lib/minikube/certs/sa.key \
    --extra-config=apiserver.service-account-key-file=/var/lib/minikube/certs/sa.pub \
    --extra-config=apiserver.service-account-issuer=api \
    --extra-config=apiserver.service-account-api-audiences=api,spire-server \
    --extra-config=apiserver.authorization-mode=Node,RBAC \



This example uses api as the service account issuer name, for your service accounts API audience.


Check out our tutorial video on Kubernetes Authentication.