S3 storage driver

Estimated reading time: 7 minutes

This page contains information about hosting your own registry using the open source Docker Registry. For information about Docker Hub, which offers a hosted registry with additional features such as teams, organizations, web hooks, automated builds, etc, see Docker Hub.

An implementation of the storagedriver.StorageDriver interface which uses Amazon S3 or S3 compatible services for object storage.

Parameters

Note You can provide empty strings for your access and secret keys to run the driver on an ec2 instance and handles authentication with the instance’s credentials. If you use IAM roles, omit these keys to fetch temporary credentials from IAM.

region: The name of the aws region in which you would like to store objects (for example us-east-1). For a list of regions, see Regions, Availability Zones, and Local Zones.

regionendpoint: (optional) Endpoint URL for S3 compatible APIs. This should not be provided when using Amazon S3.

bucket: The name of your S3 bucket where you wish to store objects. The bucket must exist prior to the driver initialization.

encrypt: (optional) Whether you would like your data encrypted on the server side (defaults to false if not specified).

keyid: (optional) Whether you would like your data encrypted with this KMS key ID (defaults to none if not specified, is ignored if encrypt is not true).

secure: (optional) Whether you would like to transfer data to the bucket over ssl or not. Defaults to true (meaning transferring over ssl) if not specified. While setting this to false improves performance, it is not recommended due to security concerns.

v4auth: (optional) Whether you would like to use aws signature version 4 with your requests. This defaults to false if not specified. The eu-central-1 region does not work with version 2 signatures, so the driver errors out if initialized with this region and v4auth set to false.

chunksize: (optional) The default part size for multipart uploads (performed by WriteStream) to S3. The default is 10 MB. Keep in mind that the minimum part size for S3 is 5MB. Depending on the speed of your connection to S3, a larger chunk size may result in better performance; faster connections benefit from larger chunk sizes.

rootdirectory: (optional) The root directory tree in which all registry files are stored. Defaults to the empty string (bucket root).

storageclass: (optional) The storage class applied to each registry file. Defaults to STANDARD. Valid options are STANDARD and REDUCED_REDUNDANCY.

S3 permission scopes

The following AWS policy is required by the registry for push and pull. Make sure to replace S3_BUCKET_NAME with the name of your bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:ListBucketMultipartUploads"
      ],
      "Resource": "arn:aws:s3:::S3_BUCKET_NAME"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListMultipartUploadParts",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::S3_BUCKET_NAME/*"
    }
  ]
}

See the S3 policy documentation for more details.

CloudFront as Middleware with S3 backend

Use Case

Adding CloudFront as a middleware for your S3 backed registry can dramatically improve pull times. Your registry can retrieve your images from edge servers, rather than the geographically limited location of your S3 bucket. The farther your registry is from your bucket, the more improvements are possible. See Amazon CloudFront.

An alternative method for CloudFront that requires less configuration and will use the same edge servers is S3 Transfer Acceleration. Please check acceleration Requirements to see whether you need CloudFront or S3 Transfer Acceleration.

Configuring CloudFront for Distribution

If you are unfamiliar with creating a CloudFront distribution, see Getting Started with Cloudfront.

Defaults can be kept in most areas except:

Origin:

• The CloudFront distribution must be created such that the Origin Path is set to the directory level of the root “docker” key in S3. If your registry exists on the root of the bucket, this path should be left blank.

• For private S3 buckets, you must set Restrict Bucket Access to Yes. See the CloudFront documentation.

Behaviors:

• Viewer Protocol Policy: HTTPS Only
• Allowed HTTP Methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
• Cached HTTP Methods: OPTIONS (checked)
• Restrict Viewer Access (Use Signed URLs or Signed Cookies): Yes
  • Trusted Signers: Self (Can add other accounts as long as you have access to CloudFront Key Pairs for those additional accounts)

Registry configuration

Here the middleware option is used. It is still important to keep the storage option, because CloudFront only handles pull actions; push actions are still directly written to S3.

The following example shows a minimum configuration:

...
storage:
  s3:
    region: us-east-1
    bucket: docker.myregistry.com
middleware:
  storage:
    - name: cloudfront
      options:
        baseurl: https://abcdefghijklmn.cloudfront.net/
        privatekey: /etc/docker/cloudfront/pk-ABCEDFGHIJKLMNOPQRST.pem
        keypairid: ABCEDFGHIJKLMNOPQRST
...

CloudFront Key-Pair

A CloudFront key-pair is required for all AWS accounts needing access to your CloudFront distribution. You must have access to your AWS account’s root credentials to create the required Cloudfront keypair. For information, see Creating CloudFront Key Pairs.