Container Service for Kubernetes:Enable API server webhook authentication with ack-ram-authenticator in ACK managed clusters

Prerequisites

An ACK managed cluster (version 1.24.6-aliyun.1 or later) is created. See Create an ACK managed cluster.

Usage notes

• Installing or uninstalling ack-ram-authenticator restarts the API server and disconnects long-lived connections. Schedule during off-peak hours.

• Webhook authentication does not block API server access with KubeConfig from DescribeClusterUserKubeconfig.

• ack-ram-authenticatoris also supported on ACK Serverless Clusters.

How ack-ram-authenticator works

ack-ram-authenticator is an authentication add-on for ACK managed clusters. It uses Kubernetes Webhook Token Authentication to authenticate API server requests with Alibaba Cloud RAM and maps RAM identities to RBAC permissions as CRDs.

When a user assumes an Alibaba Cloud SSO role to access an ACK managed cluster API server, ack-ram-authenticator passes the session name for that identity to the API server. This lets the API server authenticate 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.

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.

Step 1: Install ack-ram-authenticator

Install the ack-ram-authenticator server-side add-on to enable RAM webhook authentication with the cluster API server.

1. Log on to the ACK console. In the left navigation pane, click Clusters.

2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Components and Add-ons.

3. On the Add-ons page, click the Security tab, find the ack-ram-authenticator add-on, and click Install in the lower-right corner of the card. In the Parameters dialog box that appears, select the EnableNonBootstrapMapping option, and then click OK.

Step 2: Install the ack-ram-tool client

On your local machine, ack-ram-tool generates a KubeConfig file with credentials for a cluster.

Step 3: Configure Alibaba Cloud credentials

aliyun configure --mode External --profile sso

Configuring profile 'sso' in 'External' authenticate mode...
Process Command [acs-sso login --profile sso]:
Default Region Id [cn-shanghai]:
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en:
Saving profile[sso] ...Done.


Configure Done!!!
..............888888888888888888888 ........=8888888888888888888D=..............
...........88888888888888888888888 ..........D8888888888888888888888I...........
.........,8888888888888ZI: ...........................=Z88D8888888888D..........
.........+88888888 ..........................................88888888D..........
.........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
.........+88888888 ............. ************* ..............O8888888D..........
.........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
.........+88888888...........................................88888888D..........
..........D888888888888DO+. ..........................?ND888888888888D..........
...........O8888888888888888888888...........D8888888888888888888888=...........
............ .:D8888888888888888888.........78888888888888888888O ..............

Step 4: Generate a KubeConfig file

1. Generate a KubeConfig file. Command details: get-kubeconfig.

   ack-ram-tool credential-plugin get-kubeconfig --cluster-id $cluster_id --mode ram-authenticator-token

2. Merge or replace your existing KubeConfig with the generated file. See Organizing Cluster Access Using kubeconfig Files.

Step 5: Map RAM identities to RBAC permissions

After you install ack-ram-authenticator, the cluster creates a RAMIdentityMapping CRD that maps RAM identities to Kubernetes user models. As a cluster administrator, map a RAM user or RAM role to a Kubernetes user with RBAC permissions.

1. Create a configuration template file named auth.yaml with this content:

   cat >auth.yaml <<EOF
   ---
   apiVersion: ramauthenticator.k8s.alibabacloud/v1alpha1
   kind: RAMIdentityMapping
   metadata:
     name: tester
   spec:
     arn: '<ARN>'
     username: tester
     groups:
       - system:users    
   EOF

   • Each RAMIdentityMapping instance maps one RAM ARN to a username and groups. Create one instance per mapping.

   • Replace <ARN> with the target RAM user or RAM role ARN. The following table lists ARN formats by account type.

     Account type	ARN format	Example
     Alibaba Cloud account	acs:ram::<root_uid>:root <root_uid> is the Alibaba Cloud Account ID.	acs:ram::123456789012****:root
     RAM user	acs:ram::<root_uid>:user/<user_name> <root_uid> is the Alibaba Cloud Account ID and <user_name> is the RAM user name.	acs:ram::123456789012****:user/testuser
     RAM role	acs:ram::<root_uid>:role/<role_name> <root_uid> is the Alibaba Cloud Account ID and <role_name> is the RAM role name. See View the information about a RAM role to view a RAM role ARN.	acs:ram::123456789012****:role/testrole

2. Create the RAMIdentityMapping instance:

   kubectl apply -f auth.yaml

3. Configure RBAC permissions for the cluster. Create custom RBAC roles and bindings as needed.

   Example RBAC binding:

   cat >binding.yaml <<EOF
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: tester-clusterrolebinding
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: cs:ops
   subjects:
   - apiGroup: rbac.authorization.k8s.io
     kind: User
     name: tester
   EOF
   
   kubectl apply -f binding.yaml

Step 6: Send requests with KubeConfig

Use the KubeConfig file from Step 4 to send a request to the API server and verify success within the configured permissions.

kubectl get ns

Expected output:

NAME              STATUS   AGE
arms-prom         Active   4h48m
default           Active   4h50m
kube-node-lease   Active   4h50m
kube-public       Active   4h50m
kube-system       Active   4h50m

References

• ack-ram-authenticator