Back up to S3¶

ezbak writes backups to an S3 bucket the same way it writes to a local directory. Set the bucket, authenticate the way the host requires, and every backup lands in S3. Configure local storage and S3 on the same run to keep copies in both places.

What you need¶

• A bucket name: aws_s3_bucket_name (EZBAK_AWS_S3_BUCKET_NAME, CLI --s3-bucket).
• Credentials, if the host has none of its own: aws_access_key and aws_secret_key (EZBAK_AWS_ACCESS_KEY and EZBAK_AWS_SECRET_KEY). Set both or neither.
• Optional, a key prefix: aws_s3_bucket_prefix (EZBAK_AWS_S3_BUCKET_PREFIX, CLI --s3-bucket-prefix) to store backups under a path within the bucket.
• Optional, a region: aws_region (EZBAK_AWS_REGION, CLI --s3-region), if your bucket is not in the default region of boto3.
• Optional, a custom endpoint: aws_s3_endpoint_url (EZBAK_AWS_S3_ENDPOINT_URL, CLI --s3-endpoint-url) to target S3-compatible storage such as MinIO.

ezbak reads credentials only from the environment. There is no CLI flag for them, so secrets never pass through the command line.

Instance roles and ambient credentials¶

Omit both aws_access_key and aws_secret_key, and ezbak defers to the credential chain of boto3. That covers an EC2 instance profile, an EKS service account (IRSA), an ECS task role, the standard AWS_* variables, and ~/.aws/credentials. Nothing else changes: set the bucket, and ezbak authenticates as whatever identity the host already has.

This is the usual arrangement for the orchestrated container. Most operators prefer to attach a role to the workload instead of injecting a long-lived key pair.

The bucket policy needs s3:ListBucket on the bucket, plus s3:GetObject, s3:PutObject, and s3:DeleteObject on its contents. ezbak calls HeadBucket to reach the bucket, and s3:ListBucket covers that call, so no extra permission is necessary.

From each interface¶

docker run -it \
    -v /path/to/source:/source:ro \
    -e EZBAK_ACTION=backup \
    -e EZBAK_NAME=my-backup \
    -e EZBAK_SOURCE_PATHS=/source \
    -e EZBAK_AWS_S3_BUCKET_NAME=my-bucket \
    -e EZBAK_AWS_ACCESS_KEY=your-access-key \
    -e EZBAK_AWS_SECRET_KEY=your-secret-key \
    ghcr.io/natelandau/ezbak:latest

export EZBAK_AWS_ACCESS_KEY="your-access-key"
export EZBAK_AWS_SECRET_KEY="your-secret-key"

ezbak --name my-backup --s3-bucket my-bucket create --source ~/Documents

from ezbak import EZBak, BackupConfig

backups = EZBak(
    BackupConfig(
        name="my-backup",
        source_paths=["/data"],
        aws_s3_bucket_name="my-bucket",
        aws_access_key="your-access-key",
        aws_secret_key="your-secret-key",
    )
)
backups.create_backup()

Local and S3 at once¶

Set both storage_paths and aws_s3_bucket_name, and each backup writes to both. A local copy stays on the host for a fast restore, and the S3 copy follows the job to another host.

ezbak --name my-backup --storage ~/Backups --s3-bucket my-bucket \
  create --source ~/Documents

For the model, see Storage locations.

A prefix within the bucket¶

A prefix stores backups under a path, so one bucket can hold several backup sets in their own folders.

ezbak --name my-backup --s3-bucket my-bucket --s3-bucket-prefix hosts/web01 \
  create --source ~/Documents

S3-compatible storage (MinIO)¶

Point aws_s3_endpoint_url at a non-AWS S3 service to back up there instead. The region is often a placeholder that the service ignores, but boto3 still expects one, so set aws_region too.

ezbak --name my-backup --s3-bucket my-bucket \
  --s3-endpoint-url https://minio.example.com --s3-region us-east-1 \
  create --source ~/Documents

In the container, the same options are EZBAK_AWS_S3_ENDPOINT_URL and EZBAK_AWS_REGION, alongside the usual bucket and credential variables.