Модуль amazon.aws.s3_object — управление объектами в S3

Примечание

Этот модуль входит в коллекцию amazon.aws (версия 11.3.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install amazon.aws. Для использования этого модуля могут потребоваться дополнительные зависимости; подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: amazon.aws.s3_object.

Добавлено в amazon.aws 1.0.0

Краткое описание
Требования
Параметры
Примечания
Примеры
Возвращаемые значения

Краткое описание

Этот модуль позволяет управлять объектами и каталогами в сегментах S3. Поддерживается создание и удаление объектов и каталогов, получение объектов в виде файлов или строк, создание ссылок для скачивания и копирование объектов, уже хранящихся в Amazon S3.
Создавать и удалять сегменты S3 можно с помощью модуля amazon.aws.s3_bucket.
Совместим с AWS, DigitalOcean, Ceph, Walrus, FakeS3 и StorageGRID.
При использовании служб, отличных от AWS, необходимо указать endpoint_url.

Примечание

Этому модулю соответствует плагин действий.

Псевдонимы: aws_s3

Требования

На узле, выполняющем этот модуль, должны быть установлены следующие компоненты.

python >= 3.6
boto3 >= 1.35.0
botocore >= 1.35.0

Параметры

Параметр	Комментарии
access_key псевдонимы: aws_access_key_id, aws_access_key строка	Идентификатор ключа доступа AWS. Дополнительные сведения о токенах доступа см. в документации 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` в порядке убывания приоритета. Параметры aws_access_key и profile являются взаимоисключающими. Псевдоним aws_access_key_id добавлен в выпуске 5.1.0 для согласованности с AWS botocore SDK.
aws_ca_bundle путь	Расположение пакета сертификатов центра сертификации, используемого для проверки SSL-сертификатов. Также можно использовать переменную среды `AWS_CA_BUNDLE`.
aws_config словарь	Словарь для изменения конфигурации botocore. Параметры приведены в документации AWS https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config.
bucket строка / обязательный	Имя бакета.
ceph псевдонимы: rgw логическое значение	Включить совместимость API с Ceph RGW. Учитывает подмножество API S3, работающее с Ceph, чтобы по возможности обеспечить такое же поведение модуля. Требуется `endpoint_url`, если `ceph=true`. Варианты: `false` ← (по умолчанию) `true`
content строка добавлено в amazon.aws 1.3.0	Содержимое, которое нужно `put` в объект. Значение параметра будет обработано как строка и преобразовано в UTF-8 перед отправкой в S3. Для отправки двоичных данных используйте вместо этого параметр `content_base64`. При указании `mode=put` необходимо задать один из параметров: `content`, `content_base64` или `src`; в противном случае параметр игнорируется.
content_base64 строка добавлено в amazon.aws 1.3.0	Двоичные данные в кодировке base64, которые нужно `put` в объект. Используйте этот параметр, если нужно поместить необработанные двоичные данные, и не забудьте закодировать их в base64. При указании `mode=put` необходимо задать один из параметров: `content`, `content_base64` или `src`; в противном случае параметр игнорируется.
copy_src словарь добавлено в amazon.aws 2.0.0	Сведения об исходном объекте для копирования. Обязательно, если `mode=copy`.
bucket строка / обязательный	Имя исходного бакета.
object строка	Имя ключа исходного объекта. Если не указано, все объекты `copy_src.bucket` будут скопированы в указанный бакет.
prefix строка добавлено в amazon.aws 6.2.0	Скопировать все ключи, начинающиеся с указанного префикса. Игнорируется, если задан `copy_src.object`. По умолчанию: `""`
version_id строка	Идентификатор версии исходного объекта.
debug_botocore_endpoint_logs логическое значение	Использовать регистратор `botocore.endpoint` для анализа уникальных (а не общих) вызовов API `"resource:action"`, выполненных во время задачи, и вывода их набора в ключ resource_actions результатов задачи. Используйте callback `aws_resource_action` для вывода общего списка вызовов, выполненных за время выполнения плейбука. Также можно использовать переменную среды `ANSIBLE_DEBUG_BOTOCORE_LOGS`. Варианты: `false` ← (по умолчанию) `true`
dest путь	Путь к файлу назначения при загрузке объекта/ключа, если `mode=get`. Игнорируется, если `mode` не равно `get`.
dualstack логическое значение	Включает конечные точки Amazon S3 Dual-Stack, позволяя обмениваться данными с S3 по IPv4 и IPv6. Поддержка одновременной передачи `dualstack` и `endpoint_url` объявлена устаревшей; конечные точки dualstack автоматически настраиваются с использованием заданного `region`. Поддержка будет удалена в выпуске после 2024-12-01. Варианты: `false` ← (по умолчанию) `true`
encrypt логическое значение	Запрашивает шифрование объектов на стороне сервера при `mode=put` или `mode=copy`. Игнорируется, если `mode` не равно ни `put`, ни `copy`. Варианты: `false` `true` ← (по умолчанию)
encryption_kms_key_id строка	Идентификатор ключа KMS для шифрования объектов с использованием `encryption_mode=aws:kms`. Игнорируется, если `encryption_mode` не равно `aws:kms`.
encryption_mode строка	Режим шифрования, используемый при `encrypt=true`. Варианты: `"AES256"` ← (по умолчанию) `"aws:kms"`
endpoint_url псевдонимы: aws_endpoint_url строка	URL для подключения вместо конечных точек AWS по умолчанию. Хотя этот параметр можно использовать для подключения к другим сервисам, совместимым с AWS, коллекции amazon.aws и community.aws тестируются только с AWS. Также можно использовать переменную среды `AWS_URL`.
expected_bucket_owner строка добавлено в amazon.aws 8.2.0	Идентификатор учетной записи предполагаемого владельца бакета. Если указанный идентификатор учетной записи не совпадает с фактическим владельцем бакета, запрос завершается ошибкой с кодом состояния HTTP 403 Forbidden (доступ запрещен).
expiry псевдонимы: expiration целое число	Срок действия (в секундах) URL, создаваемого и возвращаемого S3/Walrus при выполнении операции `mode=put` или `mode=geturl`. Игнорируется, если `mode` не равно ни `put`, ни `geturl`. По умолчанию: `600`
headers словарь	Пользовательские заголовки, используемые при `mode=put`, в виде словаря пар «ключ — значение». Ключи, соответствующие поддерживаемым аргументам объекта S3, переносятся на верхний уровень ExtraArgs. Поддерживаются такие ключи, как `ContentType`, `Content-Disposition`, `ContentEncoding`, `ContentLanguage`, `CacheControl`, `Expires`, `ACL`, `GrantFullControl`, `GrantRead`, `GrantReadACP`, `GrantWriteACP`, `StorageClass`, `ServerSideEncryption`, `SSECustomerAlgorithm`, `SSECustomerKey`, `SSECustomerKeyMD5`, `SSEKMSKeyId` и `WebsiteRedirectLocation`. Остальные ключи сохраняются в `Metadata`. Поддерживаются оба стиля имен заголовков: `ContentType` и `Content-Type`. Варианты с подчеркиванием, например `content_type`, не переносятся и помещаются в `Metadata`. Если `ContentType` не задан, при загрузке из файла тип определяется по `src`. При загрузке с использованием `content` или `content_base64` по умолчанию используется `binary/octet-stream`. Игнорируется, если `mode` не равно `put`.
ignore_nonexistent_bucket логическое значение	Переопределяет первоначальную проверку бакета на случай ограничений политик бакета или IAM. Это может быть полезно, если у пользователя есть разрешение `GetObject`, но нет других разрешений. В таком случае использование `mode=get` завершится ошибкой, если не указан параметр `ignore_nonexistent_bucket=true`. Варианты: `false` ← (по умолчанию) `true`
marker строка	Указывает ключ, с которого нужно начать при использовании режима списка. Ключи объектов возвращаются в алфавитном порядке, начиная с ключа, следующего за маркером.
max_keys целое число	Максимальное количество результатов, возвращаемых при `mode=list` Если значение не задано, возвращаются все ключи. Игнорируется, если `mode` не равно `list`.
metadata словарь	Метаданные, используемые при `mode=copy`, `mode=create` или `mode=put`, в виде словаря пар «ключ — значение». Ключи, соответствующие поддерживаемым аргументам объекта S3, переносятся на верхний уровень ExtraArgs (например, `ContentType`). Остальные ключи применяются как пользовательские метаданные в `Metadata`.
mode строка / обязательный	Переключает поведение модуля между режимами `put`: загрузка `get`: скачивание `geturl`: возврат URL для скачивания `getstr`: скачивание объекта в виде строки `list`: перечисление ключей `create`: создание каталогов бакета `delobj`: удаление объекта `copy`: копирование объекта, уже сохраненного в другом бакете Поддержка создания и удаления бакетов удалена в выпуске 6.0.0. Для создания бакета и управления им используйте модуль amazon.aws.s3_bucket. Поддержка `list` объявлена устаревшей и будет удалена в выпуске после 2026-11-01. Вместо `list` следует использовать модуль amazon.aws.s3_object_info. Варианты: `"get"` `"put"` `"create"` `"geturl"` `"getstr"` `"delobj"` `"list"` `"copy"`
object строка	Имя ключа объекта в бакете. Можно использовать для создания «виртуальных каталогов», см. примеры. Имена ключей объектов не должны начинаться с `/`. Дополнительные сведения см. по ссылке https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html.
overwrite псевдонимы: force строка	Принудительно перезаписывать файл локально в файловой системе или удаленно — объект/ключ. Используется при `mode=put` или `mode=get`. Игнорируется, если `mode` не равно ни `put`, ни `get`. Значение должно быть логическим, `always`, `never`, `different` или `latest`. `true` означает то же, что и `always`. `false` равнозначно `never`. Если задано значение `different`, MD5-сумма локального файла сравнивается со значением «ETag» объекта/ключа в S3. ETag может быть MD5-хешем данных объекта, но это не гарантируется. См. заголовок ответа ETag здесь: https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html. При значениях `mode=get` и `overwrite=latest` отметка времени последнего изменения локального файла сравнивается со значением «LastModified» объекта/ключа в S3. По умолчанию: `"different"`
permission список / элементы=строка	Этот параметр позволяет пользователю задать предустановленные разрешения для создаваемого объекта/бакета. Для бакета можно задать разрешения `private`, `public-read`, `public-read-write`, `authenticated-read`, а для объекта — `private`, `public-read`, `public-read-write`, `aws-exec-read`, `authenticated-read`, `bucket-owner-read`, `bucket-owner-full-control`. Можно указать несколько разрешений в виде списка, однако при первоначальной загрузке файла будет использовано только первое. Полный список разрешений см. в документации AWS https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl. Варианты: `"private"` ← (по умолчанию) `"public-read"` `"public-read-write"` `"aws-exec-read"` `"authenticated-read"` `"bucket-owner-read"` `"bucket-owner-full-control"` По умолчанию: `["private"]`
prefix строка	В режиме списка ограничивает ответ ключами, начинающимися с указанного префикса. По умолчанию: `""`
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 и session_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 строка	Регион AWS. Для глобальных сервисов, таких как IAM, Route53 и CloudFront, параметр region игнорируется. Также можно использовать переменную среды `AWS_REGION`. Дополнительные сведения см. в документации Amazon AWS http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region.
retries псевдонимы: retry целое число	Количество повторных попыток при устранимой ошибке до окончательного завершения с ошибкой. По умолчанию: `0`
secret_key псевдонимы: aws_secret_access_key, aws_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` в порядке убывания приоритета. Параметры secret_key и profile являются взаимоисключающими. Псевдоним aws_secret_access_key добавлен в выпуске 5.1.0 для согласованности с AWS botocore SDK.

session_token псевдонимы: aws_session_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`. Параметры session_token и profile являются взаимоисключающими.
sig_v4 логическое значение добавлено в amazon.aws 5.0.0	Принудительно использует в Boto SDK Signature Version 4. Применяется только к режимам получения, `mode=get`, `mode=getstr`, `mode=geturl`. Варианты: `false` `true` ← (по умолчанию)
src путь	Путь к исходному файлу при выполнении операции `put`. Если не задан параметр `mode=put`, необходимо указать один из параметров `content`, `content_base64` или `src`; в противном случае он игнорируется.
tags псевдонимы: resource_tags словарь	Словарь, представляющий теги, которые будут применены к ресурсу. Если параметр `tags` не задан, теги не изменяются.
validate_bucket_name логическое значение добавлено в amazon.aws 3.1.0	Проверять ли соответствие имени бакета правилам именования AWS S3. По умолчанию проверка включена; ее можно отключить для серверных систем S3, которые не применяют эти правила. Дополнительные сведения о правилах именования бакетов см. в документации Amazon: https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html. Варианты: `false` `true` ← (по умолчанию)
validate_certs логическое значение	Если задано значение `false`, SSL-сертификаты не будут проверяться при взаимодействии с API AWS. Настоятельно не рекомендуется задавать validate_certs=false; вместо этого рассмотрите возможность указать aws_ca_bundle. Варианты: `false` `true` ← (по умолчанию)
version строка	Идентификатор версии объекта в бакете. Можно использовать, чтобы получить определенную версию файла, если в целевом бакете включено версионирование.

Примечания

Примечание

Поддержка tags и purge_tags добавлена в выпуске 2.0.0.
Для Walrus значение endpoint_url следует задать равным FQDN конечной точки без схемы и пути.
Поддержка создания и удаления бакетов удалена в выпуске 6.0.0.
Внимание: Для модулей переменные окружения и файлы конфигурации считываются из контекста Ansible «host», а не из контекста «controller». Поэтому файлы может потребоваться явно скопировать на «host». Для плагинов поиска и подключения переменные окружения и файлы конфигурации считываются из контекста Ansible «controller», а не из контекста «host».
Используемый Ansible пакет AWS SDK (boto3) также может считывать значения по умолчанию для учетных данных и других параметров, например региона, из файлов конфигурации в контексте Ansible «host» (обычно ~/.aws/credentials). Дополнительные сведения см. по адресу https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html.

Примеры

- name: Simple PUT operation
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put

- name: PUT operation from a rendered template
  amazon.aws.s3_object:
    bucket: mybucket
    object: /object.yaml
    content: "{{ lookup('template', 'templates/object.yaml.j2') }}"
    mode: put

- name: PUT content with explicit ContentType and ContentDisposition
  amazon.aws.s3_object:
    bucket: mybucket
    object: /index.html
    content: "<html>Hello</html>\n"
    mode: put
    headers:
      ContentType: "text/html; charset=utf-8"
      ContentDisposition: inline

- name: Simple PUT operation in Ceph RGW S3
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put
    ceph: true
    endpoint_url: "http://localhost:8000"

- name: Simple GET operation
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    dest: /usr/local/myfile.txt
    mode: get

- name: Get a specific version of an object.
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    version: 48c9ee5131af7a716edc22df9772aa6f
    dest: /usr/local/myfile.txt
    mode: get

- name: PUT/upload with metadata
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put
    metadata:
      Content-Encoding: gzip
      Cache-Control: no-cache

- name: PUT/upload with custom headers
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put
    headers:
      GrantFullControl: "emailAddress=owner@example.com"

- name: List keys simple
  amazon.aws.s3_object:
    bucket: mybucket
    mode: list

- name: List keys all options
  amazon.aws.s3_object:
    bucket: mybucket
    mode: list
    prefix: /my/desired/
    marker: /my/desired/0023.txt
    max_keys: 472

- name: GET an object but don't download if the file checksums match. New in 2.0
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    dest: /usr/local/myfile.txt
    mode: get
    overwrite: different

- name: Delete an object from a bucket
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    mode: delobj

- name: Copy an object already stored in another bucket
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    mode: copy
    copy_src:
      bucket: srcbucket
      object: /source/key.txt

- name: Copy all the objects with name starting with 'ansible_'
  amazon.aws.s3_object:
    bucket: mybucket
    mode: copy
    copy_src:
      bucket: srcbucket
      prefix: 'ansible_'

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
contents строка	Содержимое объекта в виде строки. Возвращается: (для операции getstr) Пример: `"Hello, world!"`
expiry целое число	Количество секунд, в течение которых действителен предварительно подписанный URL. Возвращается: (для операции geturl) Пример: `600`
msg строка	Сообщение о состоянии операции. Возвращается: всегда Пример: `"PUT operation complete"`
s3_keys список / элементы=строка	Список ключей объектов. Возвращается: (для операции list) Пример: `["prefix1/", "prefix1/key1", "prefix1/key2"]`
tags словарь	Теги объекта S3. Возвращается: всегда Пример: `{"Owner": "dev001", "env": "test"}`
url строка	URL объекта. Возвращается: (для операций put и geturl) Пример: `"https://my-bucket.s3.amazonaws.com/my-key.txt?AWSAccessKeyId=<access-key>&Expires=1506888865&Signature=<signature>"`

Авторы

Lester Wade (@lwade)
Sloane Hertel (@s-hertel)
Alina Buzachis (@alinabuzachis)

Ссылки коллекции

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/amazon/aws/s3_object_module.html