minio/docs/gateway/s3.md

MinIO S3 Gateway

MinIO S3 Gateway adds MinIO features like MinIO Browser and disk caching to AWS S3 or any other AWS S3 compatible service.

Run MinIO Gateway for AWS S3

As a prerequisite to run MinIO S3 gateway, you need valid AWS S3 access key and secret key by default. Optionally you can also set custom access/secret key, when you have rotating AWS IAM credentials or AWS credentials through environment variables (i.e. AWS_ACCESS_KEY_ID)

Using Docker

docker run -p 9000:9000 --name minio-s3 \
 -e "MINIO_ACCESS_KEY=aws_s3_access_key" \
 -e "MINIO_SECRET_KEY=aws_s3_secret_key" \
 minio/minio gateway s3

Using Binary

export MINIO_ACCESS_KEY=aws_s3_access_key
export MINIO_SECRET_KEY=aws_s3_secret_key
minio gateway s3

Using Binary in EC2

Using IAM rotating credentials for AWS S3

If you are using an S3 enabled IAM role on an EC2 instance for S3 access, MinIO will still require env vars MINIO_ACCESS_KEY and MINIO_SECRET_KEY to be set for its internal use. These may be set to any value which meets the length requirements. Access key length should be at least 3, and secret key length at least 8 characters.

export MINIO_ACCESS_KEY=custom_access_key
export MINIO_SECRET_KEY=custom_secret_key
minio gateway s3

MinIO gateway will automatically look for list of credential styles in following order, if your backend URL is AWS S3.

• AWS env vars (i.e. AWS_ACCESS_KEY_ID)
• AWS creds file (i.e. AWS_SHARED_CREDENTIALS_FILE or ~/.aws/credentials)
• IAM profile based credentials. (performs an HTTP call to a pre-defined endpoint, only valid inside configured ec2 instances)

Minimum permissions required if you wish to provide restricted access with your AWS credentials, please make sure you have following IAM policies attached for your AWS user or roles.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "readonly",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": "arn:aws:s3:::testbucket"
        },
        {
            "Sid": "readonly",
            "Effect": "Allow",
            "Action": "s3:HeadBucket",
            "Resource": "arn:aws:s3:::testbucket"
        }
    ]
}

Run MinIO Gateway for AWS S3 compatible services

As a prerequisite to run MinIO S3 gateway on an AWS S3 compatible service, you need valid access key, secret key and service endpoint.

Run MinIO Gateway with double-encryption

MinIO gateway to S3 supports encryption of data at rest. Three types of encryption modes are supported

• encryption can be set to pass-through to backend
• single encryption (at the gateway)
• double encryption (single encryption at gateway and pass through to backend).

This can be specified by setting MINIO_GATEWAY_SSE environment variable. If MINIO_GATEWAY_SSE and KMS are not setup, all encryption headers are passed through to the backend. If KMS environment variables are set up, single encryption is automatically performed at the gateway and encrypted object is saved at the backend.

To specify double encryption, MINIO_GATEWAY_SSE environment variable needs to be set to "s3" for sse-s3 and "c" for sse-c encryption. More than one encryption option can be set, delimited by ";". Objects are encrypted at the gateway and the gateway also does a pass-through to backend. Note that in the case of SSE-C encryption, gateway derives a unique SSE-C key for pass through from the SSE-C client key using a key derivation function (KDF).

export MINIO_GATEWAY_SSE="s3;c"
export MINIO_KMS_VAULT_APPROLE_ID=9b56cc08-8258-45d5-24a3-679876769126
export MINIO_KMS_VAULT_APPROLE_SECRET=4e30c52f-13e4-a6f5-0763-d50e8cb4321f
export MINIO_KMS_VAULT_ENDPOINT=https://vault-endpoint-ip:8200
export MINIO_KMS_VAULT_KEY_NAME=my-minio-key
export MINIO_KMS_VAULT_AUTH_TYPE=approle
minio gateway s3

Using Docker

docker run -p 9000:9000 --name minio-s3 \
 -e "MINIO_ACCESS_KEY=access_key" \
 -e "MINIO_SECRET_KEY=secret_key" \
 minio/minio gateway s3 https://s3_compatible_service_endpoint:port

Using Binary

export MINIO_ACCESS_KEY=access_key
export MINIO_SECRET_KEY=secret_key
minio gateway s3 https://s3_compatible_service_endpoint:port

MinIO Caching

MinIO edge caching allows storing content closer to the applications. Frequently accessed objects are stored in a local disk based cache. Edge caching with MinIO gateway feature allows

• Dramatic improvements for time to first byte for any object.
• Avoid S3 data transfer charges.

Refer this document to get started with MinIO Caching.

MinIO Browser

MinIO Gateway comes with an embedded web based object browser. Point your web browser to http://127.0.0.1:9000 to ensure that your server has started successfully.

With MinIO S3 gateway, you can use MinIO browser to explore AWS S3 based objects.

Known limitations

• Bucket notification APIs are not supported.

Explore Further

• mc command-line interface
• aws command-line interface
• minio-go Go SDK