A guide to the management commands of VNodectl - Elastic Container Instance - Alibaba Cloud - Elastic Container Instance

VNodectl manages VNodes, add-ons, and other resources from the command line. The following sections describe the syntax, parameters, and examples of the most commonly used VNodectl commands.

Prerequisites

VNodectl — Install and configure the VNodectl command-line tool before you run any of the commands in this topic.
VNode configuration file — Before you run a VNode command (create, list, describe, update, or delete), make sure that the ~/.vnode/config file exists and is configured correctly.
Cluster kubeconfig file — A kubeconfig file for the cluster you want to manage. The add-on commands and the cluster clean command take the path to the kubeconfig file in the --kubeconfig option.

Command overview

VNodectl commands are grouped by the resource that they act on.

VNode commands

Command	Description
`vnode create`	Creates a VNode.
`vnode list`	Queries the status of VNodes.
`vnode describe`	Shows the details of a specific VNode.
`vnode update`	Updates the configuration of a specified VNode.
`vnode delete`	Deletes a specified VNode.

Add-on and cluster commands

Command	Description
`vnode addon list`	Lists the available add-ons.
`vnode addon enable`	Installs and enables an add-on.
`vnode addon disable`	Disables and uninstalls an add-on.
`vnode cluster clean`	Cleans up cluster configurations.

Add --dry to any vnode command to run a client-side validation without applying changes. If an API version compatibility error occurs, add --kubernetes-version to specify your cluster's Kubernetes version.

Manage VNodes

create

The create command creates a VNode.

Syntax

vnode create [--vswitch-id <vswitch id>] [--security-group-id <security group id>] [--custom-resources <resource name>=<resource count>] [--cluster-dns <dns ip>] [--cluster-domain <cluster domain>]

Parameters

Parameter	Description	Example
`--vswitch-id`	The ID of the vSwitch to which the VNode belongs.	`--vswitch-id vsw-7xv2yk45qp5etidgf****`
`--security-group-id`	The ID of the security group to which the VNode belongs.	`--security-group-id sg-7xv5tcch4kjdr65t****`
`--custom-resources`	The custom resources that the VNode supports. If an Elastic Container Instance (ECI) pod declares one of these custom resources in its `requests`, the pod is scheduled to the VNode. Specify resources in the `<resource name>=<resource count>` format and separate multiple resources with commas.	`--custom-resources example1.com=10000,example2.com=20000`
`--cluster-dns`	The IP addresses of the DNS servers. If an ECI pod sets `dnsPolicy=ClusterFirst`, the containers in the pod use these IP addresses for DNS resolution. Specify multiple IP addresses separated by commas.	`--cluster-dns 192.168.XX.XX`
`--cluster-domain`	The domain name of the cluster. After you specify this parameter, Kubelet configures all containers to search this domain in addition to the search domains of the host.	`--cluster-domain example.com`

Example 1: Create a VNode without parameters

[root@vnode-test001 ~]# vnode create
{"RequestId":"12B984BB-D3FB-53D2-8326-9A2E9EF7EF46","VirtualNodeId":"vnd-7xv6g0gp3ok6****"}

Example 2: Create a VNode that supports custom resources

[root@vnode-test001 ~]# vnode create --custom-resources example1.com=10000,example2.com=20000
{"RequestId":"98965B78-4F19-5DA4-BAAA-E6461BF7FF67","VirtualNodeId":"vnd-7xv1zedhxp****"}

After the VNode is created, run the kubectl describe node command to view the node details. The specified custom resources appear in the Capacity and Allocatable sections.

Capacity:
  alibabacloud.com/vfuse:  6k
  cpu:                     100k
  ephemeral-storage:       40000Gi
  example1.com:            10k
  example2.com:            20k
  memory:                  1000Ti
  nvidia.com/gpu:          1k
  pods:                    2k
Allocatable:
  alibabacloud.com/vfuse:  6k
  cpu:                     100k
  ephemeral-storage:       40000Gi
  example1.com:            10k
  example2.com:            20k
  memory:                  1000Ti
  nvidia.com/gpu:          1k
  pods:                    2k

Example 3: Create a VNode with DNS servers and a cluster domain

[root@vnode-test001 ~]# vnode create --cluster-dns 192.168.0.1 --cluster-domain example.com
{"RequestId":"1FCB1308-7C96-5FF2-A7BB-202F69D1961C","VirtualNodeId":"vnd-7xv4qqroc5f****"}

After the VNode is created, run the kubectl describe pod command to view the details of an ECI pod that is scheduled to the VNode. The specified values appear as the k8s.aliyun.com/cluster-dns and k8s.aliyun.com/cluster-domain annotations.

[root@vnode-test001 ~]# kubectl describe pod test-5748b8cfb6-xgmp7
Name:         test-5748b8cfb6-xgmp7
Namespace:    default
Priority:     0
Node:         cn-guangzhou.vnd-7xv4qqroc5f****/192.168.XX.XX
Start Time:   Mon, 27 Mar 2023 17:27:06 +0800
Labels:       alibabacloud.com/eci=true
              app=nginx
              pod-template-hash=5748b8cfb6
