Store images on Amazon S3

Estimated reading time: 5 minutes

You can configure DTR to store Docker images on Amazon S3, or other file servers with an S3-compatible API like Cleversafe or Minio.

Amazon S3 and compatible services store files in “buckets”, and users have permissions to read, write, and delete files from those buckets. When you integrate DTR with Amazon S3, DTR sends all read and write operations to the S3 bucket so that the images are persisted there.

Create a bucket on Amazon S3

Before configuring DTR you need to create a bucket on Amazon S3. To get faster pulls and pushes, you should create the S3 bucket on a region that’s physically close to the servers where DTR is running.

Start by creating a bucket. Then, as a best practice you should create a new IAM user just for the DTR integration and apply an IAM policy that ensures the user has limited permissions.

This user only needs permissions to access the bucket that you’ll use to store images, and be able to read, write, and delete files.

Here’s an example of a policy like that:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:ListBucketMultipartUploads"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject",
                "s3:ListBucketMultipartUploads"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>/*"
        }
    ]
}

Configure DTR

Once you’ve created a bucket and user, you can configure DTR to use it. In your browser, navigate to https://<dtr-url. Select System > Storage.

Select the S3 option, and fill-in the information about the bucket and user.

Field Description
Root directory The path in the bucket where images are stored
AWS Region name The region where the bucket is. Learn more
S3 bucket name The name of the bucket to store the images
AWS access key The access key to use to access the S3 bucket. This can be left empty if you’re using an IAM policy. Learn more
AWS secret key The secret key to use to access the S3 bucket. This can be left empty if you’re using an IAM policy
Region endpoint The endpoint name for the region you’re using. Learn more

There are also some advanced settings.

Field Description
Signature version 4 auth Authenticate the requests using AWS signature version 4. Learn more
Use HTTPS Secure all requests with HTTPS, or make requests in an insecure way
Skip TLS verification Encrypt all traffic, but don’t verify the TLS certificate used by the storage backend
Root CA certificate The public key certificate of the root certificate authority that issued the storage backend certificate

Once you click Save, DTR validates the configurations and saves the changes.

Configure your clients

If you’re using a TLS certificate in your storage backend that’s not globally trusted, you’ll have to configure all Docker Engines that push or pull from DTR to trust that certificate. When you push or pull an image DTR redirects the requests to the storage backend, so if clients don’t trust the TLS certificates of both DTR and the storage backend, they won’t be able to push or pull images. Learn how to configure the Docker client.

And if you’ve configured DTR to skip TLS verification, you also need to configure all Docker Engines that push or pull from DTR to skip TLS verification. You do this by adding DTR to the list of insecure registries when starting Docker.

Supported regions

DTR supports the following S3 regions:

Region
us-east-1
us-east-2
us-west-1
us-west-2
eu-west-1
eu-west-2
eu-central-1
ap-south-1
ap-southeast-1
ap-southeast-2
ap-northeast-1
ap-northeast-2
sa-east-1
cn-north-1
us-gov-west-1
ca-central-1

Update your S3 settings on the web interface

When running 2.5.x (with experimental garbage collection) or 2.6.0-2.6.4, there is an issue with changing your S3 settings on the web interface which leads to erased metadata. Make sure to back up your DTR metadata before you proceed.

Restore DTR with S3

To restore DTR using your previously configured S3 settings, use docker/dtr restore with --dtr-use-default-storage to keep your metadata.

Where to go next

Rate this page:

 
0
 
1