How to configure an Elastic Container Instance pod to use a fixed IP address - Elastic Container Instance

By default, ECI assigns a pod a random IP address from the vSwitch CIDR block defined in eci-profile. If the pod is deleted or fails, the IP is released and the replacement pod gets a new one. Enable fixed IP addresses to ensure a pod reclaims the same IP after restart, so upstream systems that rely on IP-based access control, log correlation, or service discovery are not disrupted.

With fixed IP addresses, you can:

Enforce IP-based firewall or security group rules without updating them on every pod restart.
Correlate logs and audit records by pod IP across restarts.
Maintain stable identifiers for peer-to-peer communication between stateful services.

If your service has no IP-based dependencies, fixed IP addresses are not needed.

How it works

When fixed IP is enabled, ECI assigns the pod two IP addresses from the specified vSwitch CIDR block:

A dynamic IP address, used internally by the cluster and not visible to workloads.
A fixed IP address, retained after the pod is deleted.

When a new pod is created, ECI reassigns the retained fixed IP address to it if all of the following conditions are met:

Same cluster ID
Same namespace
Same pod name
Fixed IP feature enabled on both the original and the new pod

If the fixed IP is not reclaimed within the retention period, ECI releases it. The default retention period is 48 hours. Configure a shorter period to free up IP addresses sooner and reduce the risk of exhausting your vSwitch CIDR block.

Use a StatefulSet to deploy services that require fixed IP addresses. StatefulSet automatically recreates deleted pods with the same name in the same namespace, which satisfies all four reassignment conditions.

Limitations

Review the following constraints before configuring fixed IP addresses:

Requires StatefulSet: Fixed IP reassignment requires all four conditions (cluster ID, namespace, pod name, and annotation) to match. Deployments do not preserve pod names, so IP reassignment does not work with Deployments.
Double IP consumption: Each fixed-IP pod consumes two IP addresses from the vSwitch CIDR block. Set the retention period based on your pod turnover rate to avoid IP exhaustion.
Delayed pod creation: If a new pod is created before the original pod is fully deleted, the original pod still holds the fixed IP, which delays creation of the new pod.

Annotations

Add the following annotations to the pod metadata to enable fixed IP and configure the retention period.

Annotation	Example value	Description
`k8s.aliyun.com/eci-fixed-ip`	`"true"`	Enables the fixed IP address feature.
`k8s.aliyun.com/eci-fixed-ip-retain-hour`	`"24"`	Number of hours to retain the fixed IP address after the pod is deleted and the IP becomes idle. Defaults to `48`. Shorter values reduce the risk of IP exhaustion; longer values improve reclaim reliability after extended outages.

Configure a StatefulSet with a fixed IP address

Prerequisites

Before you begin, make sure you have:

A running Kubernetes cluster with ECI enabled
kubectl configured to connect to the cluster

Deploy the StatefulSet

Create a file named fixedIp.yaml with the following content. The manifest defines a headless Service and a StatefulSet. The pod template includes the k8s.aliyun.com/eci-fixed-ip: "true" annotation to enable the fixed IP feature.

apiVersion: v1
kind: Service
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  ports:
  - port: 80
    name: web
  clusterIP: None
  selector:
    app: nginx
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  selector:
    matchLabels:
      app: nginx
  serviceName: "nginx"
  minReadySeconds: 10
  template:
    metadata:
      annotations:
        k8s.aliyun.com/eci-fixed-ip: "true"  # Enables the fixed IP address.
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
    spec:
      containers:
      - name: nginx
        image: registry-vpc.cn-beijing.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
          name: web

Apply the manifest.
```
kubectl apply -f fixedIp.yaml
```
Watch the pod status to confirm the pod is running and note its IP address.
```
kubectl get pod -o wide -w
```
The output shows that pod web-0 has been assigned an IP address, for example 172.16.0.129.

Verify IP address retention

Open a second terminal and delete the pod.
```
kubectl delete pod web-0
```
Switch back to the first terminal and observe the output. StatefulSet automatically creates a new web-0 pod. The new pod is assigned the same IP address as the deleted pod.
The original pod holds the fixed IP address until it is fully deleted. This may briefly delay creation of the new pod.