Annotations:  k8s.aliyun.com/cluster-dns: 192.168.0.1
              k8s.aliyun.com/cluster-domain: example.com
              k8s.aliyun.com/eci-created-by-template: true
              k8s.aliyun.com/eci-extra-ephemeral-storage: 62Gi
              k8s.aliyun.com/eci-instance-cpu: 2.0
              k8s.aliyun.com/eci-instance-id: eci-7xv4qqroc****
              k8s.aliyun.com/eci-instance-mem: 4.0
              k8s.aliyun.com/eci-instance-spec: 2.0-4.0Gi
              k8s.aliyun.com/eci-instance-zone: cn-guangzhou-a
              k8s.aliyun.com/eci-matched-image-cache: imc-7xv80t0k3g****

list

The list command queries the status of VNodes.

Syntax

vnode list

Example

[root@vnode-test001 ~]# vnode list
VNODE ID                VNODE NAME                                  CREATED              STATUS    SCHEDULABLE ZONES
vnd-7xv6g0gp3ok****     vnode-cn-guangzhou-a-7xv6g0****             About a minute ago   Ready     cn-guangzhou-a
vnd-7xvetkyase7****     vnode-cn-guangzhou-a-7xvetk****             49 minutes ago       Ready     cn-guangzhou-a
[root@vnode-test001 ~]#

describe

The describe command shows the details of a specific VNode.

Syntax

vnode describe <vnode id>

Example

[root@vnode-test001 ~]# vnode describe vnd-7xv6g0gp3ok69****
VNodeId: vnd-7xv6g0gp3ok69****
VNodeName: vnode-cn-guangzhou-a-7xv6g0gp3****
ClusterId:
RegionId: cn-guangzhou
ResourceGroupId: rg-acfm4ia6****
SecurityGroupId: sg-7xv5tcch****
VpcId: vpc-7xvuaoizvudf366bh****
VSwitchId: vsw-7xv4hi6ioxpw3****
Status: Ready
CreationTime: 2022-12-23T06:44:52Z
IntranetIp: 192.168.XX.54
InternetIp:
Cpu:
Memeory:
Tags: []
Events:
  Type        Reason                          Agent            Message
  -----       -----                           -----            -----
  Normal      StartingHeartBeat               2 minutes ago    birth cry
  Warning     HeartBeatToECIServiceFailed     2 minutes ago    fail to connect eci-service
  Normal      CreateEciForVnode               2 minutes ago    [eci.virtualnode]Create Eci eci-7xv6g0gp3**** for Vnode
  Normal      StartingVKubelet                2 minutes ago    Starting VKubelet.

update

The update command updates the configuration of a specified VNode. The values of the --vswitch-id, --security-group-id, --custom-resources, --cluster-dns, and --cluster-domain options can be updated.

Important

The update command overwrites the entire configuration. The parameter values you pass in replace the existing values. For example, if the VNode is already configured with --custom-resources example1.com=10000 and you want to add the custom resource example2.com with a count of 10000, pass in --custom-resources example1.com=10000,example2.com=10000.

Syntax

vnode update <vnode id> [--vswitch-id <vswitch id>] [--security-group-id <security group id>] [--custom-resources <resource name>=<resource count>] [--cluster-dns <dns ip>] [--cluster-domain <cluster domain>]

Parameters

The update command takes the same options as the create command. For option descriptions, see the parameter table in create.

Parameter	Description	Example
`--vswitch-id`	The ID of the vSwitch to which the VNode belongs.	`--vswitch-id vsw-7xv2yk45qp5etidgf****`
`--security-group-id`	The ID of the security group to which the VNode belongs.	`--security-group-id sg-7xv5tcch4kjdr65t****`
`--custom-resources`	The custom resources that the VNode supports. If an Elastic Container Instance (ECI) pod declares one of these custom resources in its `requests`, the pod is scheduled to the VNode. Specify resources in the `<resource name>=<resource count>` format and separate multiple resources with commas.	`--custom-resources example1.com=10000,example2.com=20000`
`--cluster-dns`	The IP addresses of the DNS servers. If an ECI pod sets `dnsPolicy=ClusterFirst`, the containers in the pod use these IP addresses for DNS resolution. Specify multiple IP addresses separated by commas.	`--cluster-dns 192.168.XX.XX`
`--cluster-domain`	The domain name of the cluster. After you specify this parameter, Kubelet configures all containers to search this domain in addition to the search domains of the host.	`--cluster-domain example.com`

Example

[root@vnode-test001 ~]# vnode update vnd-7xv1zedhxp**** --cluster-domain example.com
{"RequestId":"DA86B896-3A05-5A0C-A9D2-A1D433C85035"}

To review the configuration of the VNode after the update, run the vnode describe command.

delete

The delete command deletes a specified VNode.

Important

Before you delete a VNode, make sure that no ECI instances are running on the VNode.

Syntax

vnode delete <vnode id>

Example

