awstransport

caddy-s3-transport

A Caddy reverse proxy transport that signs requests with AWS Signature Version 4 (SigV4). Use it to proxy to private S3 buckets from Caddy running on EC2 (or anywhere with AWS credentials).

• Same credential stack as certmagic-s3: use_iam_provider true uses MinIO’s IAM provider (EC2 instance metadata); static keys use MinIO NewStaticV4. Same env vars (S3_USE_IAM_PROVIDER, etc.) where applicable.
• IAM / instance role: Use use_iam_provider true or omit credentials so the default chain (env, shared config, EC2 IMDS) is used.
• Caddyfile: transport aws { region ... ; service s3 ; use_iam_provider true } — matches the common transport aws syntax.

Install with xcaddy:

xcaddy build --with github.com/thetestcoder/caddy-s3-transport

Caddyfile example

Reverse proxy to a private S3 bucket, using the EC2 instance role (same IAM provider as certmagic-s3):

https:// {
    reverse_proxy your-bucket-name.s3.ap-south-1.amazonaws.com {
        transport aws {
            region ap-south-1
            service s3
            use_iam_provider true
        }
        header_up Host {upstream_hostport}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

With explicit credentials (same style as certmagic-s3; env replacement at startup):

transport aws {
    region ap-south-1
    service s3
    access_id "Access ID"
    secret_key "Secret Key"
}

You can set S3_USE_IAM_PROVIDER=true in the environment to enable IAM without changing the Caddyfile (same as certmagic-s3).

Directives

Requirements

• Caddy v2.
• For IAM: EC2 instance (or similar) with an instance profile that has s3:GetObject (and any other needed S3 permissions) on the target bucket.
• Upstream in reverse_proxy should be the bucket’s host, e.g. bucket-name.s3.region.amazonaws.com.

Example with your config

Your existing config already uses transport aws { region ap-south-1; service s3 }. After building Caddy with this module, that block will use IAM (EC2 instance role) when access_id and secret_key are omitted. See example-Caddyfile in this repo.

Build

You must use a Caddy binary built with this plugin. The stock Caddy binary (apt, official download, etc.) does not include http.reverse_proxy.transport.aws.

xcaddy build --with github.com/thetestcoder/caddy-s3-transport

Use the generated caddy binary (e.g. ./caddy run or replace /usr/bin/caddy). If the repo is not on GitHub yet, build from a local path:

xcaddy build --with github.com/thetestcoder/caddy-s3-transport=./path/to/caddy-s3-transport

Verify the module is loaded:

./caddy list-modules | grep aws
# should show: http.reverse_proxy.transport.aws

Troubleshooting

"module not registered: http.reverse_proxy.transport.aws"

This means the Caddy process is not using a binary that was built with this plugin.

1. Build Caddy with the plugin (see Build above).
2. Run that binary: ./caddy run --config /etc/caddy/Caddyfile (or install it over your system Caddy).
3. If you use systemd/Docker, point the service at the new binary path, or copy the xcaddy-built caddy to the path your service uses (e.g. /usr/bin/caddy).

Do not use the default Caddy package from your distro or the official caddy download; they do not include third-party transport modules.

License

MIT