Required RBAC permissions for the ack-cluster-agent - Container Service for Kubernetes

When you register an external Kubernetes cluster with Container Service for Kubernetes (ACK), the ack-cluster-agent component runs inside your cluster and connects it to the ACK control plane. All ACK console operations against the registered cluster go through ack-cluster-agent, which runs under a ServiceAccount named ack in the kube-system namespace. The permissions granted to that ServiceAccount determine what the ACK console can do in your cluster.

Two base permission modes are available:

Mode	Console capabilities	When to use
Restricted mode	Workload visibility is unavailable. Component management and services such as Managed Service for Prometheus and Simple Log Service (SLS) are available through onectl.	Least-privilege environments
Administrator mode	All console features are available	Full console access required

Additional permissions are required for specific operations: installing components, creating node pools, enabling log queries, or viewing resources in read-only mode.

Prerequisites

Before you begin, ensure that you have:

ack-cluster-agent version 1.13.1.105-g8ee9abb-aliyun or later installed. For more information, see Manage components.

Grant restricted mode permissions

Restricted mode requires read access to a specific set of ConfigMaps in the kube-system and kube-public namespaces. Apply the following Roles and RoleBindings to your cluster:

---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ack-agent-create-cm-role
  namespace: kube-system
  labels:
    ack/creator: "ack"
rules:
- apiGroups:
  - ""
  resources:
  - configmaps
  verbs:
  - create
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ack-agent-update-cm-role
  namespace: kube-system
  labels:
    ack/creator: "ack"
rules:
- apiGroups:
  - ""
  resources:
  - configmaps
  resourceNames:
  - ack-agent-config
  - provider
  verbs:
  - update
  - get

---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ack-agent-read-cm-role
  namespace: kube-public
  labels:
    ack/creator: "ack"
rules:
- apiGroups:
  - ""
  resources:
  - configmaps
  resourceNames:
  - kube-root-ca.crt
  verbs:
  - get

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: ack-agent-create-cm-rolebinding
  namespace: kube-system
  labels:
    ack/creator: "ack"
subjects:
- kind: ServiceAccount
  name: ack
  namespace: kube-system
roleRef:
  kind: Role
  name: ack-agent-create-cm-role
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: ack-agent-update-cm-rolebinding
  namespace: kube-system
  labels:
    ack/creator: "ack"
subjects:
- kind: ServiceAccount
  name: ack
  namespace: kube-system
roleRef:
  kind: Role
  name: ack-agent-update-cm-role
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: ack-agent-read-cm-rolebinding
  namespace: kube-public
  labels:
    ack/creator: "ack"
subjects:
- kind: ServiceAccount
  name: ack
  namespace: kube-system
roleRef:
  kind: Role
  name: ack-agent-read-cm-role
  apiGroup: rbac.authorization.k8s.io
---

In restricted mode, workload visibility in the ACK console is unavailable. To manage components and use services such as Managed Service for Prometheus and SLS, use onectl. When onectl manages components, it temporarily elevates the cluster to administrator permissions and revokes them when the operation completes or is interrupted. For more information, see Use onectl to manage registered clusters.

Grant administrator mode permissions

Administrator mode grants full access to all cluster resources. Apply the following ClusterRole to the ack ServiceAccount:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ack-admin
  labels:
    ack/creator: "ack"
rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]

Grant permissions for component management

Installing or updating components such as terway-eniip or logtail-ds requires temporary administrator permissions because the operations write to cluster-scoped resources. Follow this workflow:

Step 1: Elevate to administrator permissions

Apply the administrator ClusterRole shown in Grant administrator mode permissions before installing or updating components.

Step 2: Install or update the component

Proceed with the component installation or update.

Step 3: Restore least permissions

After you install or update components, restore the ClusterRole to the least permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ack-admin
  labels:
    ack/creator: "ack"
rules:
- apiGroups: [""]
  resources: ["nodes"]
  verbs: ["get","list","watch"]
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["ack-agent-config","provider"]
  verbs: ["get","list","watch","update"]
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["autoscaler-meta"]
  verbs: ["get","list","watch","update"]
