amazon.aws.ec2_vpc_dhcp_option 模块 – 管理 DHCP 选项，并确保给定 VPC 的 DHCP 选项与请求的选项匹配

注意

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

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

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

要在剧本中使用它，请指定：amazon.aws.ec2_vpc_dhcp_option。

amazon.aws 1.0.0 中的新增功能

概要 

此模块删除或创建 DHCP 选项集，并可以将其关联到 VPC。
可以选择创建一个新的 DHCP 选项集，该选项集将 VPC 的现有 DHCP 选项集与提供的数值融合。
当提供 dhcp_options_id 时，模块将 1. 删除 (使用 state='absent') 2. 确保应用标签 (如果 state='present' 并且提供了标签) 3. 将其附加到 VPC (如果 state='present' 并且提供了 vpc_id)。
如果缺少任何可选值，它们将被视为无操作 (即，继承 VPC 已有的值)
要删除现有选项同时继承，请提供空值 (例如，如果要从 VPC 的选项中删除它们，则将 ntp_servers 设置为 [])

要求 

执行此模块的主机需要以下要求。

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_access_key_id 别名在 5.1.0 版本中添加，以与 AWS botocore SDK 保持一致。 ec2_access_key 别名已弃用，将在 2024-12-01 之后的一个版本中删除。 `EC2_ACCESS_KEY` 环境变量的支持已弃用，将在 2024-12-01 之后的一个版本中删除。
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` 回调将输出到剧本期间进行的总列表。也可以使用 `ANSIBLE_DEBUG_BOTOCORE_LOGS` 环境变量。选项 `false` ← (默认) `true`
delete_old 布尔值	关联新 VPC DHCP 选项集时是否删除旧的 VPC DHCP 选项集。这主要用于调试/开发目的，当您想要快速回滚到旧的选项集时。请注意，如果任何其他 VPC 正在使用此设置，则会忽略此设置，并且会保留旧的 DHCP 选项集。(否则，AWS 将返回错误。) 选项 `false` `true` ← (默认)
dhcp_options_id 字符串	现有 DHCP 选项集的 resource_id。如果指定了此参数，则它将覆盖其他设置，但标签除外 (标签将更新为匹配)。
dns_servers 列表 / 元素=字符串	用于将 VPC 的 DNS 服务器设置为 IP 地址列表。
domain_name 字符串	要在 DHCP 选项集中设置的域名。
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之后发布的版本中移除。
inherit_existing 布尔值	对于这些参数中未指定的任何DHCP选项，是从已应用于`vpc_id`的选项集中继承它们，还是将其重置为空。选项 `false` ← (默认) `true`
netbios_name_servers 列表 / 元素=字符串	要作为NetBIOS服务器公布的主机列表。
netbios_node_type 整数	要在DHCP选项中公布的NetBIOS节点类型。AWS建议使用2（使用NetBIOS名称服务时）https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_DHCP_Options.html
ntp_servers 列表 / 元素=字符串	要作为VPC的NTP服务器公布的主机列表。
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选项互斥。
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之后发布的版本中移除。
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 字符串	创建/分配或删除DHCP选项。如果将state设置为absent，则如果可能，将删除通过id或标签和选项匹配的DHCP选项集。选项 `“absent”` `"present"` ← (默认)
tags 别名：resource_tags 字典	表示要应用于资源的标签的字典。如果没有设置`tags`参数，则不会修改标签。
validate_certs 布尔值	设置为`false`时，将不会验证与AWS API通信的SSL证书。强烈建议不要设置validate_certs=false，可以考虑改为设置aws_ca_bundle。选项 `false` `true` ← (默认)
vpc_id 字符串	要与请求的DHCP选项集关联的VPC ID。如果没有提供VPC ID，并且没有找到匹配的选项集，则将创建一个新的DHCP选项集。

备注 

注意

在2.0.0版本中添加了对purge_tags的支持。
注意：对于模块，环境变量和配置文件是从Ansible“主机”上下文而不是“控制器”上下文读取的。因此，可能需要将文件显式复制到“主机”。对于查找和连接插件，环境变量和配置文件是从Ansible“控制器”上下文而不是“主机”上下文读取的。
Ansible使用的AWS SDK (boto3)也可能从Ansible“主机”上下文(通常为~/.aws/credentials)中的配置文件读取凭据和其他设置的默认值，例如区域。有关更多信息，请参阅https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html。

示例 

# Completely overrides the VPC DHCP options associated with VPC vpc-123456 and deletes any existing
# DHCP option set that may have been attached to that VPC.
- amazon.aws.ec2_vpc_dhcp_option:
    domain_name: "foo.example.com"
    region: us-east-1
    dns_servers:
      - 10.0.0.1
      - 10.0.1.1
    ntp_servers:
      - 10.0.0.2
      - 10.0.1.2
    netbios_name_servers:
      - 10.0.0.1
      - 10.0.1.1
    netbios_node_type: 2
    vpc_id: vpc-123456
    delete_old: true
    inherit_existing: false

# Ensure the DHCP option set for the VPC has 10.0.0.4 and 10.0.1.4 as the specified DNS servers, but
# keep any other existing settings. Also, keep the old DHCP option set around.
- amazon.aws.ec2_vpc_dhcp_option:
    region: us-east-1
    dns_servers:
      - "{{groups['dns-primary']}}"
      - "{{groups['dns-secondary']}}"
    vpc_id: vpc-123456
    inherit_existing: true
    delete_old: false

## Create a DHCP option set with 4.4.4.4 and 8.8.8.8 as the specified DNS servers, with tags
## but do not assign to a VPC
- amazon.aws.ec2_vpc_dhcp_option:
    region: us-east-1
    dns_servers:
      - 4.4.4.4
      - 8.8.8.8
    tags:
      Name: google servers
      Environment: Test

## Delete a DHCP options set that matches the tags and options specified
- amazon.aws.ec2_vpc_dhcp_option:
    region: us-east-1
    dns_servers:
      - 4.4.4.4
      - 8.8.8.8
    tags:
      Name: google servers
      Environment: Test
    state: absent

## Associate a DHCP options set with a VPC by ID
- amazon.aws.ec2_vpc_dhcp_option:
    region: us-east-1
    dhcp_options_id: dopt-12345678
    vpc_id: vpc-123456

返回值 

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

键	描述
changed 布尔值	DHCP选项是否已更改返回：始终
dhcp_config 字典	已创建、关联或找到的boto2风格的DHCP选项返回：可用时
domain-name 列表 / 元素=字符串	DHCP选项集中主机的域名返回：可用时示例：`["my.example.com"]`
domain-name-servers 列表 / 元素=字符串	最多四个域名服务器的IP地址，或AmazonProvidedDNS。返回：可用时示例：`["10.0.0.1", "10.0.1.1"]`
netbios-name-servers 列表 / 元素=字符串	最多四个NetBIOS名称服务器的IP地址。返回：可用时示例：`["10.0.0.1", "10.0.1.1"]`
netbios-node-type 字符串	NetBIOS节点类型（1、2、4或8）。返回：可用时示例：`"2"`
ntp-servers 列表 / 元素=字符串	最多四个网络时间协议(NTP)服务器的IP地址。返回：可用时示例：`["10.0.0.1", "10.0.1.1"]`
dhcp_options 字典	已创建、关联或找到的DHCP选项返回：可用时
dhcp_configurations 列表 / 元素=字符串	选项集的DHCP配置返回：成功示例：`["{\"key\": \"ntp-servers\", \"values\": [{\"value\": \"10.0.0.2\" , \"value\": \"10.0.1.2\"}]}", "{\"key\": \"netbios-name-servers\", \"values\": [{value\": \"10.0.0.1\"}, {\"value\": \"10.0.1.1\" }]}"]`
dhcp_options_id 字符串	已创建、找到或删除的主要DCHP选项集的aws资源ID 返回：成功示例：`"dopt-0955331de6a20dd07"`
owner_id 字符串	拥有DHCP选项集的AWS账户的ID。返回：成功示例：`"012345678912"`
tags 列表 / 元素=字符串	要应用于DHCP选项集的标签返回：成功示例：`["{\"Key\": \"CreatedBy\", \"Value\": \"ansible-test\"}", "{\"Key\": \"Collection\", \"Value\": \"amazon.aws\"}"]`
dhcp_options_id 字符串	已创建、找到或删除的主要DCHP选项集的aws资源ID 返回：可用时

作者

Joel Thompson (@joelthompson)