amazon.aws.s3_bucket 模块 – 在 AWS、DigitalOcean、Ceph、Walrus、FakeS3 和 StorageGRID 中管理 S3 存储桶

注意

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

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

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

要在 playbook 中使用它,请指定:amazon.aws.s3_bucket

amazon.aws 1.0.0 中的新增功能

概要

  • 管理 S3 存储桶。

  • 兼容 AWS、DigitalOcean、Ceph、Walrus、FakeS3 和 StorageGRID。

  • 使用非 AWS 服务时,应指定 endpoint_url

要求

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

  • python >= 3.6

  • boto3 >= 1.28.0

  • botocore >= 1.31.0

参数

参数

注释

accelerate_enabled

布尔值

amazon.aws 8.1.0 中新增

启用 Amazon S3 传输加速,发送的数据将通过优化的网络路径路由到 Amazon S3。

AWS GovCloud (美国) 中不提供传输加速。

请参见 https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-s3.html#govcloud-S3-diffs

选项

  • false

  • true

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_IDAWS_ACCESS_KEYEC2_ACCESS_KEY 环境变量。

aws_access_keyprofile 选项是互斥的。

aws_access_key_id 别名在 5.1.0 版本中添加,以与 AWS botocore SDK 保持一致。

ec2_access_key 别名已被弃用,并将在 2024-12-01 后的某个版本中移除。

EC2_ACCESS_KEY 环境变量的支持已被弃用,并将在 2024-12-01 后的某个版本中移除。

acl

字符串

amazon.aws 3.1.0 中新增

要应用于存储桶的预定义 ACL。

如果您的存储桶对 S3 对象所有权使用存储桶所有者强制设置,则 ACL 将被禁用,并且不再影响权限。

选项

  • "private"

  • "public-read"

  • "public-read-write"

  • "authenticated-read"

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

bucket_key_enabled

布尔值

amazon.aws 4.1.0 中新增

为新对象上的 SSE-KMS 启用 S3 存储桶密钥。

有关更多信息,请参见 AWS 文档 https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html

只有在 encryption=aws:kms 时才支持存储桶密钥加密。

选项

  • false

  • true

ceph

别名:rgw

布尔值

启用与 Ceph RGW 的 API 兼容性。

它考虑了与 Ceph 配合使用的 S3 API 子集,以便在可能的情况下提供相同的模块行为。

如果 ceph=true,则需要 endpoint_url

选项

  • false ← (默认)

  • true

debug_botocore_endpoint_logs

布尔值

使用 botocore.endpoint 日志记录器来解析任务期间进行的唯一(而不是全部)"resource:action" API 调用,并将集合输出到任务结果中的 resource_actions 密钥。使用 aws_resource_action 回调函数将结果输出到 playbook 期间进行的全部列表。

也可以使用 ANSIBLE_DEBUG_BOTOCORE_LOGS 环境变量。

选项

  • false ← (默认)

  • true

delete_object_ownership

布尔值

amazon.aws 2.0.0 版本中添加

删除存储桶的所有权控制。

此选项不能与 object_ownership 定义一起使用。

选项

  • false ← (默认)

  • true

delete_public_access

布尔值

amazon.aws 1.3.0 版本中添加

从存储桶中删除公共访问块配置。

此选项不能与 public_access 定义一起使用。

选项

  • false ← (默认)

  • true

dualstack

布尔值

amazon.aws 6.0.0 版本中添加

启用 Amazon S3 双栈端点,允许使用 IPv4 和 IPv6 进行 S3 通信。

endpoint_url 互斥。

选项

  • false ← (默认)

  • true

encryption

字符串

描述应用于存储桶中新对象的默认服务器端加密。要删除服务器端加密,需要显式将加密设置为“none”。

注意:自 2023 年 1 月起,Amazon S3 不支持禁用 S3 存储桶上的加密。

选项

  • "none"

  • "AES256"

  • "aws:kms"

encryption_key_id

字符串

用于默认加密的 KMS 主密钥 ID。

如果未指定,则默认为 AWS 提供的 KMS 密钥。

只有当 encryptionaws:kms 时才支持此参数。

endpoint_url

别名:ec2_url、aws_endpoint_url、s3_url

字符串

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

也可以使用 AWS_URLEC2_URL 环境变量,优先级依次递减。

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

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

force

布尔值

尝试删除存储桶时,先删除存储桶中的所有键(包括版本和删除标记)(要成功删除,S3 存储桶必须为空)。

选项

  • false ← (默认)

  • true

inventory

列表 / 元素=字典

启用 S3 库存,每天或每周保存对象的列表及其对应的元数据。

destination

字典 / 必需

包含有关在何处发布库存结果的信息。

account_id

字符串

拥有目标 S3 存储桶的帐户 ID。如果未提供帐户 ID,则在导出数据之前不会验证所有者。

bucket

字符串 / 必需

将发布库存结果的存储桶的 Amazon 资源名称 (ARN)。

format

字符串 / 必需

指定库存结果的输出格式。

选项

  • "CSV"

  • "ORC"

  • "Parquet"

prefix

字符串

添加到所有库存结果之前的字首。

filter

字符串

对象必须具有的前缀才能包含在库存结果中。

id

字符串 / 必需

用于标识库存配置的 ID。

included_object_versions

字符串 / 必需

要包含在库存列表中的对象版本。如果设置为“全部”,则列表包含所有对象版本,这会将版本相关的字段 VersionId、IsLatest 和 DeleteMarker 添加到列表中。如果设置为“当前”,则列表不包含这些版本相关的字段。

选项

  • "All"

  • "Current"

optional_fields

列表 / 元素=字符串

包含包含在库存结果中的可选字段。

选项

  • "Size"

  • "LastModifiedDate"

  • "StorageClass"

  • "ETag"

  • "IsMultipartUploaded"

  • "ReplicationStatus"

  • "EncryptionStatus"

  • "ObjectLockRetainUntilDate"

  • "ObjectLockMode"

  • "ObjectLockLegalHoldStatus"

  • "IntelligentTieringAccessTier"

  • "BucketKeyStatus"

  • "ChecksumAlgorithm"

  • "ObjectAccessControlList"

  • "ObjectOwner"

schedule

字符串 / 必需

指定生成库存结果的计划。

选项

  • "Daily"

  • "Weekly"

name

字符串 / 必需

S3 存储桶的名称。

object_lock_default_retention

字典

amazon.aws 8.1.0 中新增

默认对象锁定配置,默认情况下将应用于放置在指定存储桶中的每个新对象。

必须包含 object_lock_enabled 并将其设置为 True

无法移除对象锁定保留策略。

days

整数

您要为默认保留期限指定的日期数。

object_lock_default_retention.years 互斥。

mode

字符串 / 必需

保留模式的类型。

选项

  • "GOVERNANCE"

  • "COMPLIANCE"

years

整数

您要为默认保留期限指定的年数。

object_lock_default_retention.days 互斥。

object_lock_enabled

布尔值

amazon.aws 5.3.0 版本中添加

是否启用 S3 对象锁定。

创建新存储桶时默认为 false

选项

  • false

  • true

object_ownership

字符串

amazon.aws 2.0.0 版本中添加

允许存储桶的所有权控制。

BucketOwnerEnforced - ACL 已禁用,不再影响对您存储桶的访问权限。设置或更新 ACL 的请求将失败。但是,读取 ACL 的请求受支持。存储桶所有者拥有完全所有权和控制权。对象写入者不再拥有完全所有权和控制权。

BucketOwnerPreferred - 如果使用存储桶所有者完全控制的预定义 ACL 上传对象,则上传到存储桶的对象所有权将更改为存储桶所有者。

ObjectWriter - 如果使用存储桶所有者完全控制的预定义 ACL 上传对象,则上传帐户将拥有该对象。

此选项不能与 delete_object_ownership 定义一起使用。

BucketOwnerEnforced 已在 3.2.0 版本中添加。

注意:在 2023 年 4 月底,Amazon 将默认设置更新为 BucketOwnerEnforced

选项

  • "BucketOwnerEnforced"

  • "BucketOwnerPreferred"

  • "ObjectWriter"

policy

json

JSON 策略(字符串)。设置为字符串 "null" 以强制策略不存在。

profile

别名:aws_profile

字符串

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

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

也可以使用 AWS_PROFILE 环境变量。

profile 选项与 aws_access_keyaws_secret_keysecurity_token 选项互斥。

public_access

字典

amazon.aws 1.3.0 版本中添加

配置 S3 存储桶的公共访问块。

此选项不能与 delete_public-access 一起使用。

注意:在 2023 年 4 月底,Amazon 更新了默认设置,默认情况下阻止公共访问。虽然此模块的默认值保持不变,但仍需要显式传递 public_access 参数才能启用公共访问 ACL。

block_public_acls

布尔值

设置 BlockPublicAcls 值。

选项

  • false ← (默认)

  • true

block_public_policy

布尔值

设置 BlockPublicPolicy 值。

选项

  • false ← (默认)

  • true

ignore_public_acls

布尔值

设置 IgnorePublicAcls 值。

选项

  • false ← (默认)

  • true

restrict_public_buckets

布尔值

设置 RestrictPublicAcls 值。

选项

  • false ← (默认)

  • true

purge_tags

