Docs

Volcengine Kubernetes Engine

Container Network

Configuring Static IPs for pods

Volcengine Kubernetes Engine allows static IPs for pods to address requirements such as IP-based access control, service registration, service discovery, and audit logging. This topic describes how to configure static IPs for pods.

tip

[Beta - apply for trial]: This feature is currently in beta. Submit an application to use it.

Background

Volcengine Kubernetes Engine allows the Trunk ENI mode enabled when creating clusters with the VPC-CNI network model. The pods running on a Trunk ENI node can have ENI (elastic network interface) of their own with the specified subnets and security groups.

A pod can be assigned a static IP if it has a dedicated network interface. It facilitates configurations such as access control, service registration, service discovery, and audit logging based on the IP of a pod. Here are the CRD objects to be used when configuring static IPs:

VPCENIDefinition object: This object defines the VPC IPAM configuration of the ENI, including VPC ID, IP allocation mode, security groups, and subnet ID.

PodNetworkDefinition object: This object is used to define the network configuration of a pod, including IPAM and Pod selector.

Usage limits

Trunk ENI is applicable only to clusters using the VPC-CNI network model.

The pod name must not exceed 63 characters.

Prerequisites

The vpc-cni add-on has been installed and upgraded to v1.6.0 or later.

The vpc-cni-controlplane add-on has been installed and upgraded to v1.6.0 or later.

tip

For details about the versions and upgrading add-ons, see Add-on release notes and Upgrading add-ons.

Procedure

Step 1: Enable Trunk ENI

Enable when creating clusters

Enable for existing clusters

tip

This topic only covers the key configurations for enabling Trunk ENI when creating a cluster, including installing the vpc-cni-controlplane add-on. For more details about creating a cluster, see Creating clusters.

On the cluster management page, select Cluster in the left navigation bar.

Click Create cluster in the upper left corner to go to the Cluster configuration page. Finish the configurations on the page and click Next: Node pool configuration in the lower-right corner.

The key parameters are as follows. Other parameters can be configured as needed.

Parameter	Description
Network model	Select a Container Network Interface (CNI) for the cluster. In this case, VPC-CNI is required.
Trunk ENI	Disabled by default. After enabling this option, Trunk ENI can be used to support exclusive ENIs for pods, providing advanced capabilities such as binding security groups to pods and scheduling pods to specified subnets. You need to enable this configuration in this scenario.

Finish the necessary configurations on the Node pool configuration page, and click Next: Addon configuration in the lower right corner.

The vpc-cni-controlplane add-on is selected by default on the page. You can select more add-ons if necessary and then click Next: Configuration confirmation to finish.

After confirming that the cluster information and billing details are correct, read the Volcengine Kubernetes Engine Specific Terms of Service, select the checkbox to accept them, and then click Confirm to start creating the cluster.

Step 2: Enable static IP for pods

Click the cluster name you just created to enter the cluster management page.

Select Addons in the left navigation bar.

On the Network tab, click Configuration on the vpc-cni-controlplane add-on and enable Static IP for pods in the pop-up window.

Click Confirm to finish.

tip

If this option does not appear in your cluster or is grayed out and cannot be configured, it indicates that Trunk ENI is not enabled in the cluster or the add-on is not at the required version. For more information, see the previous content.

Step 3: Create a VPCENIDefinition object

Create a VPCENIDefinition object. The configuration example and key parameter descriptions are as follows:

The parameters under spec are listed below.

Parameter			Required	Description
vpcID	-	Yes	The ID of the VPC (Virtual Private Cloud) to which the cluster belongs.
allocateType	type	Yes	IP allocation mode: Elastic: elastic IP policy. The IP resources are released as soon as pods are deleted. Fixed: static IP policy.
		releaseStrategy	It is required if the type is set to Fixed	IP reclaim policy. It is effective only if type is set to Fixed. Valid values: TTL: delayed reclaim. The system will reclaim IP addresses based on the configuration of releaseAfter. Never: never reclaim. The system will not automatically reclaim IP addresses. You need to manually delete the PodENI resource to release the IPs. tip If it is set to Never, the releaseAfter parameter becomes ineffective.
		releaseAfter	It is required if the type is set to Fixed	IP release time. Only effective if releaseStrategy is set to TTL. The delayed time before reclaiming the IP address after a pod is removed. The time format is Go time type, for example, 2h35m and 3m0s. For details on the format of Go time type, see Go time type. A value of 0 indicates immediate reclaim.
securityGroupIDs	-	Yes	Specify security group IDs. Multiple security groups can be configured and will be effective simultaneously.
subnetIDs	-	Yes	Specify one or more subnet IDs within the VPC. They can be some or all of the subnets assigned to cluster pods, or subnets in the specified VPC that are not assigned to any pods.

Step 4: Create the PodNetworkDefinition object

Create a PodNetworkDefinition object. The configuration example and key parameter descriptions are as follows:

The parameters under spec are listed below.

Parameter			Required	Description
ipResource	name	Yes	Specify a name for the network resource, which needs to be consistent with the name of the VPCENIDefinition object.
ipResource		type	Yes	Specify the type of network resource. It needs to be VPCENIDefinition in this case.
selectors	podSelector	No	Specify the labels used to match Pods. Matching Pods use the network resources specified by ipResource during Pod creation.
selectors		namespaceSelector	No	Specify labels for selecting namespaces. All Pods in the matching namespaces will use the network resources specified by ipResource during Pod creation.

warning

podSelector and namespaceSelector are optional parameters that can be configured as needed. At least one of them must be configured so that the feature can take effect.

The selectors is a list that may contain multiple namespaces and pod labels. Each individual member in the list can have labels for both namespaces and pods simultaneously.

The selectors contained in each member apply AND logically with each other. It means only the pod with labels that match the two selectors simultaneously can be assigned with an ENI and a static IP if both selectors are configured.

The members in the list apply OR logically with each other if there is more than one member in the list. It means a pod that matches the selectors of any member in the list can be assigned an ENI and a static IP.

Step 5: Configure an ENI dedicated to a pod

There are several methods to do it:

Namespace label: Use namespace labels to assign ENIs to all the pods under the namespaces.

Pod label: Use pod labels to assign ENIs to specific pods.

tip

You can use either one label type or both. If both types are used, pods need to match them simultaneously to get ENIs.

Configuring namespace labels

Creating pods and adding labels

Creating workloads and adding labels

You can add the label defined in the PodNetworkDefinition object (e.g., foo: bar) when creating a namespace, so that all the pods in that namespace can have dedicated ENIs The example is as follows:

Validating results

When the configurations are saved, the system adds necessary annotations (including ENI request/limit) to pods matching the labels in the PodNetworkDefinition object. It then relocates these pods to Trunk-enabled nodes and provides them with dedicated ENIs.

tip

For pods running with static IPs, the AZs (availability zones) of ENIs are determined when pods are first created. If pods are rebuilt later, they will automatically relocate to the AZs of the nodes where the original pods were first created. This achieves automatic affinity.

As shown in the following figure, automatically added annotations (such as k8s.volcengine.com/eni-ip-status) indicate that the pod has been configured with a dedicated ENI.

The information about ENIs can be found on the Network interface tab of the Pod Details page.

After you delete and recreate the Pod, the Pod IP address remains unchanged, indicating that the static IP has been successfully configured for the Pod.

Last updated: 2026.08.17 11:13:34