doc/api/keep-s3.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "S3 API"
   6
   7 ...
   8 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 The Simple Storage Service (S3) API is a de-facto standard for object storage originally developed by Amazon Web Services.  Arvados supports accessing files in Keep using the S3 API.
  15
  16 S3 is supported by many "cloud native" applications, and client libraries exist in many languages for programmatic access.
  17
  18 h3. Endpoints and Buckets
  19
  20 To access Arvados S3 using an S3 client library, you must tell it to use the URL of the keep-web server (this is @Services.WebDAVDownload.ExternalURL@ in the public configuration) as the custom endpoint.  The keep-web server will decide to treat it as an S3 API request based on the presence of an AWS-format Authorization header.  Requests without an Authorization header, or differently formatted Authorization, will be treated as "WebDAV":keep-webdav.html .
  21
  22 The "bucket name" is an Arvados collection uuid, portable data hash, or project uuid.
  23
  24 Path-style and virtual host-style requests are supported.
  25 * A path-style request uses the hostname indicated by @Services.WebDAVDownload.ExternalURL@, with the bucket name in the first path segment: @https://download.example.com/zzzzz-4zz18-asdfgasdfgasdfg/@.
  26 * A virtual host-style request uses the hostname pattern indicated by @Services.WebDAV.ExternalURL@, with a bucket name in place of the leading @*@: @https://zzzzz-4zz18-asdfgasdfgasdfg.collections.example.com/@.
  27
  28 If you have wildcard DNS, TLS, and routing set up, an S3 client configured with endpoint @collections.example.com@ should work regardless of which request style it uses.
  29
  30 h3. Supported Operations
  31
  32 h4. ListObjects
  33
  34 Supports the following request query parameters:
  35
  36 * delimiter
  37 * marker
  38 * max-keys
  39 * prefix
  40
  41 h4. GetObject
  42
  43 Supports the @Range@ header.
  44
  45 h4. PutObject
  46
  47 Can be used to create or replace a file in a collection.
  48
  49 An empty PUT with a trailing slash and @Content-Type: application/x-directory@ will create a directory within a collection if Arvados configuration option @Collections.S3FolderObjects@ is true.
  50
  51 Missing parent/intermediate directories within a collection are created automatically.
  52
  53 Cannot be used to create a collection or project.
  54
  55 h4. DeleteObject
  56
  57 Can be used to remove files from a collection.
  58
  59 If used on a directory marker, it will delete the directory only if the directory is empty.
  60
  61 h4. HeadBucket
  62
  63 Can be used to determine if a bucket exists and if client has read access to it.
  64
  65 h4. HeadObject
  66
  67 Can be used to determine if an object exists and if client has read access to it.
  68
  69 h4. GetBucketVersioning
  70
  71 Bucket versioning is presently not supported, so this will always respond that bucket versioning is not enabled.
  72
  73 h3. Accessing collection/project properties as metadata
  74
  75 GetObject, HeadObject, and HeadBucket return Arvados object properties as S3 metadata headers, e.g., @X-Amz-Meta-Foo: bar@.
  76
  77 If the requested path indicates a file or directory placeholder inside a collection, or the top level of a collection, GetObject and HeadObject return the collection properties.
  78
  79 If the requested path indicates a directory placeholder corresponding to a project, GetObject and HeadObject return the properties of the project.
  80
  81 HeadBucket returns the properties of the collection or project corresponding to the bucket name.
  82
  83 Non-string property values are returned in a JSON representation, e.g., @["foo","bar"]@.
  84
  85 As in Amazon S3, property values containing non-ASCII characters are returned in BASE64-encoded form as described in RFC 2047, e.g., @=?UTF-8?b?4pu1?=@.
  86
  87 GetBucketTagging and GetObjectTagging APIs are _not_ supported.
  88
  89 It is not possible to modify collection or project properties using the S3 API.
  90
  91 h3. Authorization mechanisms
  92
  93 Keep-web accepts AWS Signature Version 4 (AWS4-HMAC-SHA256) as well as the older V2 AWS signature.
  94
  95 If your client uses V4 signatures exclusively _and_ your Arvados token was issued by the same cluster you are connecting to, you can use the Arvados token's UUID part as your S3 Access Key, and its secret part as your S3 Secret Key. This is preferred, where applicable.
  96
  97 Example using cluster @zzzzz@:
  98 * Arvados token: @v2/zzzzz-gj3su-yyyyyyyyyyyyyyy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@
  99 * Access Key: @zzzzz-gj3su-yyyyyyyyyyyyyyy@
 100 * Secret Key: @xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@
 101
 102 In all other cases, replace every @/@ character in your Arvados token with @_@, and use the resulting string as both Access Key and Secret Key.
 103
 104 Example using a cluster other than @zzzzz@ _or_ an S3 client that uses V2 signatures:
 105 * Arvados token: @v2/zzzzz-gj3su-yyyyyyyyyyyyyyy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@
 106 * Access Key: @v2_zzzzz-gj3su-yyyyyyyyyyyyyyy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@
 107 * Secret Key: @v2_zzzzz-gj3su-yyyyyyyyyyyyyyy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@