github.com/npaton/distribution@v2.3.1-rc.0+incompatible/docs/storage-drivers/s3.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "S3 storage driver"
     4  description = "Explains how to use the S3 storage drivers"
     5  keywords = ["registry, service, driver, images, storage,  S3"]
     6  +++
     7  <![end-metadata]-->
     8  
     9  
    10  # S3 storage driver
    11  
    12  An implementation of the `storagedriver.StorageDriver` interface which uses Amazon S3 for object storage.
    13  
    14  ## Parameters
    15  
    16  <table>
    17    <tr>
    18      <th>Parameter</th>
    19      <th>Required</th>
    20      <th>Description</th>
    21    </tr>
    22    <tr>
    23      <td>
    24        <code>accesskey</code>
    25      </td>
    26      <td>
    27        yes
    28      </td>
    29      <td>
    30        Your AWS Access Key.
    31      </td>
    32    </tr>
    33      <tr>
    34      <td>
    35        <code>secretkey</code>
    36      </td>
    37      <td>
    38        yes
    39      </td>
    40      <td>
    41        Your AWS Secret Key.
    42      </td>
    43    </tr>
    44      <tr>
    45      <td>
    46        <code>region</code>
    47      </td>
    48      <td>
    49        yes
    50      </td>
    51      <td>
    52        The AWS region in which your bucket exists. For the moment, the Go AWS
    53        library in use does not use the newer DNS based bucket routing.
    54      </td>
    55    </tr>
    56      <tr>
    57      <td>
    58        <code>bucket</code>
    59      </td>
    60      <td>
    61        yes
    62      </td>
    63      <td>
    64        The bucket name in which you want to store the registry's data.
    65      </td>
    66    </tr>
    67      <tr>
    68      <td>
    69        <code>encrypt</code>
    70      </td>
    71      <td>
    72        no
    73      </td>
    74      <td>
    75         Specifies whether the registry stores the image in encrypted format or
    76         not. A boolean value. The default is false.
    77      </td>
    78    </tr>
    79      <tr>
    80      <td>
    81        <code>secure</code>
    82      </td>
    83      <td>
    84        no
    85      </td>
    86      <td>
    87        Indicates whether to use HTTPS instead of HTTP. A boolean value. The
    88        default is <code>true</code>.
    89      </td>
    90    </tr>
    91      <tr>
    92      <td>
    93        <code>v4auth</code>
    94      </td>
    95      <td>
    96        no
    97      </td>
    98      <td>
    99        Indicates whether the registry uses Version 4 of AWS's authentication.
   100        Generally, you should set this to <code>true</code>. By default, this is
   101        <code>false</code>.
   102      </td>
   103    </tr>
   104      <tr>
   105      <td>
   106        <code>chunksize</code>
   107      </td>
   108      <td>
   109        no
   110      </td>
   111      <td>
   112        The S3 API requires multipart upload chunks to be at least 5MB. This value
   113        should be a number that is larger than 5*1024*1024.
   114      </td>
   115    </tr>
   116     <tr>
   117      <td>
   118        <code>rootdirectory</code>
   119      </td>
   120      <td>
   121        no
   122      </td>
   123      <td>
   124        This is a prefix that will be applied to all S3 keys to allow you to segment data in your bucket if necessary.
   125      </td>
   126    </tr>
   127  </table>
   128  
   129  
   130  `accesskey`: Your aws access key.
   131  
   132  `secretkey`: Your aws secret key.
   133  
   134  **Note** You can provide empty strings for your access and secret keys if you plan on running the driver on an ec2 instance and will handle authentication with the instance's credentials.
   135  
   136  `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, you can look at http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html
   137  
   138  `bucket`: The name of your S3 bucket where you wish to store objects. The bucket must exist prior to the driver initialization.
   139  
   140  `encrypt`: (optional) Whether you would like your data encrypted on the server side (defaults to false if not specified).
   141  
   142  `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. Note that while setting this to false will improve performance, it is not recommended due to security concerns.
   143  
   144  `v4auth`: (optional) Whether you would like to use aws signature version 4 with your requests. This defaults to false if not specified (note that the eu-central-1 region does not work with version 2 signatures, so the driver will error out if initialized with this region and v4auth set to false)
   145  
   146  `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 will benefit from larger chunk sizes.
   147  
   148  `rootdirectory`: (optional) The root directory tree in which all registry files will be stored. Defaults to the empty string (bucket root).
   149  
   150  # CloudFront as Middleware with S3 backend
   151  
   152  ## Use Case
   153  
   154  Adding CloudFront as a middleware for your S3 backed registry can dramatically improve pull times. Your registry will have the ability to 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 you will see. See [Amazon CloudFront](https://aws.amazon.com/cloudfront/details/).
   155  
   156  ## Configuring CloudFront for Distribution
   157  
   158  If you are unfamiliar with creating a CloudFront distribution, see [Getting Started with Cloudfront](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html).
   159  
   160  Defaults can be kept in most areas except:
   161  
   162  ### Origin:
   163  
   164  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.
   165  
   166  ### Behaviors:
   167  
   168    - Viewer Protocol Policy: HTTPS Only
   169    - Allowed HTTP Methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
   170    - Cached HTTP Methods: OPTIONS (checked)
   171    - Restrict Viewer Access (Use Signed URLs or Signed Cookies): Yes
   172      - Trusted Signers: Self (Can add other accounts as long as you have access to CloudFront Key Pairs for those additional accounts)
   173  
   174  ## Registry configuration
   175  
   176  Here the `middleware` option is used. It is still important to keep the `storage` option as CloudFront will only handle `pull` actions; `push` actions are still directly written to S3.
   177  
   178  The following example shows what you will need at minimum:
   179  ```
   180  ...
   181  storage:
   182    s3:
   183      region: us-east-1
   184      bucket: docker.myregistry.com
   185  middleware:
   186    storage:
   187      - name: cloudfront
   188        options:
   189          baseurl: https://abcdefghijklmn.cloudfront.net/
   190          privatekey: /etc/docker/cloudfront/pk-ABCEDFGHIJKLMNOPQRST.pem
   191          keypairid: ABCEDFGHIJKLMNOPQRST
   192  ...
   193  ```
   194  
   195  ## CloudFront Key-Pair
   196  
   197  A CloudFront key-pair is required for all AWS accounts needing access to your CloudFront distribution. For information, please see [Creating CloudFront Key Pairs](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs).