Vault Kubernetes Auth Guide: Service Account Integration and Sidecar Patterns

The standard way to securely authenticate Kubernetes Pods to Vault is the Kubernetes Auth Method backed by Service Account tokens. This article walks through RBAC and role design, plus the implementation details of secret distribution via the Vault Agent Injector sidecar, from both exam and operational perspectives.

On the Associate exam, expect questions on the components of auth/kubernetes, how Service Accounts map to Vault roles, Agent Injector annotations and behavior, and the concepts of token renewal and TTL. The configuration examples, comparison tables, and diagrams below should help cement the picture.

Big Picture: Kubernetes Auth + Service Account + Sidecar Flow

The Kubernetes Auth Method uses the Service Account (SA) JWT that is auto-mounted into a Pod. Vault validates it through the Kubernetes API and issues a Vault token in return. In the sidecar pattern, the Vault Agent handles auto-authentication, secret fetching, and template rendering inside the Pod, and the application reads secrets from files.

In practice, distributing secrets via files through a sidecar (or Init container) is usually easier to operate than having the application talk to Vault directly, and it makes rotation and reload control simpler. The diagram below shows the flow from authentication to secret injection.

• Input: the Pod's Service Account JWT (short-lived Projected Tokens recommended)
• Verification: Vault queries the Kubernetes API to validate the token
• Output: a Vault token (with policy-scoped permissions) and secrets that the sidecar fetches and refreshes

Typical Kubernetes Auth + sidecar flow

Minimal configuration in concept (excerpt)

# Pod内のService Accountトークンを使い、VaultのKubernetes Authでlogin。
# SidecarのVault Agentがテンプレートでシークレットをファイル出力し、
# アプリはread-onlyでマウントされたボリュームから読み取る。

Step by Step: Configuring Vault's Kubernetes Auth

On the Vault server, enable the Kubernetes Auth Method, prepare a Service Account that can call TokenReview against the Kubernetes API, and register the required information into auth/kubernetes/config. This lets Vault validate Pod JWTs as legitimate Kubernetes-issued tokens.

Least-privilege RBAC is sufficient — grant only the permissions needed for TokenReview and validating Service Account tokens in the relevant namespaces.

• Prerequisite: Vault can reach the Kubernetes API (network and certificates)
• Recommended: Projected Service Account Tokens (short-lived, audience-scoped)
• Security: be explicit about how kubernetes_ca_cert is handled and how TLS verification is performed

Relationship between the configuration components

Enabling Kubernetes Auth and configuring RBAC (example)

# 1) Vault側: Kubernetes Authを有効化
vault auth enable kubernetes

