Use ack-pod-identity-webhook to enable password-free access and permission isolation for application pods - Container Service for Kubernetes

Automatically inject OIDC tokens into pods to enable password-free, per-pod RAM role access.

Introduction

ack-pod-identity-webhook uses the Kubernetes MutatingAdmissionWebhook mechanism to simplify RAM Roles for Service Accounts (RRSA) in ACK. It automatically injects OIDC token volume mounts and environment variables into application pods, eliminating manual configuration.

Usage

ack-pod-identity-webhook automates RRSA configuration, allowing pods to directly assume RAM roles. This enables password-free, per-pod permission isolation. See Configure RRSA for service accounts to isolate permissions among pods.

Custom configurations

Customize ack-pod-identity-webhook at the component, namespace, service account, and pod levels.

Component configuration

Parameter

Type

Description

AutoInjectSTSEnvVars

boolean

Supported in version 0.4.0 and later.

Specifies whether to inject STS-related environment variables into pods by default.

true: Enables this feature.
false: Disables this feature.

Namespace configuration

Parameter

Type

Description

Sample code

pod-identity.alibabacloud.com/injection

label

Specifies whether to enable automatic configuration injection for pods in the namespace.

on: Enables automatic configuration injection.
Disabled if this label is absent or set to another value.

apiVersion: v1
kind: Namespace
metadata:
  name: test
  labels:
    pod-identity.alibabacloud.com/injection: 'on'

pod-identity.alibabacloud.com/override-env

label

Supported in version 0.4.2 and later.

Specifies whether to enable automatic configuration override for pods in the namespace. If enabled, injected environment variables take precedence over existing ones with the same name.

true: Enables automatic configuration override.
Disabled if this label is absent or set to another value.

apiVersion: v1
kind: Namespace
metadata:
  name: test
  labels:
    pod-identity.alibabacloud.com/override-env: 'true'

Service account configuration

Parameter	Type	Description	Sample code
`pod-identity.alibabacloud.com/role-name`	annotation	The RAM role name for this service account. If absent or invalid, no configurations are injected into pods using this service account.	`apiVersion: v1 kind: ServiceAccount metadata: name: test-sa namespace: test annotations: pod-identity.alibabacloud.com/role-name: test-role`
`pod-identity.alibabacloud.com/service-account-token-expiration`	annotation	The OIDC token validity period for pods using this service account. Valid values: 600 to 43200. Unit: seconds. Default value: 3600. Invalid values fall back to the default.	`apiVersion: v1 kind: ServiceAccount metadata: name: test-sa namespace: test annotations: pod-identity.alibabacloud.com/service-account-token-expiration: '3600'`
`pod-identity.alibabacloud.com/inject-sts-endpoint`	annotation	Supported in version 0.3.0 and later. Specifies whether to inject the `ALIBABA_CLOUD_STS_ENDPOINT` environment variable into pods using this service account. `on`: Enables injection. Disabled if this annotation is absent or set to another value.	`apiVersion: v1 kind: ServiceAccount metadata: name: test-sa namespace: test annotations: pod-identity.alibabacloud.com/inject-sts-endpoint: 'on'`

Pod configuration

