Container Service for Kubernetes:Manage registered clusters with onectl

Communicating with the external cluster

onectl deploys an ACK One agent in the external cluster and resolves the kubeconfig from the following sources, in order:

1. The --kubeconfig parameter. 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

onectl cluster connect performs two steps:

1. Retrieves the registered cluster connection information and saves it to agent.yaml.

2. Deploys the ACK One agent in the external cluster using that information.

RAM users for cluster components

Components in a registered cluster use a RAM user's AccessKey pair to access Alibaba Cloud resources. For example, logtail-ds requires access to Simple Log Service (SLS) 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 exists, onectl uses the AccessKey pair in it.

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

Installing cluster add-ons

Installing a component requires admin permissions on the registered cluster. onectl checks whether the ACK One agent's service account has these permissions:

• If it does, onectl installs the component directly.

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

Temporary ClusterRole and ClusterRoleBinding 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 your registered cluster ID and <region-id>, <vpc-id>, <vswitch-id>, and <cluster-name> with your environment values.

• Create a registered cluster and connect an external cluster. 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 ****.

• Check 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 component name.

• Install a component. If the ACK One agent lacks admin permissions, onectl temporarily grants and then revokes them.

  onectl addon install <component-name>

  Example output with temporary permissions:

  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 available components:

  onectl addon catalog

• Uninstall a component:

  onectl addon uninstall <component-name>

Manage RAM users for components

Some components require specific RAM permissions to access Alibaba Cloud resources. Grant permissions before installing these components.

Replace <component-name> with the component name.

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

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

  Example output with a new RAM user:

  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.

• Check RAM user permissions:

  onectl ram-user describe --detail

• Update RAM user permissions:

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

• Revoke RAM user permissions:

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