# 2) Reviewer用のService Account/RBAC（kube側）
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: vault-token-reviewer
  namespace: vault
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: system:token-reviewer
rules:
- apiGroups: ["authentication.k8s.io"]
  resources: ["tokenreviews"]
  verbs: ["create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: vault-token-reviewer-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:token-reviewer
subjects:
- kind: ServiceAccount
  name: vault-token-reviewer
  namespace: vault

# 3) VaultにK8sクラスタ情報を登録
# 環境に合わせて$K8S_HOST, $REVIEWER_JWT, $CA_CERTを用意
vault write auth/kubernetes/config \
  kubernetes_host="$K8S_HOST" \
  token_reviewer_jwt="$REVIEWER_JWT" \
  kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

Designing the Service Account to Vault Role Mapping

A Vault Kubernetes role binds Vault policies to a specific Service Account name + namespace combination and issues a token to logins from authorized Pods. Use bound_service_account_names, bound_service_account_namespaces, and optionally bound_audiences to constrain the JWT audience.

TTL and token type (service, batch) are also controlled by the role. Choose a TTL that is not too short and decide whether to allow renewal, based on your app's refresh cadence and the cost of restarts.

• Bind both SA and namespace to prevent misapplication
• Scope the audience to Vault to reduce replay risk
• Keep policies minimal — be especially careful with where list permissions are granted

How roles and policies are wired together

Role creation and policy example

# ポリシー: kv v2の特定パスのみ許可
tee kv-app.hcl <<'EOF'
path "kv/data/app/*" {
  capabilities = ["read"]
}
EOF
vault policy write kv-app kv-app.hcl

# ロール: app Namespaceのweb SAにバインド
aud="vault"
vault write auth/kubernetes/role/app-web \
  bound_service_account_names=web \
  bound_service_account_namespaces=app \
  bound_audiences="$aud" \
  policies=kv-app \
  ttl=1h \
  token_type=default

Distributing via Sidecar: Implementing the Vault Agent Injector

The Vault Agent Injector automatically injects a sidecar and shared volume into a Pod just by adding annotations. It authenticates via Kubernetes Auth, evaluates templates, and writes files. The app simply reads them as environment-variable files or config files.

For certificates and short-lived tokens that need rotation, combining the Agent's auto-renewal with SIGHUP-based reloads typically yields a stable setup.

• Add annotations to the Pod template in your Deployment or StatefulSet
• Specify the Vault role name with vault.hashicorp.com/role
• Templates can produce JSON, YAML, ENV, or any other format you need

In-Pod layout produced by the Injector

Minimal Deployment annotation example (generates config.json from kv v2)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: app
spec:
  replicas: 1
  selector:
    matchLabels: { app: web }
  template:
    metadata:
      labels: { app: web }
      annotations:
        vault.hashicorp.com/agent-inject: "true"
        vault.hashicorp.com/role: "app-web"
        # 出力ファイル名は注釈の末尾と一致
        vault.hashicorp.com/agent-inject-secret-config: "kv/data/app/config"
        vault.hashicorp.com/agent-inject-template-config: |
          {{- with secret "kv/data/app/config" -}}{{ .Data.data | toJSON }}{{- end -}}
    spec:
      serviceAccountName: web
      containers:
      - name: app
        image: ghcr.io/example/web:1.0
        volumeMounts:
        - name: vault-secrets
          mountPath: /vault/secrets
          readOnly: true
      volumes:
      - name: vault-secrets
        emptyDir:
          medium: Memory

Security and Operations: Token Renewal, TTL, and Failure Behavior

Vault tokens issued via Kubernetes Auth are automatically renewable within the role's ttl and max_ttl. The sidecar Agent renews before expiry and retries on failure. If renewal keeps failing, template re-evaluation stops, and the app continues to reference the last file the Agent produced.

For stable operation, combine monitoring (remaining token TTL, template update timestamps), a Pod restart strategy, and SIGHUP-based config reloads. This limits the blast radius if an auth break ever occurs.

• Keep Projected SA Token lifetimes short (minutes to tens of minutes)
• Balance the Vault token TTL against your app's reload characteristics
• Plan around retries and backoff for transient network or API outages

Simplified renewal loop

Template example (environment-variable file) and reload

# テンプレート例: .env 形式
{{- with secret "kv/data/app/db" -}}
DB_USER={{ .Data.data.username }}
DB_PASS={{ .Data.data.password }}
{{- end -}}

# アプリ側: ファイル変更検知でSIGHUP
# inotifywait等で /vault/secrets/.env の更新を監視し、プロセスにSIGHUP送出

Exam Prep and Pitfalls: Key Points Checklist

The Associate exam tests terminology and flow. Make sure you firmly grasp the role of the reviewer token, the role binding conditions, what each Injector annotation does, and kv v2 path conventions.

Common pitfalls include login failures from audience or namespace/SA name mismatches, and confusing /data with /metadata in kv v2 paths.

• The reviewer SA's token is for Vault to call TokenReview against the K8s API — it is not for the application
• On auth/kubernetes/role, bound_service_account_names and namespaces are evaluated with AND
• In kv v2, reads go to secret/data/... and metadata is at secret/metadata/...

Mini glossary diagram

Manual login check via the CLI (for troubleshooting)

# Pod内での手動テスト例（デバッグ用途）
SA_JWT=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
vault write auth/kubernetes/login role=app-web jwt="$SA_JWT"
# auth成功後に VAULT_TOKEN を使って読み取り
echo $VAULT_TOKEN | vault kv get -format=json kv/app/config

Check Your Understanding

Frequently Asked Questions