[root@vnode-test001 ~]# vnode delete vnd-7xv6g0gp3ol****
are you sure to delete vnd-7xv6g0gp3ol**** ?(y/n)y
{"RequestId":"7B7E8276-772A-5229-B2D7-B3DD36A66432"}

To check the state of your VNodes after the deletion, run the vnode list command.

Manage add-ons and cluster configurations

In addition to VNodes, VNodectl manages cluster add-ons, such as eci-profile and vnode-approver, and cleans up cluster configurations. In the commands in this section, the --kubeconfig option takes the path to the kubeconfig file of the target cluster.

addon list

The addon list command lists the available add-ons.

Syntax

vnode addon list --kubeconfig <kubeconfig path>

Example

[root@vnode-test001 ~]# vnode addon list --kubeconfig ~/.kube/config
  ADDON NAME     |   STATUS   |  MAINTAINER  |                  REPOSITORY
-----------------+------------+--------------+------------------------------------------------------
  eci-profile    | enabled    | ECI Group    | https://github.com/aliyuneci/eci-profile.git
  vnode-approver | disabled   | ECI Group    | https://github.com/aliyuneci/vnode-approver.git

addon enable

The addon enable command installs and enables an add-on. The command creates the resources that the add-on requires in the cluster, such as a ClusterRole, a CustomResourceDefinition, a Service, and a Deployment.

Syntax

vnode addon enable <add-on name> --kubeconfig <kubeconfig path>

Example

The following example enables the eci-profile add-on and then lists the add-ons to confirm the new status:

[root@vnode-test001 ~]# vnode addon list
  ADDON NAME     |   STATUS   |  MAINTAINER  |                  REPOSITORY
-----------------+------------+--------------+------------------------------------------------------
  eci-profile    | disabled   | ECI Group    | https://github.com/aliyuneci/eci-profile.git
  vnode-approver | disabled   | ECI Group    | https://github.com/aliyuneci/vnode-approver.git
[root@vnode-test001 ~]# vnode addon enable eci-profile --kubeconfig ~/.kube/config
clusterrole.rbac.authorization.k8s.io/eci-profile created
clusterrolebinding.rbac.authorization.k8s.io/eci-profile created
customresourcedefinition.apiextensions.k8s.io/selectors.eci.aliyun.com created
service/eci-profile created
serviceaccount/eci-profile created
deployment.apps/eci-profile created
[root@vnode-test001 ~]# vnode addon list
  ADDON NAME     |   STATUS   |  MAINTAINER  |                  REPOSITORY
-----------------+------------+--------------+------------------------------------------------------
  eci-profile    | enabled    | ECI Group    | https://github.com/aliyuneci/eci-profile.git
  vnode-approver | disabled   | ECI Group    | https://github.com/aliyuneci/vnode-approver.git

addon disable

The addon disable command disables and uninstalls an add-on. The command deletes the resources created for the add-on in the cluster.

Syntax

vnode addon disable <add-on name> --kubeconfig <kubeconfig path>

Example

The following example disables the eci-profile add-on and then lists the add-ons to confirm the new status:

[root@vnode-test001 ~]# vnode addon list
  ADDON NAME     |   STATUS   |  MAINTAINER  |                  REPOSITORY
-----------------+------------+--------------+------------------------------------------------------
  eci-profile    | enabled    | ECI Group    | https://github.com/aliyuneci/eci-profile.git
  vnode-approver | disabled   | ECI Group    | https://github.com/aliyuneci/vnode-approver.git
[root@vnode-test001 ~]# vnode addon disable eci-profile --kubeconfig ~/.kube/config
clusterrole.rbac.authorization.k8s.io "eci-profile" deleted
clusterrolebinding.rbac.authorization.k8s.io "eci-profile" deleted
customresourcedefinition.apiextensions.k8s.io "selectors.eci.aliyun.com" deleted
Error from server (NotFound): error when deleting "/root/.vnode/addon/eci-profile/eci-profile-cus...
service "eci-profile" deleted
serviceaccount "eci-profile" deleted
deployment.apps "eci-profile" deleted
[root@vnode-test001 ~]# vnode addon list
  ADDON NAME     |   STATUS   |  MAINTAINER  |                  REPOSITORY
-----------------+------------+--------------+------------------------------------------------------
  eci-profile    | disabled   | ECI Group    | https://github.com/aliyuneci/eci-profile.git
  vnode-approver | disabled   | ECI Group    | https://github.com/aliyuneci/vnode-approver.git

cluster clean

The cluster clean command cleans up cluster configurations.

Important

Run the cluster cleancommand if you no longer use VNodes.

Syntax

vnode cluster clean --kubeconfig <kubeconfig path> [--bootstrap]

Which option to use depends on how the cluster was previously configured.

Example 1: Clean up a cluster that was configured by using the standard method

vnode cluster clean --kubeconfig <kubeconfig path>

Example 2: Clean up a cluster that was configured by using the TLS bootstrap method

vnode cluster clean --kubeconfig <kubeconfig path> --bootstrap