Pods often need direct access to the Kubernetes API server to read or modify cluster state. This guide shows how a pod uses its service account token and in-cluster configurations to call the API securely.
TL;DR
- Pods use service account tokens mounted as secret volumes to authenticate to the API server.
KUBERNETES_SERVICE_HOSTandKUBERNETES_SERVICE_PORTenv vars let in-cluster clients discover the API endpoint.- RBAC roles and role bindings grant granular API permissions to pods.
- Client libraries (client-go) or curl can call the API using mounted tokens.
- Service account token volumes refresh periodically for long-running pods.
- Use security contexts and quotas to control API usage per namespace or pod.
💡 Tip: The Kubernetes API server exposes a RESTful interface on port 6443 by default.
Kubernetes API Access Basics
The Kubernetes API server exposes a RESTful interface on port 6443 by default. Pods inside the cluster can call it via HTTPS using credentials from their assigned service account. In-cluster config files and env vars simplify client code by providing endpoint and token data automatically.
Creating a Service Account for Kubernetes API Access
Create a service account and bind it to RBAC roles to scope your pod’s API permissions.
apiVersion: v1
kind: ServiceAccount
metadata:
name: api-access-sa
namespace: default
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: pod-reader
namespace: default
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "list"]
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: pod-reader-binding
namespace: default
subjects:
- kind: ServiceAccount
name: api-access-sa
namespace: default
roleRef:
kind: Role
name: pod-reader
apiGroup: rbac.authorization.k8s.io
Accessing the Kubernetes API from Pod
When you launch a pod with the service account, Kubernetes mounts a secret volume at /var/run/secrets/kubernetes.io/serviceaccount containing a token and CA certificate.
apiVersion: v1
kind: Pod
metadata:
name: api-client-pod
namespace: default
spec:
serviceAccountName: api-access-sa
containers:
- name: client
image: curlimages/curl
command: ["sleep", "3600"]
Service Account Token Volume Type
Kubernetes uses the secret volume type to project the service account token and CA bundle into the pod. The volume lifecycle ties to pod lifecycle. Tokens refresh every hour to maintain session validity. CSI token projected volumes can replace legacy secrets for ephemeral token mounting.
RBAC and Access Controls for Kubernetes API Access
RBAC rules define which API actions a pod can perform. Use Role and ClusterRole to group API permissions. Then bind them to your service account with RoleBinding or ClusterRoleBinding. This enforces the principle of least privilege.
Environment Variables and Endpoint Discovery for Kubernetes API Access
Inside a pod, KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT env vars point to the API server. Client libraries auto-populate an in-cluster config object using these env vars and mounted files at /var/run/secrets/kubernetes.io/serviceaccount.
Client Libraries and Shell Tools
You can use client-go in Go code or call the API directly with curl. Below is an example CURL call to list pods:
TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
CACERT=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
API=https://${KUBERNETES_SERVICE_HOST}:${KUBERNETES_SERVICE_PORT}
curl --cacert ${CACERT} --header "Authorization: Bearer ${TOKEN}" ${API}/api/v1/pods
Security Contexts and Quotas
Use PodSecurityContext to set file permissions on the token volume. Limit API usage with ResourceQuota on namespace APIRequests when applicable. Enforce security contexts to prevent privilege escalation.
Use-Cases
Common event-driven patterns include operators, controllers, and webhook servers that watch for resource changes and act via the API. CronJobs can poll custom resources using curl or client libraries inside pods.
References
Suggested Reading
PostHashiID: c0c55ee6faa1892993b881409bcb1c3c92585d2bbad0bc1e9d0e6f15ecc9dba7
