All Products
Search

This Product

    Container Compute Service:Annotations for attaching an EIP to a pod

    Document Center

    Container Compute Service:Annotations for attaching an EIP to a pod

    Last Updated:Mar 26, 2026

    Use pod annotations to attach an elastic IP address (EIP) to a pod in an Alibaba Cloud Container Service for Kubernetes (ACS) cluster. This gives the pod its own public IP, independent of the shared NAT gateway used by the cluster. You can either let ACS automatically create and attach an EIP, or attach an existing EIP instance by ID.

    Prerequisites

    Before you begin, make sure that you have:

    Attach an EIP to a pod

    Two approaches are available: let ACS automatically create and attach an EIP, or specify an existing EIP instance by ID. Use the automatic approach for most cases. Use the static instance approach for StatefulSets that require a stable, persistent public IP.

    Automatically create an EIP

    Add the network.alibabacloud.com/pod-with-eip: "true" annotation to the pod spec. ACS creates an EIP and attaches it to the pod when the pod starts.

    Important

    Automatic EIP allocation can result in EIPs being repeatedly created and released — for example, when a pod is recreated or when the Container Network Interface (CNI) component fails to configure the network. To avoid this, specify an EIP instance by ID instead.

    The following YAML shows all supported annotations for automatic EIP creation. Each annotation is marked as required or optional.

    apiVersion: v1
kind: Pod
metadata:
  annotations:
    network.alibabacloud.com/pod-with-eip: "true"                              # Required. Enables automatic EIP creation and attachment.
    network.alibabacloud.com/eip-bandwidth: "5"                                # Optional. Maximum bandwidth in Mbit/s.
    network.alibabacloud.com/eip-internet-charge-type: "PayByTraffic"          # Optional. Metering method: PayByTraffic (default) or PayByBandwidth.
    network.alibabacloud.com/eip-instance-charge-type: "PostPaid"              # Optional. Billing method: PostPaid (pay-as-you-go) or PrePaid (subscription).
    network.alibabacloud.com/eip-isp: "BGP"                                    # Optional. Line type: BGP (Multi-ISP) or BGP_PRO (BGP Multi-ISP Pro).
    network.alibabacloud.com/eip-common-bandwidth-package-id: "<package-id>"   # Optional. Internet Shared Bandwidth instance ID.
    network.alibabacloud.com/eip-public-ip-address-pool-id: "<pool-id>"        # Optional. IP address pool ID.
    network.alibabacloud.com/eip-resource-group-id: "<resource-group-id>"      # Optional. Resource group for the EIP.
    network.alibabacloud.com/eip-name: "<eip-name>"                            # Optional. Display name for the EIP.
    network.alibabacloud.com/eip-description: "<description>"                  # Optional. Description for the EIP.
    network.alibabacloud.com/eip-security-protection-types: "<level1>,<level2>"# Optional. Security protection levels, comma-separated.

    The following table describes each annotation in detail.

    Annotation Description
    network.alibabacloud.com/pod-with-eip Whether to automatically create and attach an EIP. Set to true to enable, false to disable.
    network.alibabacloud.com/eip-bandwidth Maximum bandwidth of the EIP. Unit: Mbit/s.
    network.alibabacloud.com/eip-internet-charge-type Metering method. PayByTraffic (default): pay-by-traffic. PayByBandwidth: pay-by-bandwidth. For billing details, see Billing overview.
    k8s.aliyun.com/eip-charge-type Compatible with earlier versions.
    network.alibabacloud.com/eip-instance-charge-type Billing method. PostPaid: pay-as-you-go. PrePaid: subscription. See Pay-as-you-go and Subscription.
    network.alibabacloud.com/eip-isp Line type. BGP: BGP (Multi-ISP) lines. BGP_PRO: BGP (Multi-ISP) Pro lines. See Apply for EIPs.
    network.alibabacloud.com/eip-common-bandwidth-package-id ID of the Internet Shared Bandwidth instance to use.
    network.alibabacloud.com/eip-public-ip-address-pool-id IP address pool. See Create and manage an IP address pool.
    network.alibabacloud.com/eip-resource-group-id Resource group for the EIP. See Apply for EIPs.
    network.alibabacloud.com/eip-name Display name of the EIP. See Apply for EIPs.
    network.alibabacloud.com/eip-description Description of the EIP. See Apply for EIPs.
    network.alibabacloud.com/eip-security-protection-types Security protection level of the EIP. Separate multiple levels with a comma (,). See Request an EIP.

    Specify an EIP instance

    Attach an existing EIP to a pod by specifying its instance ID. The EIP controller attaches the EIP without modifying the EIP instance configuration.

    Important

    • This approach is not applicable to controllers with multiple replicas. Use it only with a StatefulSet for stateful applications.

    • Attach each EIP instance to only one pod at a time. After the pod exits, the EIP controller detaches the EIP, during which the EIP cannot be used by other pods. To check whether a pod and its EIP have been detached, verify that a pod EIP resource with the same name as the pod no longer exists.

    apiVersion: v1
kind: Pod
metadata:
  annotations:
    network.alibabacloud.com/pod-eip-instanceid: "eip-bp14qxxxxxxx"  # Required. The ID of the EIP to attach.
    Annotation Description
    network.alibabacloud.com/pod-eip-instanceid ID of the EIP to attach, for example, eip-bp14qxxxxxxx. See Apply for EIPs.
    k8s.aliyun.com/eci-eip-instanceid Compatible with Elastic Container Instance.

    Configure the EIP release policy

    Use the network.alibabacloud.com/pod-eip-release-strategy annotation to control what happens to the EIP when its pod is deleted.

    Important

    • This feature applies only to StatefulSets for stateful applications. It cannot be used with Deployments for stateless applications.

    • If you attach an EIP by instance ID, that EIP is never released by the controller.

    Choose a release strategy based on whether your application needs to reuse the same public IP after a pod restart:

    Strategy Behavior When to use
    Follow (default) The EIP is released when the pod is deleted. StatefulSet workloads where IP reuse is not required.
    Never The EIP is never released automatically. Delete it manually when it is no longer needed. When you need to preserve the EIP for future reassignment.
    Duration (e.g., 5m30s) The EIP is retained for the specified duration after the pod is deleted, then released. A pod with the same name created during this window reuses the same EIP. Stateful applications that require a stable public IP across pod restarts, used with automatic EIP allocation.

    The duration value uses Go duration format. For example, 5m30s means the EIP is released 5 minutes and 30 seconds after the pod is deleted.

    apiVersion: v1
kind: Pod
metadata:
  annotations:
    network.alibabacloud.com/pod-with-eip: "true"
    network.alibabacloud.com/pod-eip-release-strategy: "5m30s"  # Retain the EIP for 5m30s after the pod is deleted.
    Annotation Description
    network.alibabacloud.com/pod-eip-release-strategy EIP release policy. Follow (default): follows the pod lifecycle. Never: never releases the EIP automatically. Duration string (e.g., 5m30s): releases the EIP after the specified time.