布尔值

如果 purge_tags=truetags 已设置,则将从资源中清除现有标签,以完全匹配 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 等全球服务,将忽略区域

也可以使用 AWS_REGIONEC2_REGION 环境变量。

更多信息,请参见 Amazon AWS 文档 http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region

ec2_region 别名已弃用,将在 2024 年 12 月 1 日后的版本中移除。

EC2_REGION 环境变量的支持已弃用,将在 2024 年 12 月 1 日后的版本中移除。

requester_pays (请求者付费)

布尔值

对于请求者付费存储桶,请求者而不是存储桶所有者将支付请求成本和从存储桶下载数据所需的费用。

选项

  • 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_KEYAWS_SECRET_KEYEC2_SECRET_KEY 环境变量(按优先级递减顺序)。

secret_keyprofile 选项互斥。

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

ec2_secret_key 别名已弃用,将在 2024 年 12 月 1 日后的版本中移除。

EC2_SECRET_KEY 环境变量的支持已弃用,将在 2024 年 12 月 1 日后的版本中移除。

会话令牌 (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_TOKENAWS_SECURITY_TOKENEC2_SECURITY_TOKEN 环境变量(按优先级递减顺序)。

security_tokenprofile 选项互斥。

在 3.2.0 版本中添加了 aws_session_tokensession_token 别名,在 6.0.0 版本中将参数名称从 security_token 重命名为 session_token

security_tokenaws_security_tokenaccess_token 别名已弃用,将在 2024 年 12 月 1 日后的版本中移除。

EC2_SECRET_KEYAWS_SECURITY_TOKEN 环境变量的支持已弃用,将在 2024 年 12 月 1 日后的版本中移除。

状态 (state)

字符串

创建或删除 S3 存储桶。

选项

  • "present" ← (默认)

  • "absent" (不存在)

标签 (tags)

别名:resource_tags

字典

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

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

validate_bucket_name (验证存储桶名称)

布尔值

amazon.aws 3.1.0 中新增

是否应验证存储桶名称是否符合 AWS S3 命名规则。

默认情况下启用,对于不强制执行这些规则的 S3 后端,可以禁用此功能。

请参见 https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html

选项

  • false

  • true ← (默认)

validate_certs (验证证书)

布尔值

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

强烈建议不要设置 validate_certs=false,作为替代方案,请考虑设置 aws_ca_bundle

选项

  • false

  • true ← (默认)

版本控制 (versioning)

布尔值

启用或禁用版本控制(请注意,启用版本控制后,只能将其暂停)。

选项

  • false

  • true

备注

注意

  • 如果端点未实现 requestPaymentpolicytaggingversioning 操作/API,则如果每个参数都满足以下条件,模块不会失败。 requester_paysfalsepolicytagsversioningNone

  • 在 5.0.0 版本中,s3_url 参数已合并到 endpoint_url 参数中,s3_url 保留为 endpoint_url 的别名。

  • 对于 Walrus,endpoint_url 应设置为端点的 FQDN,不包含方案或路径。

  • S3_URL 环境变量的支持已弃用,将在 2024 年 12 月 1 日后的版本中移除,请使用 endpoint_url 参数或 AWS_URL 环境变量。

  • 警告:对于模块,环境变量和配置文件是从 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.

# Create a simple S3 bucket
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present

# Create a simple S3 bucket on Ceph Rados Gateway
- amazon.aws.s3_bucket:
    name: mys3bucket
    endpoint_url: http://your-ceph-rados-gateway-server.xxx
    ceph: true

# Remove an S3 bucket and any keys it contains
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: absent
    force: true

# Create a bucket, add a policy from a file, enable requester pays, enable versioning and tag
- amazon.aws.s3_bucket:
    name: mys3bucket
    policy: "{{ lookup('file','policy.json') }}"
    requester_pays: true
    versioning: true
    tags:
      example: tag1
      another: tag2

# Create a simple DigitalOcean Spaces bucket using their provided regional endpoint
- amazon.aws.s3_bucket:
    name: mydobucket
    endpoint_url: 'https://nyc3.digitaloceanspaces.com'

# Create a bucket with AES256 encryption
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    encryption: "AES256"

# Create a bucket with aws:kms encryption, KMS key
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    encryption: "aws:kms"
    encryption_key_id: "arn:aws:kms:us-east-1:1234/5678example"

# Create a bucket with aws:kms encryption, Bucket key
- amazon.aws.s3_bucket:
    name: mys3bucket
    bucket_key_enabled: true
    encryption: "aws:kms"

# Create a bucket with aws:kms encryption, default key
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    encryption: "aws:kms"

# Create a bucket with public policy block configuration
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    public_access:
      block_public_acls: true
      ignore_public_acls: true
      ## keys == 'false' can be omitted, undefined keys defaults to 'false'
      # block_public_policy: false
      # restrict_public_buckets: false

# Delete public policy block from bucket
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    delete_public_access: true

# Create a bucket with object ownership controls set to ObjectWriter
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    object_ownership: ObjectWriter

# Delete onwership controls from bucket
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    delete_object_ownership: true

# Delete a bucket policy from bucket
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    policy: "null"

# This example grants public-read to everyone on bucket using ACL
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    acl: public-read

# Enable transfer acceleration
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    accelerate_enabled: true

# Default Object Lock retention
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    object_lock_enabled: true
    object_lock_default_retention:
      mode: governance
      days: 1
# Bucket with inventory configuration:
- amazon.aws.s3_bucket:
    name: mys3bucket
    state: present
    inventory:
      - id: mys3bucket-inventory-id
        destination:
          bucket: "arn:aws:s3:::mys3inventorybucket"
        optional_fields:
          - "Size"
        included_object_versions: "All"
        schedule: "Weekly"

返回值

公共返回值已在此处记录 此处,以下是此模块特有的字段

键 (Key)

描述

accelerate_enabled

布尔值

S3 存储桶加速状态。

返回: state=present

示例: true

acl

字典

S3存储桶的预设ACL。

返回:state=present 时。

示例: "public-read"

bucket_inventory

列表 / 元素=字符串

S3存储桶清单配置。

返回:state=present 时。

示例: [{"Destination": {"S3BucketDestination": {"Bucket": "arn:aws:s3:::9c2a337ba5fd64de777f499441f83093-inventory-target", "Format": "CSV"}}, "Id": "9c2a337ba5fd64de777f499441f83093-inventory-target", "IncludedObjectVersions": "All", "IsEnabled": true, "OptionalFields": [], "Schedule": {"Frequency": "Daily"}}]

encryption

字典

S3存储桶中对象的服务器端加密。

返回:state=present 时。

示例: {"SSEAlgorithm": "AES256"}

name

字符串

存储桶名称。

返回:state=present 时。

示例: "a-testing-bucket-name"

object_lock_default_retention

字典

S3存储桶的对象锁定保留策略。

返回:state=present 时。

示例: {"Days": 1, "Mode": "GOVERNANCE", "Years": 0}

object_lock_enabled

布尔值

是否启用了S3对象锁定。

返回:state=present 时。

示例: false

object_ownership

字符串

S3存储桶的所有权控制。

返回:state=present 时。

示例: "BucketOwnerPreferred"

policy

字典

S3存储桶的策略。

返回:state=present 时。

示例: {"Statement": [{"Action": "s3:GetObject", "Effect": "Allow", "Principal": "*", "Resource": "arn:aws:s3:::2d3ce10a8210d36d6b4d23b822892074complex/*", "Sid": "AddPerm"}], "Version": "2012-10-17"}

public_access_block

字典

存储桶公共访问块配置。

返回:state=present 时。

示例: {"PublicAccessBlockConfiguration": {"BlockPublicAcls": true, "BlockPublicPolicy": true, "IgnorePublicAcls": true, "RestrictPublicBuckets": true}}

PublicAccessBlockConfiguration

字典

此Amazon S3存储桶当前生效的PublicAccessBlock配置。

返回: 成功

BlockPublicAcls

布尔值

指定Amazon S3是否应阻止此存储桶和此存储桶中对象的公共访问控制列表(ACL)。

返回: 成功

BlockPublicPolicy

布尔值

指定Amazon S3是否应阻止此存储桶的公共存储桶策略。

返回: 成功

IgnorePublicAcls

布尔值

指定Amazon S3是否应忽略此存储桶和此存储桶中对象的公共ACL。

返回: 成功

RestrictPublicBuckets

布尔值

指定Amazon S3是否应限制此存储桶的公共存储桶策略。

返回: 成功

requester_pays (请求者付费)

布尔值

指示请求者已成功为请求付费。

返回:state=present 时。

示例: true

tags

字典

S3存储桶的标签。

返回:state=present 时。

示例: {"Tag1": "tag1", "Tag2": "tag2"}

版本控制 (versioning)

字典

S3存储桶的版本控制配置。

返回:state=present 时。

示例: {"MfaDelete": "Disabled", "Versioning": "Enabled"}

MfaDelete

字符串

指定在存储桶版本控制配置中是否启用了MFA删除。

返回:state=presnet 并且在存储桶上配置了MfaDelete时。

Versioning

字符串

存储桶的版本控制状态。

返回: 始终

作者

  • Rob White (@wimnat)

  • Aubin Bikouo (@abikouo)