全部产品
Search

搜索本产品

    容器服务 Kubernetes 版 ACK：通过onectl管理注册集群

    文档中心

    容器服务 Kubernetes 版 ACK：通过onectl管理注册集群

    更新时间：Aug 11, 2026

    onectl是阿里云分布式云容器平台为注册集群提供的命令行工具，您可以通过onectl进行注册集群、相关组件以及组件RAM用户的管理。

    onectl介绍

    onectl主要包含以下功能。

    • 集群管理

      创建注册集群、列出注册集群当前的状态、连接注册集群与线下集群、列出当前RAM用户所有的注册集群、删除注册集群。

    • 组件管理

      安装组件、升级组件、列出集群中所有已安装的组件、列出所有可安装的组件、删除组件。

    • 组件RAM用户管理

      根据组件名授予组件RAM用户对应的权限、列出组件RAM用户的所有权限、根据组件名称撤销对应的权限。

    实现原理

    展开查看onectl的实现原理

    与目标集群的通信

    通过onectl连接注册集群与目标集群时，onectl需要在目标集群中部署注册集群agent，此时，onectl将按照以下优先级依次尝试使用对应的KubeConfig与目标集群进行通信。

    1. kubeconfig参数

      例如，通过以下命令使用~/.kube/config配置文件与目标集群通信，并将目标集群连接至注册集群。

      onectl cluster connect --cluster-id **** --kubeconfig ~/.kube/config

    2. KUBECONFIG环境变量

      若上述kubeconfig参数未指定，onectl会使用KUBECONFIG环境变量指向的KubeConfig配置文件。

    3. onectl配置文件~/.onectl/config.json中的Kubeconfig Path字段

      若以上两个字段都不存在，则使用该字段指向的配置文件。该字段的配置请参见步骤二：配置onectl RAM用户。

    4. ~/.kube/config

      若上述字段均为空，则默认使用该配置文件。

    连接注册集群

    onectl连接注册集群时，将依次执行以下操作。

    1. 获取注册集群的连接信息，并保存到本地名为agent.yaml的文件中。

    2. 根据此YAML文件的内容，在目标集群中部署注册集群agent。

    例如，执行以下命令，连接注册集群与目标集群。

    onectl cluster connect --cluster-id ****

    预期输出：

    Agent information saved as agent.yaml.
Installing ACK One agent using kubeconfig file **** to connect to registered cluster ****.
Confirm? [Y/n]: y
ACK One agent deployed successfully.
Check the running status of deployment ack-cluster-agent to confirm the connection status of registered cluster ****.

    组件RAM用户

    注册集群中已安装的组件在运行时，需要一个单独的RAM用户的AccessKey来访问云上资源。例如，logtail-ds组件需要访问日志服务SLS的项目、日志库等资源，该组件RAM用户的AK信息保存在集群kube-system命名空间下名为alibaba-addon-secret的Secret中。

    • 若集群中已经存在此Secret，onectl会沿用此Secret中的AK信息来运行集群组件。

    • 若集群中不存在此Secret，onectl会自动创建并使用名为ack-one-user-[cluster id prefix]的RAM用户来运行组件。例如，当集群中不存在此Secret时，您可以执行以下命令，创建一个RAM用户并授予其terway-eniip组件所需要的权限。

      onectl ram-user grant --addon terway-eniip

      预期输出：

      Ram user ack-one-user-ce313528c3 created successfully.
Ram policy ack-one-registered-cluster-policy-terway-eniip granted to ram user ack-one-user-ce313528c3 successfully.
Secret alibaba-addon-secret created under namespace kube-system in the cluster, it stores the access key and secret of ram user ack-one-user-ce313528c3.

    组件安装

    通过onectl安装组件需要管理员权限，onectl会在开始安装前检测注册集群agent的ServiceAccount是否拥有管理员权限。若没有，onectl将创建一个临时的管理员角色，并赋予ack账户集群的管理员权限。组件安装完成后，onectl将删除此临时管理员角色，将ack账户的权限恢复至组件安装前。

    例如，在agent没有管理员权限时，您可以执行以下命令对agent账户进行临时提权，并在组件安装完成后撤销agent的临时管理员权限。

    onectl addon install logtail-ds

    预期输出：

    Cluster role ack-admin-tmp created.
