Use ack-pod-identity-webhook to implement passwordless access and permission isolation for application pods - Container Service for Kubernetes

The ack-pod-identity-webhook is a key component that provides passwordless access and pod permission isolation for applications. This topic describes the ack-pod-identity-webhook component, its usage, and its change log.

Component overview

The ack-pod-identity-webhook component uses the Kubernetes MutatingAdmissionWebhook mechanism. This component simplifies the use of the RAM Roles for Service Accounts (RRSA) feature provided by Container Service for Kubernetes (ACK). It automatically injects the required OpenID Connect (OIDC) token mounts and environment variable configurations into application pods. This eliminates the need for complex manual configuration.

Usage

The ack-pod-identity-webhook automates the configuration of RRSA. This allows pods to directly assume RAM roles, providing a secure, passwordless, and fine-grained permission management solution for cloud resources at the pod level. For more information, see Use RRSA to configure RAM permissions for a ServiceAccount and implement pod permission isolation.

Custom configurations

Custom configurations for the ack-pod-identity-webhook component include settings for the component, namespace, service account, and pod.

Component configuration

Parameter

Type

Description

AutoInjectSTSEnvVars

boolean

Specifies whether to enable the feature that injects STS-related environment variables into pods by default.

true: Enables the feature.
false: Disables the feature.

Note

This parameter is supported only in version 0.4.0 and later.

Namespace configuration

Parameter

Type

Description

Example

pod-identity.alibabacloud.com/injection

Label

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

A value of on enables automatic configuration injection at the namespace level.
If this label is not configured or is set to another value, automatic configuration injection at the namespace level is disabled.

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

Service account configuration

Parameter	Type	Description	Example
pod-identity.alibabacloud.com/role-name	Annotation	The name of the RAM role associated with this service account. If this configuration item is not configured or its value is not a valid RAM role name, configurations are not automatically injected into pods that use 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	Specifies the validity period of the OIDC token mounted to pods that use this service account. Valid values: 600 to 43200. Unit: seconds. The default value is 3600. If you specify an invalid value, the default value 3600 is used.	`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	Specifies whether to inject the `ALIBABA_CLOUD_STS_ENDPOINT` environment variable into pods that use this service account. A value of `on` enables the injection of this environment variable. If this annotation is not configured or is set to another value, the injection of this environment variable is disabled. Note This parameter is supported only in version 0.3.0 and later.	`apiVersion: v1 kind: ServiceAccount metadata: name: test-sa namespace: test annotations: pod-identity.alibabacloud.com/inject-sts-endpoint: 'on'`

Pod configuration

Parameter	Type	Description	Example
pod-identity.alibabacloud.com/injection	Label	Specifies whether to enable automatic configuration injection for this pod. A value of `on` enables automatic configuration injection. If this label is not configured or is set to another value, the namespace configuration determines whether to enable automatic configuration injection. Note This parameter is supported only in version 0.2.0 and later.	`apiVersion: v1 kind: Pod metadata: name: test labels: pod-identity.alibabacloud.com/injection: 'on'`
pod-identity.alibabacloud.com/service-account-token-expiration	Annotation	Specifies the validity period of the OIDC token mounted to this pod. Valid values: 600 to 43200. Unit: seconds. The default value is 3600. If you specify an invalid value, the default value 3600 is used. Note If this configuration item exists on both the service account and the pod, the configuration on the service account is ignored.	`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	Restricts automatic configuration injection to specific containers within the pod. Use commas (,) to separate multiple container names. If this configuration item is not configured, configurations are automatically injected into all containers in the pod.	`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	Prevents automatic configuration injection for specific containers. Use commas (,) to separate multiple container names. Note If a container name is specified in both the `pod-identity.alibabacloud.com/only-containers` and `pod-identity.alibabacloud.com/skip-containers` configurations, the configuration in `pod-identity.alibabacloud.com/only-containers` is ignored.	`apiVersion: v1 kind: Pod metadata: name: test-pod namespace: test annotations: pod-identity.alibabacloud.com/skip-containers: 'controller,test'`

Change log

November 2025

Version number	Registry Address	Change time	Changes	Impact
0.4.0	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:0.4.0	November 24, 2025	Adds support for injecting STS-related environment variables into pods by default: `ALIBABA_CLOUD_STS_ENDPOINT`, `ALIBABA_CLOUD_STS_REGION`, and `ALIBABA_CLOUD_VPC_ENDPOINT_ENABLED`. You can disable this feature by setting the `AutoInjectSTSEnvVars` component configuration item to `false`. Upgrades the Golang version used by the component to 1.24.10 to improve component stability.	An abnormal component upgrade may cause pod creation to fail. Perform the upgrade during off-peak hours.

September 2025

Version number	Registry Address	Change time	Changes	Impact
0.3.1	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:0.3.1	September 08, 2025	Upgrades the Golang version used by the component to 1.24.6 to improve component stability.	An abnormal component upgrade may cause pod creation to fail. Perform the upgrade during off-peak hours.

June 2025

Version number	Registry Address	Change time	Changes	Impact
0.3.0	registry-cn-hangzhou.ack.aliyuncs.com/acs/ack-pod-identity-webhook:v0.3.0.0-g433f84b-aliyun	June 06, 2025	Adds support for configuring `pod-identity.alibabacloud.com/inject-sts-endpoint` on a ServiceAccount to enable the injection of the `ALIBABA_CLOUD_STS_ENDPOINT` environment variable into pods.	An abnormal component upgrade may cause pod creation to fail. Perform the upgrade during off-peak hours.

March 2025

Version number	Registry Address	Change time	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	Upgrades the Golang version used by the component to 1.23.7 to improve component stability.	An abnormal component upgrade may cause pod creation to fail. Perform the upgrade during off-peak hours.

December 2024

Version number	Registry Address	Change time	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	Adds support for enabling configuration injection by adding the `pod-identity.alibabacloud.com/injection: 'on'` label to pods. Optimizes support for Kubernetes 1.32.	An abnormal component upgrade may cause pod creation to fail. Perform the upgrade during off-peak hours.

June 2023

Version number	Registry Address	Change time	Changes	Impact of the change
0.1.1	registry.cn-hangzhou.aliyuncs.com/acs/ack-pod-identity-webhook:v0.1.1.0-gbddcb74-aliyun	June 07, 2023	Enhances the component's compatibility with ACK serverless clusters.	An abnormal component upgrade may cause pod creation to fail. Perform the upgrade during off-peak hours.

February 2023

Version number	Registry Address	Change time	Changes	Impact
0.1.0	registry.cn-hangzhou.aliyuncs.com/acs/ack-pod-identity-webhook:v0.1.0.9-g26b8fde-aliyun	February 01, 2023	Implements the feature to automatically mount OIDC tokens and configure environment variables for application pods.	Initial release.