ceph/examples/rgw/boto3/README.md

   1 # Introduction
   2 This directory contains examples on how to use AWS CLI/boto3 to exercise the RadosGW extensions to the S3 API.
   3 This is an extension to the [AWS SDK](https://github.com/boto/botocore/blob/develop/botocore/data/s3/2006-03-01/service-2.json).
   4
   5 # Users
   6 For the standard client to support these extensions, the: ``service-2.sdk-extras.json`` file should be placed under: ``~/.aws/models/s3/2006-03-01/`` directory.
   7 For more information see [here](https://github.com/boto/botocore/blob/develop/botocore/loaders.py#L33).
   8 ## Python
   9 The [boto3 client](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) could be used with the extensions, code samples exists in this directory.
  10 ## AWS CLI
  11 The standard [AWS CLI](https://docs.aws.amazon.com/cli/latest/) may also be used with these extensions. For example:
  12 - Unordered listing:
  13 ```
  14 aws --endpoint-url http://localhost:8000 s3api list-objects --bucket=mybucket --allow-unordered
  15 ```
  16
  17 - Unordered listing (version 2):
  18 ```
  19 aws --endpoint-url http://localhost:8000 s3api list-objects-v2 --bucket=mybucket --allow-unordered
  20 ```
  21
  22 - Topic creation with endpoint:
  23 ```
  24 aws --endpoint-url http://localhost:8000 sns create-topic --name=mytopic --attributes='{"push-endpoint": "amqp://localhost:5672", "amqp-exchange": "ex1", "amqp-ack-level": "broker"}'
  25 ```
  26 Expected output:
  27 ```
  28 {
  29     "TopicArn": "arn:aws:sns:default::mytopic"
  30 }
  31 ```
  32
  33 - Get topic attributes:
  34 ```
  35 aws --endpoint-url http://localhost:8000 sns get-topic-attributes --topic-arn="arn:aws:sns:default::mytopic"
  36 ```
  37 Expected output:
  38 ```
  39 {
  40   "Attributes": {
  41     "User": "",
  42     "Name": "mytopic",
  43     "EndPoint": "{\"EndpointAddress\":\"amqp://localhost:5672\",\"EndpointArgs\":\"Attributes.entry.1.key=push-endpoint&Attributes.entry.1.value=amqp://localhost:5672&Attributes.entry.2.key=amqp-exchange&Attributes.entry.2.value=ex1&Attributes.entry.3.key=amqp-ack-level&Attributes.entry.3.value=broker&Version=2010-03-31&amqp-ack-level=broker&amqp-exchange=ex1&push-endpoint=amqp://localhost:5672\",\"EndpointTopic\":\"mytopic\",\"HasStoredSecret\":\"false\",\"Persistent\":\"false\"}",
  44     "TopicArn": "arn:aws:sns:default::mytopic",
  45     "OpaqueData": ""
  46   }
  47 }
  48 ```
  49
  50 - Bucket notifications with filtering extensions (bucket must exist before calling this command):
  51 ```
  52 aws --region=default --endpoint-url http://localhost:8000 s3api put-bucket-notification-configuration --bucket=mybucket --notification-configuration='{"TopicConfigurations": [{"Id": "notif1", "TopicArn": "arn:aws:sns:default::mytopic", "Events": ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"], "Filter": {"Metadata": {"FilterRules": [{"Name": "x-amz-meta-foo", "Value": "bar"}, {"Name": "x-amz-meta-hello", "Value": "world"}]}, "Key": {"FilterRules": [{"Name": "regex", "Value": "([a-z]+)"}]}}}]}'
  53 ```
  54
  55 - Get configuration of a specific notification of a bucket:
  56 ```
  57 aws --endpoint-url http://localhost:8000 s3api get-bucket-notification-configuration --bucket=mybucket --notification=notif1
  58 ```
  59 Expected output:
  60 ```
  61 {
  62   "TopicConfigurations": [
  63     {
  64       "Id": "notif1",
  65       "TopicArn": "arn:aws:sns:default::mytopic",
  66       "Events": [
  67         "s3:ObjectCreated:*",
  68         "s3:ObjectRemoved:*"
  69       ],
  70       "Filter": {
  71         "Key": {
  72           "FilterRules": [
  73             {
  74               "Name": "regex",
  75               "Value": "([a-z]+)"
  76             }
  77           ]
  78         },
  79         "Metadata": {
  80           "FilterRules": [
  81             {
  82               "Name": "x-amz-meta-foo",
  83               "Value": "bar"
  84             },
  85             {
  86               "Name": "x-amz-meta-hello",
  87               "Value": "world"
  88             }
  89           ]
  90         }
  91       }
  92     }
  93   ]
  94 }
  95 ```
  96
  97 # Developers
  98 Anyone developing an extension to the S3 API supported by AWS, please modify ``service-2.sdk-extras.json`` (all extensions should go into the same file), so that boto3 could be used to test the new API.
  99 In addition, python files with code samples should be added to this directory demonstrating use of the new API.
 100 When testing you changes please:
 101 - make sure that the modified file is in the boto3 path as explained above
 102 - make sure that the standard S3 tests suit is not broken, even with the extensions files in the path
 103