18791: update documentation, fix single host/single hostname installer
[arvados.git] / doc / install / configure-s3-object-storage.html.textile.liquid
1 ---
2 layout: default
3 navsection: installguide
4 title: Configure S3 object storage
5 ...
6 {% comment %}
7 Copyright (C) The Arvados Authors. All rights reserved.
8
9 SPDX-License-Identifier: CC-BY-SA-3.0
10 {% endcomment %}
11
12 Keepstore can store data in object storage compatible with the S3 API, such as Amazon S3, Google Cloud Storage, or Ceph RADOS.
13
14 Volumes are configured in the @Volumes@ section of the cluster configuration file.
15
16 {% include 'assign_volume_uuid' %}
17
18 <notextile><pre><code>    Volumes:
19       <span class="userinput">ClusterID</span>-nyw5e-<span class="userinput">000000000000000</span>:
20         AccessViaHosts:
21           # This section determines which keepstore servers access the
22           # volume. In this example, keep0 has read/write access, and
23           # keep1 has read-only access.
24           #
25           # If the AccessViaHosts section is empty or omitted, all
26           # keepstore servers will have read/write access to the
27           # volume.
28           "http://<span class="userinput">keep0.ClusterID.example.com</span>:25107": {}
29           "http://<span class="userinput">keep1.ClusterID.example.com</span>:25107": {ReadOnly: true}
30
31         Driver: <span class="userinput">S3</span>
32         DriverParameters:
33           # Bucket name.
34           Bucket: <span class="userinput">example-bucket-name</span>
35
36           # IAM role name to use when retrieving credentials from
37           # instance metadata. It can be omitted, in which case the
38           # role name itself will be retrieved from instance metadata
39           # -- but setting it explicitly may protect you from using
40           # the wrong credentials in the event of an
41           # installation/configuration error.
42           IAMRole: <span class="userinput">""</span>
43
44           # If you are not using an IAM role for authentication,
45           # specify access credentials here instead.
46           AccessKeyID: <span class="userinput">""</span>
47           SecretAccessKey: <span class="userinput">""</span>
48
49           # Storage provider region. For Google Cloud Storage, use ""
50           # or omit.
51           Region: <span class="userinput">us-east-1</span>
52
53           # Storage provider endpoint. For Amazon S3, use "" or
54           # omit. For Google Cloud Storage, use
55           # "https://storage.googleapis.com".
56           Endpoint: ""
57
58           # Change to true if the region requires a LocationConstraint
59           # declaration.
60           LocationConstraint: false
61
62           # Use V2 signatures instead of the default V4. Amazon S3
63           # supports V4 signatures in all regions, but this option
64           # might be needed for other S3-compatible services.
65           V2Signature: false
66
67           # Use the AWS S3 v2 Go driver instead of the goamz driver.
68           UseAWSS3v2Driver: false
69
70           # By default keepstore stores data using the MD5 checksum
71           # (32 hexadecimal characters) as the object name, e.g.,
72           # "0123456abc...". Setting PrefixLength to 3 changes this
73           # naming scheme to "012/0123456abc...". This can improve
74           # performance, depending on the S3 service being used. For
75           # example, PrefixLength 3 is recommended to avoid AWS
76           # limitations on the number of read/write operations per
77           # second per prefix (see
78           # https://aws.amazon.com/premiumsupport/knowledge-center/s3-request-limit-avoid-throttling/).
79           #
80           # Note that changing PrefixLength on an existing volume is
81           # not currently supported. Once you have started using a
82           # bucket as an Arvados volume, you should not change its
83           # configured PrefixLength, or configure another volume using
84           # the same bucket and a different PrefixLength.
85           PrefixLength: 0
86
87           # Requested page size for "list bucket contents" requests.
88           IndexPageSize: 1000
89
90           # Maximum time to wait while making the initial connection
91           # to the backend before failing the request.
92           ConnectTimeout: 1m
93
94           # Maximum time to wait for a complete response from the
95           # backend before failing the request.
96           ReadTimeout: 2m
97
98           # Maximum eventual consistency latency
99           RaceWindow: 24h
100
101         # How much replication is provided by the underlying bucket.
102         # This is used to inform replication decisions at the Keep
103         # layer.
104         Replication: 2
105
106         # If true, do not accept write or trash operations, even if
107         # AccessViaHosts.*.ReadOnly is false.
108         #
109         # If false or omitted, enable write access (subject to
110         # AccessViaHosts.*.ReadOnly, where applicable).
111         ReadOnly: false
112
113         # Storage classes to associate with this volume.  See "Storage
114         # classes" in the "Admin" section of doc.arvados.org.
115         StorageClasses: null
116 </code></pre></notextile>
117
118 Two S3 drivers are available. Historically, Arvados has used the @goamz@ driver to talk to S3-compatible services. More recently, support for the @aws-sdk-go-v2@ driver was added. This driver can be activated by setting the @UseAWSS3v2Driver@ flag to @true@.
119
120 The @aws-sdk-go-v2@ does not support the old S3 v2 signing algorithm. This will not affect interacting with AWS S3, but it might be an issue when Keep is backed by a very old version of a third party S3-compatible service.
121
122 The @aws-sdk-go-v2@ driver can improve read performance by 50-100% over the @goamz@ driver, but it has not had as much production use. See the "wiki":https://dev.arvados.org/projects/arvados/wiki/Keep_real_world_performance_numbers for details.