Parameter	Type	Description	Sample code
`pod-identity.alibabacloud.com/injection`	label	Supported in version 0.2.0 and later. Specifies whether to enable automatic configuration injection for this pod. `on`: Enables automatic configuration injection. Falls back to namespace-level configuration if this label is absent or set to another value.	`apiVersion: v1 kind: Pod metadata: name: test labels: pod-identity.alibabacloud.com/injection: 'on'`
`pod-identity.alibabacloud.com/override-env`	annotation	Supported in version 0.4.2 and later. Specifies whether to enable automatic configuration override for this pod. If enabled, injected environment variables take precedence over existing ones with the same name. `true`: Enables automatic configuration override. Falls back to namespace-level configuration if this annotation is absent or set to another value.	`apiVersion: v1 kind: Pod metadata: name: test annotations: pod-identity.alibabacloud.com/override-env: 'true'`
`pod-identity.alibabacloud.com/service-account-token-expiration`	annotation	The OIDC token validity period for this pod. Valid values: 600 to 43200. Unit: seconds. Default value: 3600. Invalid values fall back to the default. Note If this annotation is specified on both the service account and the pod, the pod-level annotation takes precedence.	`apiVersion: v1 kind: Pod metadata: name: test-pod namespace: test annotations: pod-identity.alibabacloud.com/service-account-token-expiration: '3600'`
`pod-identity.alibabacloud.com/only-containers`	annotation	The containers to inject configurations into. Separate names with commas (,). If absent, all containers receive injected configurations.	`apiVersion: v1 kind: Pod metadata: name: test-pod namespace: test annotations: pod-identity.alibabacloud.com/only-containers: 'controller,test'`
`pod-identity.alibabacloud.com/skip-containers`	annotation	Containers to exclude from configuration injection. Separate names with commas (,). Note If a container name is specified in both `pod-identity.alibabacloud.com/only-containers` and `pod-identity.alibabacloud.com/skip-containers`, the setting in `pod-identity.alibabacloud.com/only-containers` for that container is ignored.	`apiVersion: v1 kind: Pod metadata: name: test-pod namespace: test annotations: pod-identity.alibabacloud.com/skip-containers: 'controller,test'`

Release notes

April 2026

Version	Image address	Release date	Changes	Impact
0.4.3	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:0.4.3	April 23, 2026	Upgraded Go to 1.25.9 to improve stability.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

January 2026

Version	Image address	Release date	Changes	Impact
0.4.2	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:0.4.2	January 29, 2026	Added automatic configuration override. Injected variables take precedence over existing pod variables with the same name. Enable at the namespace or pod level with the `pod-identity.alibabacloud.com/override-env` label or annotation. Upgraded Go to 1.25.6 to improve stability.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

November 2025

Version	Image address	Release date	Changes	Impact
0.4.0	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:0.4.0	November 24, 2025	By default, the following STS-related environment variables are now injected into pods: `ALIBABA_CLOUD_STS_ENDPOINT`, `ALIBABA_CLOUD_STS_REGION`, and `ALIBABA_CLOUD_VPC_ENDPOINT_ENABLED`. Disable by setting the `AutoInjectSTSEnvVars` component parameter to `false`. Upgraded Go to 1.24.10 to improve stability.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

September 2025

Version	Image address	Release date	Changes	Impact
0.3.1	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:0.3.1	September 8, 2025	Upgraded Go to 1.24.6 to improve stability.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

June 2025

Version	Image address	Release date	Changes	Impact
0.3.0	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:v0.3.0.0-g433f84b-aliyun	June 6, 2025	Added `ALIBABA_CLOUD_STS_ENDPOINT` injection via the `pod-identity.alibabacloud.com/inject-sts-endpoint` service account annotation.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

March 2025

Version	Image address	Release date	Changes	Impact
0.2.1	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:v0.2.1.0-g52e519c-aliyun	March 18, 2025	Upgraded Go to 1.23.7 to improve stability.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

December 2024

Version	Image address	Release date	Changes	Impact
0.2.0	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:v0.2.0.11-g2f0c2e7-aliyun	December 19, 2024	Added pod-level configuration injection via the `pod-identity.alibabacloud.com/injection: 'on'` label. Improved support for Kubernetes 1.32.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

June 2023

Version	Image address	Release date	Changes	Impact
0.1.1	registry.cn-hangzhou.aliyuncs.com/acs/ack-pod-identity-webhook:v0.1.1.0-gbddcb74-aliyun	June 7, 2023	Improved compatibility with ACK Serverless clusters.	Pod creation may fail if an exception occurs during upgrade. Upgrade during off-peak hours.

February 2023

Version	Image address	Release date	Changes	Impact
0.1.0	registry.cn-hangzhou.aliyuncs.com/acs/ack-pod-identity-webhook:v0.1.0.9-g26b8fde-aliyun	February 1, 2023	Implemented automatic OIDC token mounting and environment variable injection for application pods.	Initial release.