In most cases, a pod uses a private IP address. In a Container Service for Kubernetes (ACK) cluster that uses Terway, a pod may require a dedicated public IP address in some cases. This topic describes how to associate an elastic IP address (EIP) with a pod in a cluster that uses Terway.

Background information

In most cases, to enable a pod to access the Internet, the IP address of the pod is converted to an EIP that is associated with the host or the NAT gateway of the virtual private cloud (VPC) based on SNAT rules. The inbound Internet traffic to the pod is routed through the related LoadBalancer type Services. A pod may require a dedicated public IP address in the following scenarios.
  • The pod exposes random ports to the Internet. For example, game servers and audio conferences that use the UDP. For example, if the Real Time Streaming Protocol (RTSP) is used, different ports are used for different clients.
  • The pod competes with other pods for a public IP address to access the Internet. In this case, the pod requires a dedicated public IP address to access the Internet.

For more information about how to use the Terway network plug-in in an ACK cluster, see Work with Terway.

Step 1: Update Terway to the latest version

Update Terway in your ACK cluster to a version that supports EIP. For more information about how to update Terway, see Manage system components.

Note Terway V1.0.10.280-gdc2cb6c-aliyun and later support EIP. We recommend that you update Terway to the latest version.

Step 2: Configure and grant permissions to manage EIPs

You must configure and grant EIP-related permissions to the cluster that uses Terway.

Grant EIP-related permissions to the RAM role of the cluster that uses Terway

  1. Grant EIP-related permissions to the Resource Access Management (RAM) role of the cluster that uses Terway.

    For ACK managed clusters that were created before June 2020 or ACK dedicated clusters, you must grant permissions to the worker RAM role of the cluster.

    1. Log on to the ACK console and click Clusters in the left-side navigation pane.
    2. On the Clusters page, click the name of the cluster that you want to manage. Click the Cluster Resources tab and click the hyperlink to the right side of Worker RAM Role.
    3. On the Permissions tab, click the name of the policy assigned to the RAM role. The details page of the policy appears.
      Policy details
    4. Click Modify Policy Document. In the Modify Policy Document panel that appears on the right side of the page, add the following content to the Action field in the Policy Document section. Click OK.
      Modify Policy Document
      "vpc:DescribeVSwitches",
      "vpc:AllocateEipAddress",
      "vpc:DescribeEipAddresses",
      "vpc:AssociateEipAddress",
      "vpc:UnassociateEipAddress",
      "vpc:ReleaseEipAddress",
      "vpc:AddCommonBandwidthPackageIp",
      "vpc:RemoveCommonBandwidthPackageIp"
      Note Before you add the policy content, add a comma (,) to the end of the bottom line in the Action field.

    For ACK standard clusters that were created in and after June 2020 or ACK Pro clusters, you must grant permissions to the AliyunCSManagedNetworkRole RAM role.

    Grant EIP-related permissions to the AliyunCSManagedNetworkRole RAM role in the RAM console.

    1. On the RAM role AliyunCSManagedNetworkRole page, find the policy and click Add Permissions on the right side of the page.
    2. In the Add Permissions panel, click + Create Policy in the Select Policy section to create a custom policy.
      For information about how to create a custom policy, see Create a custom policy.
    3. Add the following policy content to the custom policy.
      For more information about how to modify a custom policy, see Modify the document and description of a custom policy.
      "vpc:DescribeVSwitches",
      "vpc:AllocateEipAddress",
      "vpc:DescribeEipAddresses",
      "vpc:AssociateEipAddress",
      "vpc:UnassociateEipAddress",
      "vpc:ReleaseEipAddress",
      "vpc:AddCommonBandwidthPackageIp",
      "vpc:RemoveCommonBandwidthPackageIp"
  2. Configure Terway to support EIP.
    1. Run the following command to modify the eni_conf ConfigMap of the Terway configurations:
      kubectl edit cm eni-config -n kube-system
    2. Add the following content to the eni_conf ConfigMap:
      "enable_eip_pool": "true"
      Notice If you want to disassociate the existing EIP when you associate a new one, add "allow_eip_rob": "true" to the eni_conf ConfigMap.
    3. After you modify the configuration file, press Esc. Then, enter :wq! and press Enter to save the configuration file and exit the insert mode.
    4. Run the following command to redeploy Terway:
      kubectl delete pod -n kube-system -l app=terway-eniip

Step 3: Add annotations to create and associate an EIP with a pod

You can add annotations to the configurations of a pod to create or associate an EIP with the pod. For more information about the limits of EIPs, see Limits. The following table describes the annotations that are used to configure EIPs.
Annotation Description
k8s.aliyun.com/pod-with-eip Specifies whether to automatically create an EIP and associate the EIP with the elastic container instance. Valid values:
  • true: enables auto update
  • false: disables auto update
k8s.aliyun.com/eip-bandwidth The maximum bandwidth value for the EIP. Unit: Mbit/s. Default value: 5.
k8s.aliyun.com/eip-charge-type The metering method of the EIP. Valid values:
  • PayByBandwidth: pay-by-bandwidth
  • PayByTraffic: pay-by-data-transfer
k8s.aliyun.com/pod-eip-instanceid Specifies an existing EIP that you want to associate.
k8s.aliyun.com/eip-common-bandwidth-package-id Specifies the EIP bandwidth plan that you want to use.
k8s.aliyun.com/eip-isp Specifies the line type of the EIP. Valid values:
  • BGP: BGP (Multi-ISP) lines
  • BGP_PRO: BGP (Multi-ISP) Pro lines
Add annotations as described in the following scenarios:
  • Automatically create and associate an EIP with a pod
    • Add the following annotation to create and associate an EIP with a pod:
      k8s.aliyun.com/pod-with-eip: "true"
      The following YAML file is provided as an example.
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: nginx-deployment-basic
        labels:
          app: nginx
      spec:
        replicas: 2
        selector:
          matchLabels:
            app: nginx
        template:
          metadata:
            annotations:
              k8s.aliyun.com/pod-with-eip: "true" # Specifies that an EIP is automatically created and associated with the NGINX containers. 
            labels:
              app: nginx
          spec:
            containers:
            - name: nginx
              image: nginx
    • Add the following annotation to specify the bandwidth for the EIP. The default EIP bandwidth is 5 Mbit/s.
      k8s.aliyun.com/eip-bandwidth: "5"
  • Specify an existing EIP

    Add the following annotation to specify the ID of an existing EIP and associate it with a pod:

    k8s.aliyun.com/pod-eip-instanceid: "<youreipInstanceId>"
    Note
    • An EIP cannot be associated with multiple pods. Therefore, you cannot use this annotation for pods of Deployments and StatefulSets.
    • By default, if an EIP is already associated with a pod, you fail to create a new EIP for the pod. If you want to disassociate the existing EIP and create a new one, add the "allow_eip_rob": "true" setting to the eni_conf ConfigMap as described in the preceding step.
    • You can specify an existing EIP only when the application runs one pod replica. For example, a Deployment that runs only one pod replica.

Verify the configurations

When the pod changes to the Running state, you can check the value of k8s.aliyun.com/allocated-eipAddress in the pod annotations. The value is the associated EIP. You can access the pod through the EIP.