Ansible S3 Module: Upload, Download, Manage AWS S3 Objects (Complete Guide)

Ansible S3 Module: Upload, Download, Manage AWS S3 Objects (Complete Guide)

Ansible manages AWS S3 buckets and objects using the amazon.aws collection. Upload files, download objects, sync directories, and manage bucket policies — all from your playbooks.

See also: Ansible AWS: Complete Guide to Cloud Automation (2026)

Prerequisites

# Install the AWS collection
ansible-galaxy collection install amazon.aws
# Install Python dependencies
pip install boto3 botocore

Authentication

# Option 1: Environment variables (recommended)
# export AWS_ACCESS_KEY_ID=AKIA...
# export AWS_SECRET_ACCESS_KEY=...
# export AWS_REGION=us-east-1
# Option 2: In playbook (use vault for secrets)
- hosts: localhost
  vars:
    aws_access_key: "{{ vault_aws_access_key }}"
    aws_secret_key: "{{ vault_aws_secret_key }}"
    aws_region: us-east-1

Upload Files to S3

- name: Upload a file to S3
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: configs/app.conf
    src: /opt/myapp/app.conf
    mode: put
- name: Upload with metadata
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: "releases/myapp-{{ version }}.tar.gz"
    src: "/tmp/myapp-{{ version }}.tar.gz"
    mode: put
    metadata:
      version: "{{ version }}"
      deployed_by: ansible
- name: Upload with content type
  amazon.aws.s3_object:
    bucket: my-website-bucket
    object: index.html
    src: /opt/website/index.html
    mode: put
    content_type: text/html

Upload String Content

- name: Upload content directly
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: status/health.json
    content: '{"status": "healthy", "timestamp": "{{ ansible_date_time.iso8601 }}"}'
    mode: put
    content_type: application/json

See also: Ansible for AWS: Complete Guide to Cloud Automation with EC2, S3, RDS, and More

Download Files from S3

- name: Download a file from S3
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: configs/app.conf
    dest: /opt/myapp/app.conf
    mode: get
- name: Download and set permissions
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: "releases/myapp-{{ version }}.tar.gz"
    dest: "/opt/releases/myapp-{{ version }}.tar.gz"
    mode: get
  register: download_result
- name: Set file permissions after download
  ansible.builtin.file:
    path: "/opt/releases/myapp-{{ version }}.tar.gz"
    owner: deploy
    mode: '0644'

List Objects

- name: List objects in bucket
  amazon.aws.s3_object:
    bucket: my-app-bucket
    prefix: releases/
    mode: list
  register: s3_objects
- name: Show objects
  ansible.builtin.debug:
    msg: "{{ s3_objects.s3_keys }}"

See also: amazon.aws 10.3.1 Release: Bugfixes for S3, AutoScaling, KMS, and CloudFront

Delete Objects

- name: Delete a single object
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: temp/old-backup.tar.gz
    mode: delobj
- name: Delete old releases
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: "{{ item }}"
    mode: delobj
  loop: "{{ old_releases }}"

Manage S3 Buckets

- name: Create S3 bucket
  amazon.aws.s3_bucket:
    name: my-new-bucket
    state: present
    region: us-east-1
    versioning: true
    encryption: AES256
    tags:
      Environment: production
      Team: devops
- name: Enable bucket logging
  amazon.aws.s3_bucket:
    name: my-app-bucket
    state: present
    target_bucket: my-log-bucket
    target_prefix: s3-logs/my-app-bucket/
- name: Delete bucket
  amazon.aws.s3_bucket:
    name: old-bucket
    state: absent
    force: true  # Delete even if not empty

Sync Directories

- name: Sync local directory to S3
  amazon.aws.s3_sync:
    bucket: my-website-bucket
    file_root: /opt/website/public/
    permission: public-read
    delete: true  # Remove S3 objects not in local dir
    cache_control: "max-age=86400"
    include: "*.html,*.css,*.js,*.png,*.jpg"

Generate Pre-signed URLs

- name: Generate download URL (valid 1 hour)
  amazon.aws.s3_object:
    bucket: my-app-bucket
    object: releases/myapp-latest.tar.gz
    mode: geturl
    expiry: 3600
  register: presigned
- name: Share the URL
  ansible.builtin.debug:
    msg: "Download: {{ presigned.url }}"

Bucket Policy

- name: Set bucket policy for CloudFront
  amazon.aws.s3_bucket:
    name: my-website-bucket
    policy: |
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Sid": "CloudFrontAccess",
            "Effect": "Allow",
            "Principal": {
              "Service": "cloudfront.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-website-bucket/*"
          }
        ]
      }

Common Patterns

Backup to S3

- name: Backup database to S3
  hosts: databases
  tasks:
    - name: Create database dump
      ansible.builtin.command: >
        pg_dump -Fc myapp -f /tmp/myapp-{{ ansible_date_time.date }}.dump
      become: true
      become_user: postgres
- name: Upload backup to S3
      amazon.aws.s3_object:
        bucket: my-backups
        object: "database/myapp-{{ ansible_date_time.date }}.dump"
        src: "/tmp/myapp-{{ ansible_date_time.date }}.dump"
        mode: put
      delegate_to: localhost
- name: Clean up local dump
      ansible.builtin.file:
        path: "/tmp/myapp-{{ ansible_date_time.date }}.dump"
        state: absent

Deploy Static Website

- name: Deploy static website to S3
  hosts: localhost
  vars:
    bucket: my-website-bucket
    source: ./build/
tasks:
    - name: Sync website files
      amazon.aws.s3_sync:
        bucket: "{{ bucket }}"
        file_root: "{{ source }}"
        delete: true
- name: Invalidate CloudFront cache
      community.aws.cloudfront_distribution:
        distribution_id: E1234567890
        invalidation:
          caller_reference: "deploy-{{ ansible_date_time.epoch }}"
          paths:
            items:
              - '/*'

FAQ

How do I upload files to S3 with Ansible?

Use amazon.aws.s3_object with mode: put, specifying bucket, object (S3 key), and src (local path). Install the amazon.aws collection and boto3 Python package first.

How do I download files from S3 with Ansible?

Use amazon.aws.s3_object with mode: get, specifying bucket, object, and dest (local destination path). The file is downloaded to the target host.

How does Ansible authenticate with AWS S3?

Ansible uses boto3, which checks (in order): environment variables (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), AWS credentials file (~/.aws/credentials), IAM instance role, or explicit aws_access_key/aws_secret_key parameters.

Can I sync an entire directory to S3?

Yes. Use amazon.aws.s3_sync with file_root for the local directory and bucket for the S3 destination. Add delete: true to remove S3 objects not present locally.

How do I create an S3 bucket with Ansible?

Use amazon.aws.s3_bucket: name=my-bucket state=present. Add versioning: true, encryption: AES256, and tags for production configurations.

Conclusion

Ansible's AWS S3 modules provide complete object storage management — upload, download, sync, and manage buckets and policies. Use vault-encrypted credentials and delegate S3 operations to localhost for secure, efficient cloud automation.

Related Articles

• Ansible on AWS: Complete Guide • Ansible EC2 Module: Manage Instances • Ansible Cloud Automation Guide