All Products
Search
Document Center

Container Service for Kubernetes:Use onectl to manage registered clusters

更新時間:Apr 23, 2024

onectl is a command-line tool provided by Distributed Cloud Container Platform for Kubernetes (ACK One) for registered clusters. You can use onectl to manage registered clusters, cluster components, and Resource Access Management (RAM) users.

Introduction to onectl

onectl provides the following features.

  • Manage clusters

    You can use onectl to create and delete registered clusters, query the status of registered clusters, query all registered clusters managed by the current RAM user, and connect external clusters to registered clusters.

  • Manage components

    You can use onectl to install components, update components, query all components that are installed and can be installed, and delete components.

  • Manage the RAM user for a cluster component

    You can use onectl to grant permissions to a Resource Access Management (RAM) user on a component, revoke permissions from a RAM user on a component, and query the permissions that are granted to a RAM user on a component.

How onectl works

Click to view how onectl works

Communicate with the external cluster

When you use onectl to connect a registered cluster to an external cluster, onectl deploys a registered cluster agent in the external cluster. Then, onectl attempts to use the corresponding kubeconfig file to communicate with the external cluster by using the following methods in sequence:

  1. The kubeconfig parameter

    For example, onectl runs the following command to use the ~/.kube/config file to communicate with the external cluster and connects the external cluster to the registered cluster:

    onectl cluster connect --cluster-id **** --kubeconfig ~/.kube/config
  2. The KUBECONFIG environment variable

    If no kubeconfig file is specified in the preceding command, onectl uses the kubeconfig file specified in the KUBECONFIG environment variable.

  3. The Kubeconfig Path parameter in the ~/.onectl/config.json file

    If the kubeconfig parameter and KUBECONFIG environment variable are not configured, onectl uses the kubeconfig file specified in the Kubeconfig Path parameter. For more information about this parameter, see Step 2: Grant permissions to the RAM user for onectl.

  4. ~/.kube/config

    If none of the preceding parameters is configured, onectl uses the ~/.kube/config file.

Connect to the registered cluster

onectl performs the following steps when connecting to the registered cluster:

  1. Obtains the connection information of the registered cluster and saves the information to a local file named agent.yaml.

  2. Deploys a registered cluster agent in the external cluster based on the connection information.

For example, onectl runs the following command to connect the registered cluster and external cluster:

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

Expected output:

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 users for cluster components

Components that run in a registered cluster need to use the AccessKey pair of a RAM user to access resources in the cloud. For example, the logtail-ds component needs to access Simple Log Service resources such as projects and Logstores. The AccessKey pair of the RAM user for the logtail-ds component is stored in the Secret named alibaba-addon-secret in the kube-system namespace of the cluster.

  • If the Secret already exists in the cluster, onectl uses the AccessKey pair in the Secret to run cluster components.

  • If the Secret does not exist, onectl automatically creates a RAM user named ack-one-user-[cluster id prefix] to run cluster components. For example, if the Secret does not exist, you can run the following command to create a RAM user and grant the permissions required by the terway-eniip component to the RAM user.

    onectl ram-user grant --addon terway-eniip

    Expected output:

    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.

Install cluster components

You need administrator permissions if you use onectl to install cluster components. onectl will check whether the service account of the registered cluster agent has administrator permissions before installing the component. If the service account does not have permissions, onectl automatically creates a temporary admin role, grants administrator permissions to the role, and assigns to the role to the service account. After the component is installed, onectl automatically deletes the temporary admin role to revoke permissions from the service account.

For example, if the registered cluster agent does not have administrator permissions, you can run the following command to grant temporary permissions to the service account of the agent, and then revoke the permissions after the component is installed:

onectl addon install logtail-ds

Expected output:

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.

The following code block shows the ClusterRole and ClusterRoleBinding of the temporary admin role:

Click to view the ClusterRole and ClusterRoleBinding of the temporary admin role

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

Step 1: Install onectl

  1. Run the following command to install onectl:

    onectl supports macOS and Linux.

    curl https://ack-one.oss-cn-hangzhou.aliyuncs.com/onectl/get-onectl.sh | bash
  2. Run the following command to check whether onectl is installed:

    onectl version

    Expected output:

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

Step 2: Grant permissions to the RAM user for onectl

You can use onectl to manage registered clusters only after you log on as a RAM user. onectl uses the AccessKey pair of the RAM user to access Alibaba Cloud services. Therefore, the RAM user must have the following permissions on cloud resources.

Note

The RAM user for onectl and the RAM users for cluster components are different.

  • ACK administrator permissions provided by the AliyunCSFullAccess system policy.

  • RAM administrator permissions provided by the AliyunRamFullAccess system policy.

  • VPC read-only permissions provided by the AliyunVPCReadOnlyAccess system policy.

You can run the following command to specify the AccessKey pair of the RAM user for onectl and the ID of the registered cluster:

onectl configure

Expected output:

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

Parameter

Description

Access Key Id

The AccessKey pair of the RAM user for onectl.

Access Key Secret

Kubeconfig Path

The path of the kubeconfig file that is used to log on to the external cluster. Default value: ~/.kube/config.

Step 3: Configure the kubeconfig file to connect to an external cluster

By default, onectl uses the kubeconfig file specified in the KUBECONFIG environment variable to connect to an external cluster. You need to set the KUBECONFIG environment variable before you use onectl. If the KUBECONFIG environment variable is not set, the ~/.kube/config file is used by default.

What to do next

Manage clusters

You can use onectl to perform the following operations:

  • Create and connect to a registered cluster. cluster-id **** indicates the ID of the registered cluster. For more information, see Use onectl to create a registered cluster.

    onectl cluster create --region **** --vpc **** --vswitch **** --name **** --eip true
    onectl cluster connect --cluster-id ****
  • Query the status of a registered cluster.

    onectl cluster describe --cluster-id ****
  • Query all registered clusters.

    onectl cluster list
  • Delete a registered cluster.

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

Manage components

You can use onectl to perform the following operations: **** indicates the name of the component that you want to manage.

  • Install a component.

    onectl addon install ****
  • Update a component.

    onectl addon upgrade ****
  • Query components.

    onectl addon list
  • Query all components that can be installed.

    onectl addon catalog
  • Uninstall a component.

    onectl addon uninstall ****

Manage the RAM user for a cluster component

You can use onectl to perform the following operations: **** indicates the name of the component.

  • Grant permissions to the RAM user.

    onectl ram-user grant --addon ****
  • Query the permissions of the RAM user.

    onectl ram-user describe --detail
  • Revoke permissions from the RAM user.

    onectl ram-user revoke --addon ****
  • Update the permissions of the RAM user.

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

References

  • For more information about how to query the installed components, see Manage components.

  • For more information about how to monitor the status of registered clusters, see Observability.

  • For more information about the security requirements on registered clusters, see Security management.