通过onectl管理注册集群

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 ****

相关文档

  • 如果需要查看已安装的组件,请参见管理组件

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

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