- apiGroups: ["*"]
  resources: ["daemonsets", "deployments"]
  resourceNames: ["terway-eniip","security-inspector","ack-cluster-agent","gatekeeper","ack-virtual-node","metrics-server","logtail-ds","resource-controller","aliyun-acr-credential-helper","migrate-controller","ack-kubernetes-cronhpa-controller","tiller-deploy"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["*"]
  resources: ["daemonsets", "deployments"]
  resourceNames: ["cluster-autoscaler"]
  verbs: ["get", "list", "watch", "update"]
- apiGroups: [""]
  resources: ["pods","secrets"]
  verbs: ["list"]

Grant permissions for node pool creation

Installing Terway or creating node pools also requires temporary administrator permissions. Follow the same elevate-then-restore workflow:

Step 1: Elevate to administrator permissions

Apply the administrator ClusterRole shown in Grant administrator mode permissions before installing Terway or creating node pools.

Step 2: Create the node pool or install Terway

Proceed with the operation.

Step 3: Restore least permissions

After you install Terway or create node pools, restore the ClusterRole to the least permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ack-admin
  labels:
    ack/creator: "ack"
rules:
- apiGroups: [""]
  resources: ["nodes"]
  verbs: ["get","list","watch"]
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["ack-agent-config","provider","autoscaler-meta","eni-config"]
  verbs: ["get","list","watch","update"]
- apiGroups: ["*"]
  resources: ["daemonsets", "deployments"]
  resourceNames: ["terway-eniip", "cluster-autoscaler"]
  verbs: ["get", "list", "watch", "update"]

Grant permissions for Simple Log Service log queries

After enabling Simple Log Service (SLS) in the registered cluster, apply the following ClusterRole and ClusterRoleBinding to query logs in the ACK console:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ack-agent-role-log
  labels:
    ack/creator: "ack"
rules:
- apiGroups: [""]
  resources: ["namespaces"]
  verbs: ["get","list","watch"]
- apiGroups: ["apps"]
  resources: ["daemonsets", "deployments"]
  resourceNames: ["alibaba-log-controller", "logtail-ds", "kube-proxy-master"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["alibaba-log-configuration"]
  verbs: ["get","list","watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ack-agent-binding-log
  labels:
    ack/creator: "ack"
subjects:
- kind: ServiceAccount
  name: ack
  namespace: kube-system
roleRef:
  kind: ClusterRole
  name: ack-agent-role-log
  apiGroup: rbac.authorization.k8s.io

Grant read-only permissions

Read-only permissions let you view Kubernetes resources in the ACK console without making changes. Apply the following ClusterRole and ClusterRoleBinding:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ack-readonly-clusterrole
rules:
- apiGroups:
  - ""
  resources:
  - nodes
  - namespaces
  - pods
  - pods/log
  - pods/exec
  - configmaps
  - endpoints
  - events
  - limitranges
  - persistentvolumeclaims
  - podtemplates
  - replicationcontrollers
  - resourcequotas
  - serviceaccounts
  - services
  verbs:
  - get
  - list
- apiGroups:
  - apps
  resources:
  - deployments
  - daemonsets
  - statefulsets
  - replicasets
  verbs:
  - get
  - list
- apiGroups:
  - batch
  resources:
  - jobs
  - cronjobs
  verbs:
  - get
  - list
- apiGroups:
  - coordination.k8s.io
  resources:
  - leases
  verbs:
  - get
  - list
- apiGroups:
  - discovery.k8s.io
  resources:
  - endpointslices
  verbs:
  - get
  - list
- apiGroups:
  - events.k8s.io
  resources:
  - events
  verbs:
  - get
  - list
- apiGroups:
  - extensions
  resources:
  - daemonsets
  - deployments
  - ingresses
  - networkpolicies
  - replicasets
  verbs:
  - get
  - list
- apiGroups:
  - networking.k8s.io
  resources:
  - ingresses
  - networkpolicies
  verbs:
  - get
  - list
- apiGroups:
  - policy
  resources:
  - poddisruptionbudgets
  verbs:
  - get
  - list
- apiGroups:
  - rbac.authorization.k8s.io
  resources:
  - rolebindings
  - roles
  verbs:
  - get
  - list
- apiGroups:
  - storage.k8s.io
  resources:
  - csistoragecapacities
  verbs:
  - get
  - list

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ack-readonly-clusterrolebinding
  labels:
    ack/creator: "ack"
subjects:
- kind: ServiceAccount
  name: ack
  namespace: kube-system
roleRef:
  kind: ClusterRole
  name: ack-readonly-clusterrole
  apiGroup: rbac.authorization.k8s.io