Elastic Container Instance:Manually deploy a VNode in a self-managed Kubernetes cluster

Limitations

Before you begin, note the following constraints:

• VNodes are not real nodes. DaemonSets cannot run on VNodes. After deployment, configure nodeAffinity on kube-proxy to exclude the VNode from DaemonSet scheduling.

• ServiceAccount mode does not support certificate rotation. If the kubeconfig token expires, the VNode stops working.

• Supported Kubernetes versions: 1.16 to 1.30.

Prerequisites

Before you begin, make sure you have:

• A Kubernetes cluster (version 1.16–1.30)

• If the cluster runs in a data center: a network connection between the data center and the virtual private cloud (VPC) where ECI pods will run, established via Express Connect, Smart Access Gateway (SAG), or VPN Gateway. For setup instructions, see What is Express Connect?, What is SAG?, or What is VPN Gateway?

• The following network resources in the target region:

  • A VPC that can reach the Kubernetes API server

  • One or more vSwitches within the VPC (you can specify 1 to 10 vSwitches for a VPC)

  • An advanced security group with these inbound rules:

    • Allow all ports (1–65535) from the VPC CIDR block

    • Allow ports 10250 and 10255 from the Kubernetes API server endpoint

Step 1: Prepare required permissions

To create a VNode, the VNode identity needs both standard Kubernetes node permissions and additional ECI-specific permissions.

Standard permissions:

Additional permissions:

Step 2: Generate a kubeconfig certificate

The VNode uses a kubeconfig certificate to authenticate against your Kubernetes cluster. Skip this step if you plan to use an admin certificate.

Two modes are available:

cat vnode-config

apiVersion: v1
kind: Config
current-context: kubernetes-admin@kubernetes
contexts:
- name: kubernetes-admin@kubernetes
  context:
    cluster: kubernetes-admin@kubernetes
    user: vnode
    namespace: kube-system
clusters:
- name: kubernetes-admin@kubernetes
  cluster:
    certificate-authority-data: "*****************************************=="
    server: https://10.16.XX.XX:6443
users:
- name: vnode
  user:
    token: ******.****************

apiVersion: v1
kind: Config
current-context: kubernetes-admin@kubernetes
contexts:
- name: kubernetes-admin@kubernetes
  context:
    cluster: kubernetes-admin@kubernetes
    user: vnode
    namespace: kube-system
clusters:
- name: kubernetes-admin@kubernetes
  cluster:
    certificate-authority-data: "*****************************************=="
    server: https://10.16.XX.XX:6443
users:
- name: vnode
  user:
    token: ***********************************************

Step 3: Create a VNode

Step 4: Verify the VNode

After creating the VNode, wait a few minutes, then run the following command in your Kubernetes cluster:

kubectl get nodes

If the VNode information is displayed in the node list, the VNode is created successfully. If the VNode does not appear, see Troubleshooting.

Step 5: Prevent DaemonSets from scheduling to the VNode

VNodes are virtual — DaemonSets cannot run on them. After creating the VNode, configure nodeAffinity on kube-proxy to exclude the VNode.

1. Open the kube-proxy DaemonSet for editing:

   kubectl -n kube-system edit ds kube-proxy

2. Add the following block to spec.template.spec:

   affinity:
     nodeAffinity:
       requiredDuringSchedulingIgnoredDuringExecution:
         nodeSelectorTerms:
         - matchExpressions:
           - key: type
             operator: NotIn
             values:
             - virtual-kubelet

Troubleshooting

If the VNode does not appear in kubectl get nodes, open the Elastic Container Instance console, go to the Virtual Node page, click the VNode ID, and view the Events tab.

What's next

Schedule pods to the VNode to run them as elastic container instances:

• Manual scheduling: Use nodeSelector, tolerations, or nodeName to target the VNode explicitly. For details, see Schedule pods to a VNode.

• Automatic scheduling: Deploy the eci-profile component and configure a Selector. Pods matching the selector are automatically scheduled to the VNode. For details, see Use eci-profile to schedule pods to a VNode.

For questions or issues deploying a VNode in a self-managed Kubernetes cluster, join the DingTalk group (ID: 44666389) for assistance.