Cluster role binding ack-admin-binding-tmp created.
Addon logtail-ds, version **** installed.
Cluster role ack-admin-tmp deleted.
Cluster role binding ack-admin-binding-tmp deleted.

    临时管理员角色的ClusterRole、ClusterRoleBinding内容如下。

    展开查看临时管理员角色的ClusterRole、ClusterRoleBinding

    apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ack-admin-tmp
  labels:
    ack/creator: "ack"
rules:
- apiGroups:
  - '*'
  resources:
  - '*'
  verbs:
  - '*'
- nonResourceURLs:
  - '*'
  verbs:
  - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ack-admin-binding-tmp
  namespace: kube-system
  labels:
    ack/creator: "ack"
subjects:
- kind: ServiceAccount
  name: ack
  namespace: kube-system
roleRef:
  kind: ClusterRole
  name: ack-admin-tmp
  apiGroup: rbac.authorization.k8s.io

    步骤一：安装onectl

    1. 执行以下命令，安装onectl。

      支持macOS和Linux系统安装。

      curl https://ack-one.oss-cn-hangzhou.aliyuncs.com/onectl/get-onectl.sh | bash

    2. 执行以下命令，验证onectl是否安装成功。

      onectl version

      预期输出：

      onectl: v1.0.0+774dea0
	BuildDate: 2023-07-12T06:10:27Z
	GitCommit: 774dea0f768569821e101dc44d1cb09cef192fe8
	GitTreeState: clean
	GoVersion: go1.20.4
	Compiler: gc
	Platform: darwin/amd64

    步骤二：配置onectl RAM用户

    RAM用户登录后，才能通过onectl管理注册集群，onectl会使用该RAM用户的AK/SK来操作阿里云的云服务资源，该RAM用户需要拥有以下权限来管理云上资源。

    说明

    onectl RAM用户与组件的RAM用户是不同的RAM用户。

    • 容器服务的管理员权限：名为AliyunCSFullAccess的系统策略。

    • RAM的管理员权限：名为AliyunRamFullAccess的系统策略。

    • VPC的只读权限：名为AliyunVPCReadOnlyAccess的系统策略。

    您可以执行以下命令，配置onectl RAM用户的AK、SK信息以及注册集群ID等信息。

    onectl configure

    预期输出：

    Configuring profile default ...
Access Key Id [*********************f7x]:
Access Key Secret [***************************mft]:
Default Kubeconfig Path (default is ~/.kube/config) []:
Saving profile[default] ...
Done.

    参数

    说明

    Access Key Id

    onectl使用的RAM用户的AccessKey信息。

    Access Key Secret

    Kubeconfig Path

    IDC自建集群的KubeConfig路径，默认为~/.kube/config。

    步骤三：配置目标集群KubeConfig

    onectl默认会使用KubeConfig环境变量指向的KubeConfig配置文件用于连接目标集群，因此使用onectl之前，需要先设置该环境变量。若未设置，将默认使用~/.kube/config文件。

    相关操作

    集群管理

    您可以通过执行以下onectl命令，对集群进行操作。

    • 创建连接注册集群。其中cluster-id ****为您创建的注册集群的ID。更多信息，请参见通过onectl创建注册集群。

      onectl cluster create --region **** --vpc **** --vswitch **** --name **** --eip true
onectl cluster connect --cluster-id ****

    • 查看注册集群的当前状态。

      onectl cluster describe --cluster-id ****

    • 查看所有注册集群。

      onectl cluster list

    • 删除注册集群。

      onectl cluster delete --cluster-id ****

    组件管理

    您可以通过执行以下onectl命令，对组件进行不同的操作。其中****为您待操作的组件的名称。

    • 安装组件

      onectl addon install ****

    • 升级组件

      onectl addon upgrade ****

    • 查询组件列表

      onectl addon list

    • 查看所有可安装组件

      onectl addon catalog

    • 卸载组件

      onectl addon uninstall ****

    组件RAM用户管理

    您可以通过执行以下onectl命令，对组件RAM用户进行管理。其中****为组件的名称。

    • 授予权限

      onectl ram-user grant --addon ****

    • 列出权限详情

      onectl ram-user describe --detail

    • 撤销权限

      onectl ram-user revoke --addon ****

    • 更新权限

      onectl ram-user update --addon ****

    相关文档

    • 如果需要查看已安装的组件，请参见组件。

    • 如果需要监控注册集群的工作状态，请参见可观测性。

    • 如果需要了解注册集群的安全性要求，请参见安全管理。