amazon.aws.ec2_eip 模块 – 管理 EC2 弹性 IP (EIP) 地址。

注意

此模块是 amazon.aws 集合 (版本 9.0.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install amazon.aws。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。

要在 playbook 中使用它，请指定：amazon.aws.ec2_eip。

amazon.aws 5.0.0 中的新增功能

概要

  • 此模块可以分配或释放 EIP。

  • 此模块可以将 EIP 与实例或网络接口关联/取消关联。

  • 此模块最初添加到 community.aws 的 1.0.0 版本中。

要求

以下要求是在执行此模块的主机上所需的。

  • python >= 3.6

  • boto3 >= 1.28.0

  • botocore >= 1.31.0

参数

参数

注释

access_key

别名：aws_access_key_id、aws_access_key、ec2_access_key

字符串

AWS 访问密钥 ID。

有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。

还可以按优先级递减的顺序使用 AWS_ACCESS_KEY_ID、AWS_ACCESS_KEY 或 EC2_ACCESS_KEY 环境变量。

aws_access_key 和 profile 选项是互斥的。

为了与 AWS botocore SDK 保持一致，aws_access_key_id 别名是在 5.1.0 版本中添加的。

ec2_access_key 别名已被弃用，并将在 2024-12-01 之后的一个版本中删除。

EC2_ACCESS_KEY 环境变量的支持已被弃用，并将在 2024-12-01 之后的一个版本中删除。

allow_reassociation

布尔值

指定此选项以允许已与其他网络接口或实例关联的弹性 IP 地址与指定的实例或接口重新关联。

选项

  • false ← (默认)

  • true

aws_ca_bundle

路径

验证 SSL 证书时要使用的 CA 捆绑包的位置。

还可以使用 AWS_CA_BUNDLE 环境变量。

aws_config

字典

用于修改 botocore 配置的字典。

可以在 AWS 文档中找到参数 https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config。

debug_botocore_endpoint_logs

布尔值

使用 botocore.endpoint 记录器来解析在任务期间进行的唯一（而不是总计）"resource:action" API 调用，并将集合输出到任务结果中的 resource_actions 密钥。使用 aws_resource_action 回调将输出到 playbook 期间进行的总列表。

还可以使用 ANSIBLE_DEBUG_BOTOCORE_LOGS 环境变量。

选项

  • false ← (默认)

  • true

device_id

字符串

EIP 设备的 ID。

可以是 EC2 实例 ID 或弹性网络接口 (ENI) ID。

指定 ENI ID 时，必须将 in_vpc 设置为 true。

instance_id 别名已在 6.0.0 版本中删除。

domain_name

字符串

amazon.aws 8.3.0 版本中添加

要附加到 IP 地址的域名。

endpoint_url

别名：ec2_url、aws_endpoint_url、s3_url

字符串

要连接到的 URL，而不是默认的 AWS 端点。虽然这可以用于连接到其他与 AWS 兼容的服务，但 amazon.aws 和 community.aws 集合仅针对 AWS 进行了测试。

还可以按优先级递减的顺序使用 AWS_URL 或 EC2_URL 环境变量。

ec2_url 和 s3_url 别名已被弃用，并将在 2024-12-01 之后的一个版本中删除。

EC2_URL 环境变量的支持已被弃用，并将在 2024-12-01 之后的一个版本中删除。

in_vpc

布尔值

是否在 VPC 内分配 EIP。

如果使用 device_id 指定 ENI，则需要此参数。

选项

  • false ← (默认)

  • true

private_ip_address

字符串

要与弹性 IP 地址关联的主私有 IP 地址或辅助私有 IP 地址。

profile

别名：aws_profile

字符串

用于身份验证的命名 AWS 配置文件。

有关命名配置文件的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html。

还可以使用 AWS_PROFILE 环境变量。

profile 选项与 aws_access_key、aws_secret_key 和 security_token 选项互斥。

public_ip

别名：ip

字符串

先前分配的 EIP 的 IP 地址。

当state=present且指定了device时，EIP将与该设备关联。

当state=absent且指定了device时，EIP将与该设备解关联。

public_ipv4_pool

字符串

仅适用于新分配的弹性IP，从提供的public IPv4池（BYOIP）分配新的弹性IP；当reuse_existing_ip_allowed=true时，不会进行验证。

purge_tags

布尔值

如果purge_tags=true并且设置了tags，则将从资源中清除现有标签，以完全匹配tags参数中定义的内容。

如果未设置tags参数，则即使purge_tags=True，也不会修改标签。

以aws:开头的标签键由Amazon保留，无法修改。因此，在purge_tags参数中将忽略它们。有关更多信息，请参阅Amazon文档https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions。

选项

  • false

  • true ← (默认)

region

别名：aws_region, ec2_region

字符串

要使用的AWS区域。

对于IAM、Route53和CloudFront等全球服务，将忽略region。

也可以使用AWS_REGION或EC2_REGION环境变量。

有关更多信息，请参阅Amazon AWS文档http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region。

ec2_region别名已弃用，将在2024-12-01之后的发行版中移除。

EC2_REGION环境变量的支持已弃用，将在2024-12-01之后的发行版中移除。

release_on_disassociation

布尔值

是否在解关联时自动释放EIP。

选项

  • false ← (默认)

  • true

reuse_existing_ip_allowed

布尔值

重用未与设备关联的EIP（如果可用），而不是分配新的EIP。

选项

  • false ← (默认)

  • true

secret_key

别名：aws_secret_access_key, aws_secret_key, ec2_secret_key

字符串

AWS密钥访问密钥。

有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。

也可以使用AWS_SECRET_ACCESS_KEY、AWS_SECRET_KEY或EC2_SECRET_KEY环境变量（优先级递减）。

secret_key和profile选项是互斥的。

为了与AWS botocore SDK保持一致，在5.1.0版本中添加了aws_secret_access_key别名。

ec2_secret_key别名已弃用，将在2024-12-01之后的发行版中移除。

EC2_SECRET_KEY环境变量的支持已弃用，将在2024-12-01之后的发行版中移除。

session_token

别名：aws_session_token, security_token, aws_security_token, access_token

字符串

与临时凭据一起使用的AWS STS会话令牌。

有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。

也可以使用AWS_SESSION_TOKEN、AWS_SECURITY_TOKEN或EC2_SECURITY_TOKEN环境变量（优先级递减）。

security_token和profile选项是互斥的。

在3.2.0版本中添加了aws_session_token和session_token别名，在6.0.0版本中将参数名称从security_token重命名为session_token。

security_token、aws_security_token和access_token别名已弃用，将在2024-12-01之后的发行版中移除。

EC2_SECRET_KEY和AWS_SECURITY_TOKEN环境变量的支持已弃用，将在2024-12-01之后的发行版中移除。

state

字符串

当state=present时，分配EIP或将现有EIP与设备关联。

当state=absent时，将EIP与设备解关联，并可以选择释放它。

选项

  • "present" ← (默认)

  • "absent"

tag_name

字符串

当reuse_existing_ip_allowed=true时，补充使用此选项，只有当弹性IP带有tag_name标签时才重用它。

tag_value

字符串

补充tag_name，但也检查tag_name中提供的标签的值是否与tag_value匹配。

tags

别名：resource_tags

字典

表示要应用于资源的标签的字典。

如果未设置tags参数，则不会修改标签。

validate_certs

布尔值

设置为false时，将不会验证与AWS API通信的SSL证书。

强烈建议不要设置validate_certs=false，可以考虑改用aws_ca_bundle。

选项

  • false

  • true ← (默认)

备注

注意

  • EIP分配后到云实例可以通过新地址访问之间可能存在延迟。如有必要，可以使用wait_for和pause来延迟进一步的剧本执行，直到实例可访问。

  • 此模块在解关联或释放时返回多个已更改状态。它根据发生的任何更改返回总体状态。它还返回解关联和释放的各个已更改状态。

  • 在2.1.0版本中添加了对tags和purge_tags的支持。

  • 注意：对于模块，环境变量和配置文件是从Ansible的“主机”上下文而不是“控制器”上下文读取的。因此，可能需要将文件显式复制到“主机”。对于查找和连接插件，环境变量和配置文件是从Ansible的“控制器”上下文而不是“主机”上下文读取的。

  • Ansible使用的AWS SDK (boto3)也可能从Ansible“主机”上下文中的配置文件（通常为~/.aws/credentials）读取凭据和其他设置（如区域）的默认值。有关更多信息，请参阅https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html。

示例

# Note: These examples do not set authentication details, see the AWS Guide for details.

- name: associate an elastic IP with an instance
  amazon.aws.ec2_eip:
    device_id: i-1212f003
    ip: 93.184.216.119

- name: associate an elastic IP with a device
  amazon.aws.ec2_eip:
    device_id: eni-c8ad70f3
    ip: 93.184.216.119

- name: associate an elastic IP with a device and allow reassociation
  amazon.aws.ec2_eip:
    device_id: eni-c8ad70f3
    public_ip: 93.184.216.119
    allow_reassociation: true

- name: disassociate an elastic IP from an instance
  amazon.aws.ec2_eip:
    device_id: i-1212f003
    ip: 93.184.216.119
    state: absent

- name: disassociate an elastic IP with a device
  amazon.aws.ec2_eip:
    device_id: eni-c8ad70f3
    ip: 93.184.216.119
    state: absent

- name: allocate a new elastic IP and associate it with an instance
  amazon.aws.ec2_eip:
    device_id: i-1212f003

- name: allocate a new elastic IP without associating it to anything
  amazon.aws.ec2_eip:
    state: present
  register: eip

- name: output the IP
  ansible.builtin.debug:
    msg: "Allocated IP is {{ eip.public_ip }}"

- name: provision new instances with ec2
  amazon.aws.ec2:
    keypair: mykey
    instance_type: c1.medium
    image: ami-40603AD1
    wait: true
    group: webserver
    count: 3
  register: ec2

- name: associate new elastic IPs with each of the instances
  amazon.aws.ec2_eip:
    device_id: "{{ item }}"
  loop: "{{ ec2.instance_ids }}"

- name: allocate a new elastic IP inside a VPC in us-west-2
  amazon.aws.ec2_eip:
    region: us-west-2
    in_vpc: true
  register: eip

- name: output the IP
  ansible.builtin.debug:
    msg: "Allocated IP inside a VPC is {{ eip.public_ip }}"

- name: allocate eip - reuse unallocated ips (if found) with FREE tag
  amazon.aws.ec2_eip:
    region: us-east-1
    in_vpc: true
    reuse_existing_ip_allowed: true
    tag_name: FREE

- name: allocate eip - reuse unallocated ips if tag reserved is nope
  amazon.aws.ec2_eip:
    region: us-east-1
    in_vpc: true
    reuse_existing_ip_allowed: true
    tag_name: reserved
    tag_value: nope

- name: allocate new eip - from servers given ipv4 pool
  amazon.aws.ec2_eip:
    region: us-east-1
    in_vpc: true
    public_ipv4_pool: ipv4pool-ec2-0588c9b75a25d1a02

- name: allocate eip - from a given pool (if no free addresses where dev-servers tag is dynamic)
  amazon.aws.ec2_eip:
    region: us-east-1
    in_vpc: true
    reuse_existing_ip_allowed: true
    tag_name: dev-servers
    public_ipv4_pool: ipv4pool-ec2-0588c9b75a25d1a02

- name: allocate eip from pool - check if tag reserved_for exists and value is our hostname
  amazon.aws.ec2_eip:
    region: us-east-1
    in_vpc: true
    reuse_existing_ip_allowed: true
    tag_name: reserved_for
    tag_value: "{{ inventory_hostname }}"
    public_ipv4_pool: ipv4pool-ec2-0588c9b75a25d1a02

- name: create new IP and modify it's reverse DNS record
  amazon.aws.ec2_eip:
    state: present
    domain_name: test-domain.xyz

- name: Modify reverse DNS record of an existing EIP
  amazon.aws.ec2_eip:
    public_ip: 44.224.84.105
    domain_name: test-domain.xyz
    state: present

- name: Remove reverse DNS record of an existing EIP
  amazon.aws.ec2_eip:
    public_ip: 44.224.84.105
    domain_name: ""
    state: present

返回值

常见返回值已在此处记录，以下是此模块特有的字段

键

描述

allocation_id

字符串

弹性IP的分配ID。

返回值：成功时

示例："eipalloc-51aa3a6c"

public_ip

字符串

弹性IP地址。

返回值：成功时

示例："52.88.159.209"

update_reverse_dns_record_result

字典

关于更新反向DNS记录操作结果的信息。

返回值：当指定domain_name时。

地址

字典

关于弹性IP地址的信息。

返回值： 始终返回

allocation_id

字符串

分配ID。

返回值： 始终返回

示例： "eipalloc-00a11aa111aaa1a11"

ptr_record

字符串

IP地址的指针 (PTR) 记录。

返回值： 始终返回

示例： "ec2-11-22-33-44.us-east-2.compute.amazonaws.com."

ptr_record_update

字典

IP地址更新后的PTR记录。

返回值： 始终返回

状态

字符串

PTR记录更新的状态。

返回值： 始终返回

示例： "PENDING"

值

字符串

PTR记录更新的值。

返回值： 始终返回

示例： "example.com"

public_ip

字符串

公有IP地址。

返回值： 始终返回

示例： "11.22.33.44"

作者

  • Rick Mendes (@rickmendes)