If you created self-managed Kubernetes clusters in a data center or on an Alibaba Cloud Elastic Compute Service (ECS) instance and you want to use elastic container instances in the self-managed Kubernetes clusters, you must deploy VNodes. Elastic Container Instance provides the VNodectl CLI to deploy and manage VNodes. This topic describes how to use VNodectl to automatically deploy a VNode in a Kubernetes cluster.
Prerequisites
A Kubernetes cluster of version 1.13 to 1.30 is deployed.
If your Kubernetes cluster is deployed in a data center, make sure that the data center and the virtual private cloud (VPC) to which the Elastic Container Instance-based pods belong are connected with each other by using Express Connect, Smart Access Gateway, or VPN Gateway. For more information, see the following topics:
Preparations
Before you deploy a VNode in a self-managed Kubernetes cluster, prepare the parameter information that is required for creating a VNode and understand the permissions that are required to deploy the VNode in the cluster. The following table describes the parameters that are required to create a VNode.
Parameter | Description | Operation |
Region | A region is a geographic location where Alibaba Cloud data centers are deployed. Select a region based on the geographical location of your end users and resource prices. For more information, see Regions and Zones. The elastic container instance and relevant resources are created in the region that you selected. | You can query the regions where Elastic Container Instance is available by using the Elastic Container Instance console or by calling the DescribeRegions API operation. |
VPC | A VPC is a private network established on Alibaba Cloud. VPCs are logically isolated from each other. For more information, see What is a VPC? The elastic container instance and relevant resources are created in the VPC that you configured. Note If your Kubernetes cluster is deployed in a data center, make sure that the network of the data center and the VPC is established. | You can create and view VPCs on the VPCs page in the VPC console. |
vSwitch | A vSwitch is a basic network device that connects different cloud resources. If you want to create an elastic container instance and relevant resources in a VPC, you must specify a vSwitch. You can also specify multiple vSwitches. In this case, the system automatically selects a vSwitch from the pool of vSwitches. | You can create and view vSwitches on the vSwitch page in the VPC console and select a vSwitch in the VPC that you selected. |
Security Group | Security groups are virtual firewalls that control the inbound and outbound traffic of resources in the group to improve network security. For more information about security groups, see Overview. The elastic container instance and relevant resources are added to the security group that you selected. Note We recommend that you select an advanced security group and add the following inbound security group rules:
| You can create and view security groups on the Security Groups page in the ECS console and select a security group in the VPC that you selected. |
To create a VNode, you must configure standard permissions for native Kubernetes nodes and additional permissions for the VNode, as shown in the following table.
Type | Permission | Description |
Standard permissions | system:node | Standard permissions for nodes. |
system:node-proxier | Standard permissions for kube-proxy. | |
system:certificates.k8s.io:certificatesigningrequests:nodeclient | The permission for nodes to initiate the request to create a certificate. | |
system:certificates.k8s.io:certificatesigningrequests:selfnodeclient | The permission for nodes to initiate a request to create a certificate based on existing certificates. The permission is to request for certificate rotation. | |
Additional permissions | pods update and pods patch | The permissions for updating annotations of pods. For example, you can add computed annotations such as |
pvc update and pvc patch | The permissions for updating annotations of PersistentVolumeClaims (PVCs). | |
endpoints create and endpoints update | Leader election assurance. You do not need to configure these permissions for clusters of later than v1.13. |
Install VNodectl
Before you use VNodectl to deploy a VNode in a self-managed Kubernetes cluster, you must install VNodectl. Obtain the installation package based on your cluster environment and install VNodectl.
Operating system | CPU architecture | Hyperlink of the installation package |
macOS | AMD64 | |
ARM64 | ||
Linux | AMD64 | |
ARM64 | ||
Windows | AMD64 | |
ARM64 |
We recommend that you install VNodectl on the master node of your Kubernetes cluster. To install VNodectl, perform the following operations:
Connect to your Kubernetes cluster.
Download the installation package of VNodectl.
wget https://eci-docs.oss-cn-beijing.aliyuncs.com/vnode/vnodectl_0.0.5-beta_linux_amd64.tar.gz -O vnodectl.tar.gz
Extract the downloaded package files of VNodectl.
tar xvf vnodectl.tar.gz
Copy the extracted package files to a specified directory.
cp vnodectl /usr/local/bin/vnode
You can add
--dry
to vnode commands for client verification.If an API version compatibility error occurs when you run a vnode command, add
--kubernetes-version
to specify the Kubernetes version of the cluster.
Configure the cluster
Before you create a VNode, you must generate a kubeconfig certificate for the VNode. Then, you can use the kubeconfig to deploy the VNode in your self-managed Kubernetes cluster. You can generate the kubeconfig in TLS Bootstrap mode or ServiceAccount mode.
If you have security requirements, we recommend that you use the TLS bootstrapping mode. In this mode, the vnode-approver component is automatically deployed. The vnode-approver component is used to approve certificate signing requests (CSRs) that are sent by VNodes. vnode-approver has open source code on GitHub. For more information, see vnode-approver.
The ServiceAccount mode does not support certificate rotation. When you generate a kubeconfig certificate, make sure that the token has a long enough or permanent validity period to prevent VNode failure due to expiration of the kubeconfig.
TLS Bootstrap
Generate a kubeconfig certificate.
Prepare the information that is required to configure the cluster.
Parameter
Description
Operation
Example
kubeconfig
This parameter is used to configure the permissions that are required to deploy the VNode in the cluster.
Obtain the kubeconfig certificate from the default path
~/.kube/config
. You can also obtain a kubeconfig certificate from another path./path/to/kubeconfig
Cluster CA
This parameter is used to generate the kubeconfig certificate that is required to deploy the VNode in the cluster. You can use the certificate authority (CA) in the kubeconfig that has the admin permissions. We recommend that you use the CA that is specified when you start the API server.
Run the
ps aux | grep apiserver
command and obtain the value of--client-ca-file
from the command output./path/to/ca.crt
Connection String of API Server
This parameter is used for communication, validation, and authentication of the cluster.
Execute the kubeconfig and obtain the connection string of the API server from the output.
https://8.134.XX.XX:6443
tokenId
This parameter is used to generate a TLS bootstrap token and create a bootstrap token secret.
Specify a value. The value must be an alphanumeric string of six characters.
eci123
tokenSecret
Specify a value. The value must be an alphanumeric string of 16 characters.
eci1233333333333
Deploy the vnode-approver component.
vnode addon enable vnode-approver
Configure the cluster to generate the kubeconfig certificate.
Specify actual cluster information for the parameters in the command. Sample command:
vnode cluster setup --kubeconfig /path/to/kubeconfig --bootstrap --bootstrap-token-id <token-id> --bootstrap-token-secret <token-secret> --apiserver-address https://8.134.XX.XX:6443 --cluster-ca-path /path/to/ca.crt
If the cluster version is earlier than 1.14, include the cluster version information in the command. Sample command:
vnode cluster setup --kubernetes-version v1.13.0 --kubeconfig /path/to/kubeconfig --bootstrap --bootstrap-token-id eci123 --bootstrap-token-secret eci1233333333333 --apiserver-address https://8.134.XX.XX:6443 --cluster-ca-path /etc/kubernetes/pki/ca.crt
Validate whether the VNode can be deployed in the cluster.
vnode cluster validate
The following command output is returned. By default, the kubeconfig certificate is saved in
~/.vnode/deploy/kubeconfig
.kubeconfig can't be empty
ServiceAccount
Generate a kubeconfig certificate.
Prepare the information that is required to configure the cluster.
Parameter
Description
Operation
Example
kubeconfig
This parameter is used to configure the permissions that are required to deploy the VNode in the cluster.
Obtain the kubeconfig certificate from the default path
~/.kube/config
. You can also obtain a kubeconfig certificate from another path./path/to/kubeconfig
Cluster CA
This parameter is used to generate the kubeconfig certificate that is required to deploy the VNode in the cluster. You can use the CA in the kubeconfig that has the admin permissions. We recommend that you use the CA that is specified when you start the API server.
Run the
ps aux | grep apiserver
command and obtain the value of--client-ca-file
from the command output./path/to/ca.crt
Connection String of API Server
This parameter is used for communication, validation, and authentication of the cluster.
Execute the kubeconfig and obtain the connection string of the API server from the output.
https://8.134.XX.XX:6443
Configure the cluster to generate the kubeconfig certificate.
Specify actual cluster information for the parameters in the command. Sample command:
vnode cluster setup --kubeconfig /path/to/kubeconfig --apiserver-address https://8.134.XX.XX:6443 --cluster-ca-path /path/to/ca.crt
If the cluster version is earlier than 1.14, include the cluster version information in the command. Sample command:
vnode cluster setup --kubernetes-version v1.13.0 --kubeconfig /path/to/kubeconfig --apiserver-address https://8.134.XX.XX:6443 --cluster-ca-path /etc/kubernetes/pki/ca.crt
Validate whether the VNode can be deployed in the cluster.
vnode cluster validate
The following command output is returned. By default, the kubeconfig certificate is saved in
~/.vnode/deploy/kubeconfig
.kubeconfig can't be empty
Configure the ~/.vnode/config file
The ~/.vnode/config
file contains the configuration information of the VNode. VNodectl reads the file when VNodectl runs. Before you create a VNode, you must configure the file.
Execute the configuration information that is required for the VNode to run.
vnode config default
The following table describes the parameters of contexts in the configuration information.
Parameter
Required
Description
name
Yes
The name of the context.
vnode-name
No
The name of the VNode. We recommend that you do not configure the parameter to allow the system to generate a unique value.
region-id
Yes
The ID of the region in which the VNode resides. For information about how to select a region, see Make preparations in this topic.
access-key-id
Yes
When you call API operations, you must use the AccessKey pair to complete identity verification. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. For more information, see Create an AccessKey pair.
access-key-secret
Yes
vswitch-id
Yes
The ID of the vSwitch with which the VNode is associated. You can specify multiple vSwitches. For information about how to create a vSwitch, see Make preparations in this topic.
security-group-id
Yes
The ID of the security group to which the VNode belongs. For information about how to create a security group, see Make preparations in this topic.
resource-group-id
No
The resource group to which the VNode belongs.
A resource group is a mechanism in which resources are managed by groups in an Alibaba Cloud account. Each Alibaba Cloud account is assigned a default resource group. For more information, see What is Resource Management?
If you do not specify a resource group, the VNode is added to the default resource group.
kubeconfig
Yes
The path of the kubeconfig certificate that is required to deploy the VNode in the cluster. The path is automatically generated after you configure the cluster. By default, the kubeconfig certificate is saved in
~/.vnode/deploy/kubeconfig
.taints
No
The taints that are bound to the VNode.
tags
No
The tags that are bound to the VNode.
Tags can be used to manage split bills. After you bind a custom tag to the VNode, you can use the tag to filter the charged fees of instances in the VNode when you view the fee analysis. For more information, see View split bills based on tags.
Redirect the configuration information to the
~/.vnode/config
file and configure parameters in the file.vnode config default > ~/.vnode/config vim ~/.vnode/config
Modify the content of the
~/.vnode/config
file based on your business requirements. In the following example, only the required parameters are configured.kind: vnode contexts: - name: default region-id: cn-guangzhou access-key-id: LTAI5tJbBkHcHBUmuP7C**** access-key-secret: 5PlpKJT6sgLcD4f9y5pACNDbEg**** vswitch-id: vsw-7xv2yk45qp5etidgf**** security-group-id: sg-7xv5tcch4kjdr65t**** kubeconfig: ~/.vnode/deploy/kubeconfig current-context: default
Verify the configuration information that is read by the VNode when the VNode runs.
vnode config
Switch the context to allow the VNode to load the configuration in the context when the VNode runs.
vnode config set-context <context-name>
Create a VNode
Create a VNode.
vnode create
NoteThe VNode is created based on the configurations in the
~/.vnode/config
file. You can add parameters to configure customResources, clusterDNS, and clusterDomain. For more information, see Manage VNodes.The following sample output is returned. The value of VirtualNodeId is the ID of the generated VNode.
{"RequestId":"AB772F9D-2FEF-5BFD-AAFB-DA3444851F29","VirtualNodeId":"vnd-7xvetkyase7gb62u****"}
View the status of the VNode.
vnode list
The following sample output is returned. If the STATUS value is Ready, the VNode is created.
VNODE ID VNODE NAME CREATED STATUS SCHEDULABLE ZONES vnd-7xvetkyase7gb62u**** vnode-cn-guangzhou-a-7xvetkyase7gb62u**** 2 minutes ago Ready cn-guangzhou-a
View the information about nodes.
kubectl get node
The following sample output is returned, which indicates that the VNode is deployed in the cluster.
NAME STATUS ROLES AGE VERSION cn-guangzhou.vnd-7xvetkyase7gb62u**** Ready agent 174m v1.20.6 vnode-test001 Ready control-plane,master 23h v1.20.6 vnode-test002 Ready <none> 22h v1.20.6
Prevent DaemonSets from being scheduled to the VNode
DaemonSets cannot run on VNodes because VNodes are not real nodes. After you create a VNode, you need to modify the DaemonSet in kube-proxy and configure nodeAffinity to prevent DaemonSets from being scheduled to the VNode.
Modify the configurations of the DaemonSet.
kubectl -n kube-system edit ds kube-proxy
Configure nodeAffinity.
Add the following YAML content to spec > template > spec:
affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: type operator: NotIn values: - virtual-kubelet
Schedule pods to the VNode
After you create a VNode, you can use one of the following methods to schedule pods to the VNode. Then, you can run the pods as elastic container instances in the VNode.
Manual scheduling
You can configure the nodeSelector and tolerations parameters or specify the nodeName parameter to schedule pods to the VNode. For more information, see Schedule pods to a VNode.
Automatic Scheduling
After you deploy the eci-profile component, you can specify the Selector parameter. This way, the system automatically schedules pods that meet the conditions specified by Selector to the VNode. For more information, see Use eci-profile to schedule pods to a VNode.