Container Service for Kubernetes:Use onectl to manage registered clusters

Communicating with the external cluster

When you connect a registered cluster to an external cluster, onectl deploys an ACK One agent in the external cluster. onectl then communicates with the external cluster using the following kubeconfig sources, in order:

1. The --kubeconfig parameter passed directly in the command. For example:

   onectl cluster connect --cluster-id <cluster-id> --kubeconfig ~/.kube/config

2. The KUBECONFIG environment variable.

3. The Kubeconfig Path parameter in ~/.onectl/config.json (configured via onectl configure).

4. ~/.kube/config as the default fallback.

Connecting to a registered cluster

When you run onectl cluster connect, onectl performs two steps:

1. Retrieves the connection information for the registered cluster and saves it to a local file named agent.yaml.

2. Deploys the ACK One agent in the external cluster based on that connection information.

RAM users for cluster components

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

• If the Secret already exists, onectl uses the AccessKey pair stored in it.

• If the Secret does not exist, onectl automatically creates a RAM user named ack-one-user-<cluster-id-prefix> and stores the new AccessKey pair in the Secret.

Installing cluster components

Installing a component requires administrator permissions on the registered cluster. onectl checks whether the service account of the ACK One agent has admin permissions before proceeding:

• If it does, onectl installs the component directly.

• If it does not, onectl automatically creates a temporary ClusterRole (ack-admin-tmp) and ClusterRoleBinding (ack-admin-binding-tmp), grants admin permissions to the service account, installs the component, and then deletes the temporary role and binding.

The temporary ClusterRole and ClusterRoleBinding use the following definitions:

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

Manage clusters

Replace <cluster-id> with the ID of your registered cluster and <region-id>, <vpc-id>, <vswitch-id>, and <cluster-name> with your environment-specific values.

• Create a registered cluster and connect an external cluster to it. For more information, see Use onectl to create a registered cluster.

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

  Expected output for cluster connect:

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

• Query the status of a registered cluster:

  onectl cluster describe --cluster-id <cluster-id>

• List all registered clusters:

  onectl cluster list

• Delete a registered cluster:

  onectl cluster delete --cluster-id <cluster-id>

Manage components

Replace <component-name> with the name of the component.

• Install a component. If the ACK One agent does not have admin permissions, onectl grants temporary permissions automatically and removes them after installation.

  onectl addon install <component-name>

  Example output when temporary permissions are granted:

  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.

• Upgrade a component:

  onectl addon upgrade <component-name>

• List installed components:

  onectl addon list

• List all installable components:

  onectl addon catalog

• Uninstall a component:

  onectl addon uninstall <component-name>

Manage RAM users for components

Some components need a RAM user with specific permissions to access Alibaba Cloud resources. Grant permissions before installing a component that requires them.

Replace <component-name> with the name of the component.

• Grant permissions to the RAM user for a component. If the Secret alibaba-addon-secret does not exist in the cluster, onectl creates a new RAM user and Secret automatically.

  onectl ram-user grant --addon <component-name>

  Example output when a new RAM user is created:

  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.

• Query the permissions of the RAM user:

  onectl ram-user describe --detail

• Update the permissions of the RAM user:

  onectl ram-user update --addon <component-name>

• Revoke permissions from the RAM user:

  onectl ram-user revoke --addon <component-name>