All Products
Search

This Product

    Container Service for Kubernetes:ack-ram-authenticator

    Document Center

    Container Service for Kubernetes:ack-ram-authenticator

    Last Updated:Jun 24, 2026

    The ack-ram-authenticator add-on authenticates API server requests in ACK managed clusters via webhook token authentication and RAM. This topic covers the add-on overview, usage notes, configuration, and release notes.

    Overview

    The ack-ram-authenticator add-on authenticates API server requests in ACK managed clusters using Kubernetes-native webhook token authentication and RAM. You can define mappings between RAM identities and role-based access control (RBAC) permissions through custom resource definitions (CRDs) for flexible RBAC authorization.

    When a user assumes an Alibaba Cloud SSO role to access the API server, ack-ram-authenticator passes the session name corresponding to the user identity to the API server. This enables more secure auditing of access requests from different users who assume the same role.

    The following figure shows how webhook authentication works in an ACK managed cluster with ack-ram-authenticator installed.

    1111..png

    1. When you use a tool such as kubectl to authenticate to the API server, the kubectl client runs the exec command in the kubeconfig file and calls ack-ram-tool to generate a signed STS token URL.

    2. The kubectl client sends the authentication webhook to the API server, which routes it to ack-ram-authenticator.

    3. ack-ram-authenticator calls the GetCallerIdentity operation to obtain the caller identity from the token URL, then matches it against the identity mappings defined in RAMIdentityMapping configurations.

    4. The API server verifies the RBAC permissions of the matched RAM user or user group and returns the authentication result to the kubectl client.

    Usage notes

    See Use ack-ram-authenticator for webhook authentication.

    Configuration

    ack-ram-authenticator supports the following configurations:

    Parameter

    Type

    Description

    EnableNonBootstrapMapping

    boolean

    Whether to enable the RAM role-to-RBAC mappings configured in Step 5: Map RAM identities to RBAC permissions.

    • true: Enables the mappings configured in the cluster.

    • false: Disables the mappings. Only identity mappings required for node initialization are used.

    Note

    Applies to v0.4.0.0-g33f30dac-aliyun and later.

    Release notes

    April 2025

    Version

    Description

    Release date

    Impact

    v0.4.1.0-g8023a0b5-aliyun

    • Adds the "identitySource": ["ack-ram-authenticator"] identifier to the extra field in returned user information, enabling quick identification of users authenticated by ack-ram-authenticator.

    • Updates Golang to 1.24.2 for improved stability.

    2025-04-29

    Installing or uninstalling ack-ram-authenticator triggers a control plane restart, disrupting persistent API server connections. Perform these operations during off-peak hours to minimize service impact.

    March 2025

    Version

    Description

    Release date

    Impact

    v0.4.0.0-g33f30dac-aliyun

    Adds the EnableNonBootstrapMapping parameter. See Configuration.

    2025-03-31

    Installing or uninstalling ack-ram-authenticator triggers a control plane restart, disrupting persistent API server connections. Perform these operations during off-peak hours to minimize service impact.

    September 2024

    Version

    Description

    Release date

    Impact

    v0.3.0.0-gea598ff0-aliyun

    Updates Golang to 1.22.7 for improved stability.

    2024-09-09

    Installing or uninstalling ack-ram-authenticator triggers a control plane restart, disrupting persistent API server connections. Perform these operations during off-peak hours to minimize service impact.

    April 2024

    Version

    Description

    Release date

    Impact

    v0.2.1.3-g694325a9-aliyun

    Delivers ack-ram-authenticator version information with GetCallerIdentity calls for troubleshooting.

    2024-04-12

    Installing or uninstalling ack-ram-authenticator triggers a control plane restart, disrupting persistent API server connections. Perform these operations during off-peak hours to minimize service impact.

    v0.2.0.3-gcea89d25-aliyun

    Canary release.

    Adds ARM architecture support.

    2024-04-10

    November 2023

    Version

    Description

    Release date

    Impact

    v0.2.0.0-g9cf9d682-aliyun

    • Adds support for ACK serverless clusters.

    • Adds support for the new token format.

    2023-11-15

    Installing or uninstalling ack-ram-authenticator triggers a control plane restart, disrupting persistent API server connections. Perform these operations during off-peak hours to minimize service impact.

    May 2023

    Version

    Description

    Release date

    Impact

    v0.1.0.5-g6e50a122-aliyun

    Initial release of ack-ram-authenticator.

    2023-05-18

    Installing or uninstalling ack-ram-authenticator triggers a control plane restart, disrupting persistent API server connections. Perform these operations during off-peak hours to minimize service impact.