Chapter 2. Ceph Object Gateway administrative API
As a developer, you can administer the Ceph Object Gateway by interacting with the RESTful application programming interface (API). The Ceph Object Gateway makes available the features of the radosgw-admin
command in a RESTful API. You can manage users, data, quotas, and usage which you can integrate with other management platforms.
Red Hat recommends using the command-line interface when configuring the Ceph Object Gateway.
The administrative API provides the following functionality:
- Authentication Requests
User Account Management
User Capabilities Management
Key Management
Bucket Management
Object Management
- Getting Usage Information
- Removing Usage Information
- Standard Error Responses
Prerequisites
- A running Red Hat Ceph Storage cluster.
- A RESTful client.
2.1. Administration operations
An administrative Application Programming Interface (API) request will be done on a URI that starts with the configurable 'admin' resource entry point. Authorization for the administrative API duplicates the S3 authorization mechanism. Some operations require that the user holds special administrative capabilities. The response entity type, either XML or JSON, might be specified as the 'format' option in the request and defaults to JSON if not specified.
Example
PUT /admin/user?caps&format=json HTTP/1.1 Host: FULLY_QUALIFIED_DOMAIN_NAME Content-Type: text/plain Authorization: AUTHORIZATION_TOKEN usage=read
2.2. Administration authentication requests
Amazon’s S3 service uses the access key and a hash of the request header and the secret key to authenticate the request. It has the benefit of providing an authenticated request, especially large uploads, without SSL overhead.
Most use cases for the S3 API involve using open-source S3 clients such as the AmazonS3Client
in the Amazon SDK for Java or Python Boto. These libraries do not support the Ceph Object Gateway Admin API. You can subclass and extend these libraries to support the Ceph Admin API. Alternatively, you can create a unique Gateway client.
Creating an execute()
method
The CephAdminAPI example class in this section illustrates how to create an execute()
method that can take request parameters, authenticate the request, call the Ceph Admin API and receive a response.
The CephAdminAPI
class example is not supported or intended for commercial use. It is for illustrative purposes only.
Calling the Ceph Object Gateway
The client code contains five calls to the Ceph Object Gateway to demonstrate CRUD operations:
- Create a User
- Get a User
- Modify a User
- Create a Subuser
- Delete a User
To use this example, get the httpcomponents-client-4.5.3
Apache HTTP components. You can download it for example here: http://hc.apache.org/downloads.cgi. Then unzip the tar file, navigate to its lib
directory and copy the contents to the /jre/lib/ext
directory of the JAVA_HOME
directory, or a custom classpath.
As you examine the CephAdminAPI class example, notice that the execute()
method takes an HTTP method, a request path, an optional subresource, null
if not specified, and a map of parameters. To execute with subresources, for example, subuser
, and key
, you will need to specify the subresource as an argument in the execute()
method.
The example method:
- Builds a URI.
- Builds an HTTP header string.
-
Instantiates an HTTP request, for example,
PUT
,POST
,GET
,DELETE
. -
Adds the
Date
header to the HTTP header string and the request header. -
Adds the
Authorization
header to the HTTP request header. - Instantiates an HTTP client and passes it the instantiated HTTP request.
- Makes a request.
- Returns a response.
Building the header string
Building the header string is the portion of the process that involves Amazon’s S3 authentication procedure. Specifically, the example method does the following:
-
Adds a request type, for example,
PUT
,POST
,GET
,DELETE
. - Adds the date.
- Adds the requestPath.
The request type should be uppercase with no leading or trailing white space. If you do not trim white space, authentication will fail. The date MUST be expressed in GMT, or authentication will fail.
The exemplary method does not have any other headers. The Amazon S3 authentication procedure sorts x-amz
headers lexicographically. So if you are adding x-amz
headers, be sure to add them lexicographically.
Once you have built the header string, the next step is to instantiate an HTTP request and pass it the URI. The exemplary method uses PUT
for creating a user and subuser, GET
for getting a user, POST
for modifying a user and DELETE
for deleting a user.
Once you instantiate a request, add the Date
header followed by the Authorization
header. Amazon’s S3 authentication uses the standard Authorization
header, and has the following structure:
Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET
The CephAdminAPI example class has a base64Sha1Hmac()
method, which takes the header string and the secret key for the admin user, and returns a SHA1 HMAC as a base-64 encoded string. Each execute()
call will invoke the same line of code to build the Authorization
header:
httpRequest.addHeader("Authorization", "AWS " + this.getAccessKey() + ":" + base64Sha1Hmac(headerString.toString(), this.getSecretKey()));
The following CephAdminAPI
example class requires you to pass the access key, secret key, and an endpoint to the constructor. The class provides accessor methods to change them at runtime.
Example
import java.io.IOException; import java.net.URI; import java.net.URISyntaxException; import java.time.OffsetDateTime; import java.time.format.DateTimeFormatter; import java.time.ZoneId; import org.apache.http.HttpEntity; import org.apache.http.NameValuePair; import org.apache.http.Header; import org.apache.http.client.entity.UrlEncodedFormEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpRequestBase; import org.apache.http.client.methods.HttpGet; import org.apache.http.client.methods.HttpPost; import org.apache.http.client.methods.HttpPut; import org.apache.http.client.methods.HttpDelete; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.message.BasicNameValuePair; import org.apache.http.util.EntityUtils; import org.apache.http.client.utils.URIBuilder; import java.util.Base64; import java.util.Base64.Encoder; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import javax.crypto.spec.SecretKeySpec; import javax.crypto.Mac; import java.util.Map; import java.util.Iterator; import java.util.Set; import java.util.Map.Entry; public class CephAdminAPI { /* * Each call must specify an access key, secret key, endpoint and format. */ String accessKey; String secretKey; String endpoint; String scheme = "http"; //http only. int port = 80; /* * A constructor that takes an access key, secret key, endpoint and format. */ public CephAdminAPI(String accessKey, String secretKey, String endpoint){ this.accessKey = accessKey; this.secretKey = secretKey; this.endpoint = endpoint; } /* * Accessor methods for access key, secret key, endpoint and format. */ public String getEndpoint(){ return this.endpoint; } public void setEndpoint(String endpoint){ this.endpoint = endpoint; } public String getAccessKey(){ return this.accessKey; } public void setAccessKey(String accessKey){ this.accessKey = accessKey; } public String getSecretKey(){ return this.secretKey; } public void setSecretKey(String secretKey){ this.secretKey = secretKey; } /* * Takes an HTTP Method, a resource and a map of arguments and * returns a CloseableHTTPResponse. */ public CloseableHttpResponse execute(String HTTPMethod, String resource, String subresource, Map arguments) { String httpMethod = HTTPMethod; String requestPath = resource; StringBuffer request = new StringBuffer(); StringBuffer headerString = new StringBuffer(); HttpRequestBase httpRequest; CloseableHttpClient httpclient; URI uri; CloseableHttpResponse httpResponse = null; try { uri = new URIBuilder() .setScheme(this.scheme) .setHost(this.getEndpoint()) .setPath(requestPath) .setPort(this.port) .build(); if (subresource != null){ uri = new URIBuilder(uri) .setCustomQuery(subresource) .build(); } for (Iterator iter = arguments.entrySet().iterator(); iter.hasNext();) { Entry entry = (Entry)iter.next(); uri = new URIBuilder(uri) .setParameter(entry.getKey().toString(), entry.getValue().toString()) .build(); } request.append(uri); headerString.append(HTTPMethod.toUpperCase().trim() + "\n\n\n"); OffsetDateTime dateTime = OffsetDateTime.now(ZoneId.of("GMT")); DateTimeFormatter formatter = DateTimeFormatter.RFC_1123_DATE_TIME; String date = dateTime.format(formatter); headerString.append(date + "\n"); headerString.append(requestPath); if (HTTPMethod.equalsIgnoreCase("PUT")){ httpRequest = new HttpPut(uri); } else if (HTTPMethod.equalsIgnoreCase("POST")){ httpRequest = new HttpPost(uri); } else if (HTTPMethod.equalsIgnoreCase("GET")){ httpRequest = new HttpGet(uri); } else if (HTTPMethod.equalsIgnoreCase("DELETE")){ httpRequest = new HttpDelete(uri); } else { System.err.println("The HTTP Method must be PUT, POST, GET or DELETE."); throw new IOException(); } httpRequest.addHeader("Date", date); httpRequest.addHeader("Authorization", "AWS " + this.getAccessKey() + ":" + base64Sha1Hmac(headerString.toString(), this.getSecretKey())); httpclient = HttpClients.createDefault(); httpResponse = httpclient.execute(httpRequest); } catch (URISyntaxException e){ System.err.println("The URI is not formatted properly."); e.printStackTrace(); } catch (IOException e){ System.err.println("There was an error making the request."); e.printStackTrace(); } return httpResponse; } /* * Takes a uri and a secret key and returns a base64-encoded * SHA-1 HMAC. */ public String base64Sha1Hmac(String uri, String secretKey) { try { byte[] keyBytes = secretKey.getBytes("UTF-8"); SecretKeySpec signingKey = new SecretKeySpec(keyBytes, "HmacSHA1"); Mac mac = Mac.getInstance("HmacSHA1"); mac.init(signingKey); byte[] rawHmac = mac.doFinal(uri.getBytes("UTF-8")); Encoder base64 = Base64.getEncoder(); return base64.encodeToString(rawHmac); } catch (Exception e) { throw new RuntimeException(e); } } }
The subsequent CephAdminAPIClient
example illustrates how to instantiate the CephAdminAPI
class, build a map of request parameters, and use the execute()
method to create, get, update and delete a user.
Example
import java.io.IOException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.HttpEntity; import org.apache.http.util.EntityUtils; import java.util.*; public class CephAdminAPIClient { public static void main (String[] args){ CephAdminAPI adminApi = new CephAdminAPI ("FFC6ZQ6EMIF64194158N", "Xac39eCAhlTGcCAUreuwe1ZuH5oVQFa51lbEMVoT", "ceph-client"); /* * Create a user */ Map requestArgs = new HashMap(); requestArgs.put("access", "usage=read, write; users=read, write"); requestArgs.put("display-name", "New User"); requestArgs.put("email", "new-user@email.com"); requestArgs.put("format", "json"); requestArgs.put("uid", "new-user"); CloseableHttpResponse response = adminApi.execute("PUT", "/admin/user", null, requestArgs); System.out.println(response.getStatusLine()); HttpEntity entity = response.getEntity(); try { System.out.println("\nResponse Content is: " + EntityUtils.toString(entity, "UTF-8") + "\n"); response.close(); } catch (IOException e){ System.err.println ("Encountered an I/O exception."); e.printStackTrace(); } /* * Get a user */ requestArgs = new HashMap(); requestArgs.put("format", "json"); requestArgs.put("uid", "new-user"); response = adminApi.execute("GET", "/admin/user", null, requestArgs); System.out.println(response.getStatusLine()); entity = response.getEntity(); try { System.out.println("\nResponse Content is: " + EntityUtils.toString(entity, "UTF-8") + "\n"); response.close(); } catch (IOException e){ System.err.println ("Encountered an I/O exception."); e.printStackTrace(); } /* * Modify a user */ requestArgs = new HashMap(); requestArgs.put("display-name", "John Doe"); requestArgs.put("email", "johndoe@email.com"); requestArgs.put("format", "json"); requestArgs.put("uid", "new-user"); requestArgs.put("max-buckets", "100"); response = adminApi.execute("POST", "/admin/user", null, requestArgs); System.out.println(response.getStatusLine()); entity = response.getEntity(); try { System.out.println("\nResponse Content is: " + EntityUtils.toString(entity, "UTF-8") + "\n"); response.close(); } catch (IOException e){ System.err.println ("Encountered an I/O exception."); e.printStackTrace(); } /* * Create a subuser */ requestArgs = new HashMap(); requestArgs.put("format", "json"); requestArgs.put("uid", "new-user"); requestArgs.put("subuser", "foobar"); response = adminApi.execute("PUT", "/admin/user", "subuser", requestArgs); System.out.println(response.getStatusLine()); entity = response.getEntity(); try { System.out.println("\nResponse Content is: " + EntityUtils.toString(entity, "UTF-8") + "\n"); response.close(); } catch (IOException e){ System.err.println ("Encountered an I/O exception."); e.printStackTrace(); } /* * Delete a user */ requestArgs = new HashMap(); requestArgs.put("format", "json"); requestArgs.put("uid", "new-user"); response = adminApi.execute("DELETE", "/admin/user", null, requestArgs); System.out.println(response.getStatusLine()); entity = response.getEntity(); try { System.out.println("\nResponse Content is: " + EntityUtils.toString(entity, "UTF-8") + "\n"); response.close(); } catch (IOException e){ System.err.println ("Encountered an I/O exception."); e.printStackTrace(); } } }
Additional Resources
- See the S3 Authentication section in the Red Hat Ceph Storage Developer Guide for additional details.
- For a more extensive explanation of the Amazon S3 authentication procedure, consult the Signing and Authenticating REST Requests section of Amazon Simple Storage Service documentation.
2.3. Creating an administrative user
To run the radosgw-admin
command from the Ceph Object Gateway node, ensure the node has the admin key. The admin key can be copied from any Ceph Monitor node.
Prerequisites
- Root-level access to the Ceph Object Gateway node.
Procedure
Create an object gateway user:
Syntax
radosgw-admin user create --uid="USER_NAME" --display-name="DISPLAY_NAME"
Example
[user@client ~]$ radosgw-admin user create --uid="admin-api-user" --display-name="Admin API User"
The
radosgw-admin
command-line interface will return the user.Example output
{ "user_id": "admin-api-user", "display_name": "Admin API User", "email": "", "suspended": 0, "max_buckets": 1000, "auid": 0, "subusers": [], "keys": [ { "user": "admin-api-user", "access_key": "NRWGT19TWMYOB1YDBV1Y", "secret_key": "gr1VEGIV7rxcP3xvXDFCo4UDwwl2YoNrmtRlIAty" } ], "swift_keys": [], "caps": [], "op_mask": "read, write, delete", "default_placement": "", "placement_tags": [], "bucket_quota": { "enabled": false, "max_size_kb": -1, "max_objects": -1 }, "user_quota": { "enabled": false, "max_size_kb": -1, "max_objects": -1 }, "temp_url_keys": [] }
Assign administrative capabilities to the user you create:
Syntax
radosgw-admin caps add --uid="USER_NAME" --caps="users=*"
Example
[user@client ~]$ radosgw-admin caps add --uid=admin-api-user --caps="users=*"
The
radosgw-admin
command-line interface will return the user. The"caps":
will have the capabilities you assigned to the user:Example output
{ "user_id": "admin-api-user", "display_name": "Admin API User", "email": "", "suspended": 0, "max_buckets": 1000, "auid": 0, "subusers": [], "keys": [ { "user": "admin-api-user", "access_key": "NRWGT19TWMYOB1YDBV1Y", "secret_key": "gr1VEGIV7rxcP3xvXDFCo4UDwwl2YoNrmtRlIAty" } ], "swift_keys": [], "caps": [ { "type": "users", "perm": "*" } ], "op_mask": "read, write, delete", "default_placement": "", "placement_tags": [], "bucket_quota": { "enabled": false, "max_size_kb": -1, "max_objects": -1 }, "user_quota": { "enabled": false, "max_size_kb": -1, "max_objects": -1 }, "temp_url_keys": [] }
Now you have a user with administrative privileges.
2.4. Get user information
Get the user’s information. Cap users
or user-info-without-keys
must be set to read
to run this operation. If cap user-info-without-keys
is set to read
or *
, S3 keys and Swift keys will not be included in the response unless the user running this operation is the system user, an admin user, or the cap users
is set to read
.
Capabilities
users=read or user-info-without-keys=read
Syntax
GET /admin/user?format=json HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user for which the information is requested.
- Type
- String
- Example
-
foo_user
- Required
- Yes
access-key
- Description
- The S3 access key of the user for which the information is requested.
- Type
- String
- Example
-
ABCD0EF12GHIJ2K34LMN
- Required
- No
Response Entities
user
- Description
- A container for the user data information.
- Type
- Container
- Parent
- N/A
user_id
- Description
- The user ID.
- Type
- String
- Parent
-
user
display_name
- Description
- Display name for the user.
- Type
- String
- Parent
-
user
suspended
- Description
- True if the user is suspended.
- Type
- Boolean
- Parent
-
user
max_buckets
- Description
- The maximum number of buckets to be owned by the user.
- Type
- Integer
- Parent
-
user
subusers
- Description
- Subusers associated with this user account.
- Type
- Container
- Parent
-
user
keys
- Description
- S3 keys associated with this user account.
- Type
- Container
- Parent
-
user
swift_keys
- Description
- Swift keys associated with this user account.
- Type
- Container
- Parent
-
user
caps
- Description
- User capabilities.
- Type
- Container
- Parent
-
user
If successful, the response contains the user information.
Special Error Responses
None.
2.5. Create a user
Create a new user. By default, an S3 key pair will be created automatically and returned in the response. If only a access-key
or secret-key
is provided, the omitted key will be automatically generated. By default, a generated key is added to the keyring without replacing an existing key pair. If access-key
is specified and refers to an existing key owned by the user then it will be modified.
Capabilities
`users=write`
Syntax
PUT /admin/user?format=json HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID to be created.
- Type
- String
- Example
-
foo_user
- Required
- Yes
display-name
- Description
- The display name of the user to be created.
- Type
- String
- Example
-
foo_user
- Required
- Yes
email
- Description
- The email address associated with the user.
- Type
- String
- Example
-
foo@bar.com
- Required
- No
key-type
- Description
- Key type to be generated, options are: swift, s3 (default).
- Type
- String
- Example
-
s3
[s3
] - Required
- No
access-key
- Description
- Specify access key.
- Type
- String
- Example
-
ABCD0EF12GHIJ2K34LMN
- Required
- No
secret-key
- Description
- Specify secret key.
- Type
- String
- Example
-
0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
- Required
- No
user-caps
- Description
- User capabilities.
- Type
- String
- Example
-
usage=read, write; users=read
- Required
- No
generate-key
- Description
- Generate a new key pair and add to the existing keyring.
- Type
- Boolean
- Example
- True [True]
- Required
- No
max-buckets
- Description
- Specify the maximum number of buckets the user can own.
- Type
- Integer
- Example
- 500 [1000]
- Required
- No
suspended
- Description
- Specify whether the user should be suspended
- Type
- Boolean
- Example
- False [False]
- Required
- No
Response Entities
user
- Description
- Specify whether the user should be suspended
- Type
- Boolean
- Parent
- No
user_id
- Description
- The user ID.
- Type
- String
- Parent
-
user
display_name
- Description
- Display name for the user.
- Type
- String
- Parent
-
user
suspended
- Description
- True if the user is suspended.
- Type
- Boolean
- Parent
-
user
max_buckets
- Description
- The maximum number of buckets to be owned by the user.
- Type
- Integer
- Parent
-
user
subusers
- Description
- Subusers associated with this user account.
- Type
- Container
- Parent
-
user
keys
- Description
- S3 keys associated with this user account.
- Type
- Container
- Parent
-
user
swift_keys
- Description
- Swift keys associated with this user account.
- Type
- Container
- Parent
-
user
caps
- Description
- User capabilities.
- Type
- Container
- Parent
- If successful, the response contains the user information.
Special Error Responses
UserExists
- Description
- Attempt to create existing user.
- Code
- 409 Conflict
InvalidAccessKey
- Description
- Invalid access key specified.
- Code
- 400 Bad Request
InvalidKeyType
- Description
- Invalid key type specified.
- Code
- 400 Bad Request
InvalidSecretKey
- Description
- Invalid secret key specified.
- Code
- 400 Bad Request
KeyExists
- Description
- Provided access key exists and belongs to another user.
- Code
- 409 Conflict
EmailExists
- Description
- Provided email address exists.
- Code
- 409 Conflict
InvalidCap
- Description
- Attempt to grant invalid admin capability.
- Code
- 400 Bad Request
Additional Resources
- See the Red Hat Ceph Storage Developer Guide for creating subusers.
2.6. Modify a user
Modify an existing user.
Capabilities
`users=write`
Syntax
POST /admin/user?format=json HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID to be created.
- Type
- String
- Example
-
foo_user
- Required
- Yes
display-name
- Description
- The display name of the user to be created.
- Type
- String
- Example
-
foo_user
- Required
- Yes
email
- Description
- The email address associated with the user.
- Type
- String
- Example
-
foo@bar.com
- Required
- No
generate-key
- Description
- Generate a new key pair and add to the existing keyring.
- Type
- Boolean
- Example
- True [False]
- Required
- No
access-key
- Description
- Specify access key.
- Type
- String
- Example
-
ABCD0EF12GHIJ2K34LMN
- Required
- No
secret-key
- Description
- Specify secret key.
- Type
- String
- Example
-
0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
- Required
- No
key-type
- Description
- Key type to be generated, options are: swift, s3 (default).
- Type
- String
- Example
-
s3
- Required
- No
user-caps
- Description
- User capabilities.
- Type
- String
- Example
-
usage=read, write; users=read
- Required
- No
max-buckets
- Description
- Specify the maximum number of buckets the user can own.
- Type
- Integer
- Example
- 500 [1000]
- Required
- No
suspended
- Description
- Specify whether the user should be suspended
- Type
- Boolean
- Example
- False [False]
- Required
- No
Response Entities
user
- Description
- Specify whether the user should be suspended
- Type
- Boolean
- Parent
- No
user_id
- Description
- The user ID.
- Type
- String
- Parent
-
user
display_name
- Description
- Display name for the user.
- Type
- String
- Parent
-
user
suspended
- Description
- True if the user is suspended.
- Type
- Boolean
- Parent
-
user
max_buckets
- Description
- The maximum number of buckets to be owned by the user.
- Type
- Integer
- Parent
-
user
subusers
- Description
- Subusers associated with this user account.
- Type
- Container
- Parent
-
user
keys
- Description
- S3 keys associated with this user account.
- Type
- Container
- Parent
-
user
swift_keys
- Description
- Swift keys associated with this user account.
- Type
- Container
- Parent
-
user
caps
- Description
- User capabilities.
- Type
- Container
- Parent
- If successful, the response contains the user information.
Special Error Responses
InvalidAccessKey
- Description
- Invalid access key specified.
- Code
- 400 Bad Request
InvalidKeyType
- Description
- Invalid key type specified.
- Code
- 400 Bad Request
InvalidSecretKey
- Description
- Invalid secret key specified.
- Code
- 400 Bad Request
KeyExists
- Description
- Provided access key exists and belongs to another user.
- Code
- 409 Conflict
EmailExists
- Description
- Provided email address exists.
- Code
- 409 Conflict
InvalidCap
- Description
- Attempt to grant invalid admin capability.
- Code
- 400 Bad Request
Additional Resources
- See the Red Hat Ceph Storage Developer Guide for modifying subusers.
2.7. Remove a user
Remove an existing user.
Capabilities
`users=write`
Syntax
DELETE /admin/user?format=json HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID to be removed.
- Type
- String
- Example
-
foo_user
- Required
- Yes
purge-data
- Description
- When specified the buckets and objects belonging to the user will also be removed.
- Type
- Boolean
- Example
- True
- Required
- No
Response Entities
None.
Special Error Responses
None.
Additional Resources
- See Red Hat Ceph Storage Developer Guide for removing subusers.
2.8. Create a subuser
Create a new subuser, primarily useful for clients using the Swift API.
Either gen-subuser
or subuser
is required for a valid request. In general, for a subuser to be useful, it must be granted permissions by specifying access
. As with user creation if subuser
is specified without secret
, then a secret key is automatically generated.
Capabilities
`users=write`
Syntax
PUT /admin/user?subuser&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID under which a subuser is to be created.
- Type
- String
- Example
-
foo_user
- Required
- Yes
subuser
- Description
- Specify the subuser ID to be created.
- Type
- String
- Example
-
sub_foo
- Required
-
Yes (or
gen-subuser
)
gen-subuser
- Description
- Specify the subuser ID to be created.
- Type
- String
- Example
-
sub_foo
- Required
-
Yes (or
gen-subuser
)
secret-key
- Description
- Specify secret key.
- Type
- String
- Example
-
0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
- Required
- No
key-type
- Description
- Key type to be generated, options are: swift (default), s3.
- Type
- String
- Example
-
swift
[swift
] - Required
- No
access
- Description
-
Set access permissions for sub-user, should be one of
read, write, readwrite, full
. - Type
- String
- Example
-
read
- Required
- No
generate-secret
- Description
- Generate the secret key.
- Type
- Boolean
- Example
- True [False]
- Required
- No
Response Entities
subusers
- Description
- Subusers associated with the user account.
- Type
- Container
- Parent
- N/A
permissions
- Description
- Subuser access to user account.
- Type
- String
- Parent
-
subusers
If successful, the response contains the subuser information.
Special Error Responses
SubuserExists
- Description
- Specified subuser exists.
- Code
- 409 Conflict
InvalidKeyType
- Description
- Invalid key type specified.
- Code
- 400 Bad Request
InvalidSecretKey
- Description
- Invalid secret key specified.
- Code
- 400 Bad Request
InvalidAccess
- Description
- Invalid subuser access specified
- Code
- 400 Bad Request
2.9. Modify a subuser
Modify an existing subuser.
Capabilities
`users=write`
Syntax
POST /admin/user?subuser&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID under which a subuser is to be created.
- Type
- String
- Example
-
foo_user
- Required
- Yes
subuser
- Description
- The subuser ID to be modified.
- Type
- String
- Example
-
sub_foo
- Required
generate-secret
- Description
- Generate a new secret key for the subuser, replacing the existing key.
- Type
- Boolean
- Example
- True [False]
- Required
- No
secret
- Description
- Specify secret key.
- Type
- String
- Example
-
0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
- Required
- No
key-type
- Description
- Key type to be generated, options are: swift (default), s3.
- Type
- String
- Example
-
swift
[swift
] - Required
- No
access
- Description
-
Set access permissions for sub-user, should be one of
read, write, readwrite, full
. - Type
- String
- Example
-
read
- Required
- No
Response Entities
subusers
- Description
- Subusers associated with the user account.
- Type
- Container
- Parent
- N/A
id
- Description
- Subuser ID
- Type
- String
- Parent
-
subusers
permissions
- Description
- Subuser access to user account.
- Type
- String
- Parent
-
subusers
If successful, the response contains the subuser information.
Special Error Responses
InvalidKeyType
- Description
- Invalid key type specified.
- Code
- 400 Bad Request
InvalidSecretKey
- Description
- Invalid secret key specified.
- Code
- 400 Bad Request
InvalidAccess
- Description
- Invalid subuser access specified
- Code
- 400 Bad Request
2.10. Remove a subuser
Remove an existing subuser.
Capabilities
`users=write`
Syntax
DELETE /admin/user?subuser&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID to be removed.
- Type
- String
- Example
-
foo_user
- Required
- Yes
subuser
- Description
- The subuser ID to be removed.
- Type
- String
- Example
-
sub_foo
- Required
- Yes
purge-keys
- Description
- Remove keys belonging to the subuser.
- Type
- Boolean
- Example
- True [True]
- Required
- No
Response Entities
None.
Special Error Responses
None.
2.11. Add capabilities to a user
Add an administrative capability to a specified user.
Capabilities
`users=write`
Syntax
PUT /admin/user?caps&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID to add an administrative capability to.
- Type
- String
- Example
-
foo_user
- Required
- Yes
user-caps
- Description
- The administrative capability to add to the user.
- Type
- String
- Example
-
usage=read, write
- Required
- Yes
Response Entities
user
- Description
- A container for the user data information.
- Type
- Container
- Parent
- N/A
user_id
- Description
- The user ID
- Type
- String
- Parent
-
user
caps
- Description
- User capabilities,
- Type
- Container
- Parent
-
user
If successful, the response contains the user’s capabilities.
Special Error Responses
InvalidCap
- Description
- Attempt to grant invalid admin capability.
- Code
- 400 Bad Request
2.12. Remove capabilities from a user
Remove an administrative capability from a specified user.
Capabilities
`users=write`
Syntax
DELETE /admin/user?caps&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID to remove an administrative capability from.
- Type
- String
- Example
-
foo_user
- Required
- Yes
user-caps
- Description
- The administrative capabilities to remove from the user.
- Type
- String
- Example
-
usage=read, write
- Required
- Yes
Response Entities
user
- Description
- A container for the user data information.
- Type
- Container
- Parent
- N/A
user_id
- Description
- The user ID.
- Type
- String
- Parent
-
user
caps
- Description
- User capabilities.
- Type
- Container
- Parent
-
user
If successful, the response contains the user’s capabilities.
Special Error Responses
InvalidCap
- Description
- Attempt to remove an invalid admin capability.
- Code
- 400 Bad Request
NoSuchCap
- Description
- User does not possess specified capability.
- Code
- 404 Not Found
2.13. Create a key
Create a new key. If a subuser
is specified then by default created keys will be swift type. If only one of access-key
or secret-key
is provided the committed key will be automatically generated, that is if only secret-key
is specified then access-key
will be automatically generated. By default, a generated key is added to the keyring without replacing an existing key pair. If access-key
is specified and refers to an existing key owned by the user then it will be modified. The response is a container listing all keys of the same type as the key created.
When creating a swift key, specifying the option access-key
will have no effect. Additionally, only one swift key might be held by each user or subuser.
Capabilities
`users=write`
Syntax
PUT /admin/user?key&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user ID to receive the new key.
- Type
- String
- Example
-
foo_user
- Required
- Yes
subuser
- Description
- The subuser ID to receive the new key.
- Type
- String
- Example
-
sub_foo
- Required
- No
key-type
- Description
- Key type to be generated, options are: swift, s3 (default).
- Type
- String
- Example
-
s3
[s3
] - Required
- No
access-key
- Description
- Specify access key.
- Type
- String
- Example
-
AB01C2D3EF45G6H7IJ8K
- Required
- No
secret-key
- Description
- Specify secret key.
- Type
- String
- Example
-
0ab/CdeFGhij1klmnopqRSTUv1WxyZabcDEFgHij
- Required
- No
generate-key
- Description
- Generate a new key pair and add to the existing keyring.
- Type
- Boolean
- Example
-
True [
True
] - Required
- No
Response Entities
keys
- Description
- Keys of type created associated with this user account.
- Type
- Container
- Parent
- N/A
user
- Description
- The user account associated with the key.
- Type
- String
- Parent
-
keys
access-key
- Description
- The access key.
- Type
- String
- Parent
-
keys
secret-key
- Description
- The secret key.
- Type
- String
- Parent
-
keys
Special Error Responses
InvalidAccessKey
- Description
- Invalid access key specified.
- Code
- 400 Bad Request
InvalidKeyType
- Description
- Invalid key type specified.
- Code
- 400 Bad Request
InvalidSecretKey
- Description
- Invalid secret key specified.
- Code
- 400 Bad Request
InvalidKeyType
- Description
- Invalid key type specified.
- Code
- 400 Bad Request
KeyExists
- Description
- Provided access key exists and belongs to another user.
- Code
- 409 Conflict
2.14. Remove a key
Remove an existing key.
Capabilities
`users=write`
Syntax
DELETE /admin/user?key&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
access-key
- Description
- The S3 access key belonging to the S3 key pair to remove.
- Type
- String
- Example
-
AB01C2D3EF45G6H7IJ8K
- Required
- Yes
uid
- Description
- The user to remove the key from.
- Type
- String
- Example
-
foo_user
- Required
- No
subuser
- Description
- The subuser to remove the key from.
- Type
- String
- Example
-
sub_foo
- Required
- No
key-type
- Description
Key type to be removed, options are: swift, s3.
NoteRequired to remove swift key.
- Type
- String
- Example
-
swift
- Required
- No
Special Error Responses
None.
Response Entities
None.
2.15. Bucket notifications
As a storage administrator, you can use these APIs to provide configuration and control interfaces for the bucket notification mechanism. The API topics are named objects that contain the definition of a specific endpoint. Bucket notifications associate topics with a specific bucket. The S3 bucket operations section gives more details on bucket notifications.
In all topic actions, the parameters are URL encoded, and sent in the message body using application/x-www-form-urlencoded
content type.
Any bucket notification already associated with the topic needs to be re-created for the topic update to take effect.
Prerequisites
- Create bucket notifications on the Ceph Object Gateway.
2.15.1. Overview of bucket notifications
Bucket notifications provide a way to send information out of the Ceph Object Gateway when certain events happen in the bucket. Bucket notifications can be sent to HTTP, AMQP0.9.1, and Kafka endpoints. A notification entry must be created to send bucket notifications for events on a specific bucket and to a specific topic. A bucket notification can be created on a subset of event types or by default for all event types. The bucket notification can filter out events based on key prefix or suffix, regular expression matching the keys, and the metadata attributes attached to the object, or the object tags. Bucket notifications have a REST API to provide configuration and control interfaces for the bucket notification mechanism.
Sending a bucket notification when an object is synced to a zone lets the external system get information into the zone syncing status at the object level. The bucket notification event types s3:ObjectSynced:*
and s3:ObjectSynced:Created
, when configured via the bucket notification mechanism, send a notification event from the synced RGW upon successful sync of an object. Both the topics and the notification configuration should be done separately in each zone from which the notification events are being sent.
2.15.2. Persistent notifications
Persistent notifications enable reliable and asynchronous delivery of notifications from the Ceph Object Gateway to the endpoint configured at the topic. Regular notifications are also reliable because the delivery to the endpoint is performed synchronously during the request. With persistent notifications, the Ceph Object Gateway retries sending notifications even when the endpoint is down or there are network issues during the operations, that is notifications are retried if not successfully delivered to the endpoint. Notifications are sent only after all other actions related to the notified operation are successful. If an endpoint goes down for a longer duration, the notification queue fills up and the S3 operations that have configured notifications for these endpoints will fail.
With kafka-ack-level=none
, there is no indication for message failures, and therefore messages sent while broker is down are not retried, when the broker is up again. After the broker is up again, only new notifications are seen.
2.15.3. Creating a topic
You can create topics before creating bucket notifications. A topic is a Simple Notification Service (SNS) entity and all the topic operations, that is, create
, delete
, list
, and get
, are SNS operations. The topic needs to have endpoint parameters that are used when a bucket notification is created. Once the request is successful, the response includes the topic Amazon Resource Name (ARN) that can be used later to reference this topic in the bucket notification request.
A topic_arn
provides the bucket notification configuration and is generated after a topic is created.
Prerequisites
- A running Red Hat Ceph Storage cluster.
- Root-level access.
- Installation of the Ceph Object Gateway.
- User access key and secret key.
- Endpoint parameters.
Procedure
Create a topic with the following request format:
Syntax
POST Action=CreateTopic &Name=TOPIC_NAME [&Attributes.entry.1.key=amqp-exchange&Attributes.entry.1.value=EXCHANGE] [&Attributes.entry.2.key=amqp-ack-level&Attributes.entry.2.value=none|broker|routable] [&Attributes.entry.3.key=verify-ssl&Attributes.entry.3.value=true|false] [&Attributes.entry.4.key=kafka-ack-level&Attributes.entry.4.value=none|broker] [&Attributes.entry.5.key=use-ssl&Attributes.entry.5.value=true|false] [&Attributes.entry.6.key=ca-location&Attributes.entry.6.value=FILE_PATH] [&Attributes.entry.7.key=OpaqueData&Attributes.entry.7.value=OPAQUE_DATA] [&Attributes.entry.8.key=push-endpoint&Attributes.entry.8.value=ENDPOINT] [&Attributes.entry.9.key=persistent&Attributes.entry.9.value=true|false]
Here are the request parameters:
-
Endpoint
: URL of an endpoint to send notifications to. -
OpaqueData
: opaque data is set in the topic configuration and added to all notifications triggered by the topic. -
persistent
: indication of whether notifications to this endpoint are persistent that is asynchronous or not. By default the value isfalse
. HTTP endpoint:
-
URL
: https://FQDN:PORT -
port defaults to
: Use 80/443 for HTTP[S] accordingly. -
verify-ssl
: Indicates whether the server certificate is validated by the client or not. By default , it istrue
.
-
AMQP0.9.1 endpoint:
-
URL
: amqp://USER:PASSWORD@FQDN:PORT[/VHOST]. -
User and password defaults to:
guest
andguest
respectively. - User and password details should be provided over HTTPS, otherwise the topic creation request is rejected.
-
port defaults to
: 5672. -
vhost
defaults to: “/” -
amqp-exchange
: The exchanges must exist and be able to route messages based on topics. This is a mandatory parameter for AMQP0.9.1. Different topics pointing to the same endpoint must use the same exchange. amqp-ack-level
: No end to end acknowledgment is required, as messages may persist in the broker before being delivered into their final destination. Three acknowledgment methods exist:-
none
: Message is considereddelivered
if sent to the broker. -
broker
: By default, the message is considereddelivered
if acknowledged by the broker. routable
: Message is considereddelivered
if the broker can route to a consumer.NoteThe key and value of a specific parameter do not have to reside in the same line, or in any specific order, but must use the same index. Attribute indexing does not need to be sequential or start from any specific value.
NoteThe
topic-name
is used for the AMQP topic.
-
-
Kafka endpoint:
-
URL
: kafka://USER:PASSWORD@FQDN:PORT. -
use-ssl
is set tofalse
by default. Ifuse-ssl
is set totrue
, secure connection is used for connecting with the broker. -
If
ca-location
is provided, and secure connection is used, the specified CA will be used, instead of the default one, to authenticate the broker. - User and password can only be provided over HTTP[S]. Otherwise, the topic creation request is rejected.
-
User and password may only be provided together with
use-ssl
, otherwise, the connection to the broker will fail. -
port defaults to
: 9092. kafka-ack-level
: no end to end acknowledgment required, as messages may persist in the broker before being delivered into their final destination. Two acknowledgment methods exist:-
none
: message is considereddelivered
if sent to the broker. -
broker
: By default, the message is considereddelivered
if acknowledged by the broker.
-
-
-
The following is an example of the response format:
Example
<CreateTopicResponse xmlns="https://sns.amazonaws.com/doc/2010-03-31/"> <CreateTopicResult> <TopicArn></TopicArn> </CreateTopicResult> <ResponseMetadata> <RequestId></RequestId> </ResponseMetadata> </CreateTopicResponse>
The topic Amazon Resource Name (ARN) in the response will have the following format: arn:aws:sns:ZONE_GROUP:TENANT:TOPIC
The following is an example of AMQP0.9.1 endpoint:
Example
client.create_topic(Name='my-topic' , Attributes={'push-endpoint': 'amqp://127.0.0.1:5672', 'amqp-exchange': 'ex1', 'amqp-ack-level': 'broker'}) "
2.15.4. Getting topic information
Returns information about a specific topic. This can include endpoint information if it is provided.
Prerequisites
- A running Red Hat Ceph Storage cluster.
- Root-level access.
- Installation of the Ceph Object Gateway.
- User access key and secret key.
- Endpoint parameters.
Procedure
Get topic information with the following request format:
Syntax
POST Action=GetTopic &TopicArn=TOPIC_ARN
Here is an example of the response format:
<GetTopicResponse> <GetTopicRersult> <Topic> <User></User> <Name></Name> <EndPoint> <EndpointAddress></EndpointAddress> <EndpointArgs></EndpointArgs> <EndpointTopic></EndpointTopic> <HasStoredSecret></HasStoredSecret> <Persistent></Persistent> </EndPoint> <TopicArn></TopicArn> <OpaqueData></OpaqueData> </Topic> </GetTopicResult> <ResponseMetadata> <RequestId></RequestId> </ResponseMetadata> </GetTopicResponse>
The following are the tags and definitions:
-
User
: Name of the user that created the topic. -
Name
: Name of the topic. JSON formatted endpoints include:
EndpointAddress
: The endpoint URL. If the endpoint URL contains user and password information, the request must be made over HTTPS. Otheriwse, the topic get request is rejected.-
EndPointArgs
: The endpoint arguments. -
EndpointTopic
: The topic name that is be sent to the endpoint can be different than the above example topic name. -
HasStoredSecret
:true
when the endpoint URL contains user and password information. -
Persistent
:true
when the topic is persistent.
-
-
TopicArn
: Topic ARN. -
OpaqueData
: This is an opaque data set on the topic.
-
2.15.5. Listing topics
List the topics that the user has defined.
Prerequisites
- A running Red Hat Ceph Storage cluster.
- Root-level access.
- Installation of the Ceph Object Gateway.
- User access key and secret key.
- Endpoint parameters.
Procedure
List topic information with the following request format:
Syntax
POST Action=ListTopics
Here is an example of the response format:
<ListTopicdResponse xmlns="https://sns.amazonaws.com/doc/2020-03-31/"> <ListTopicsRersult> <Topics> <member> <User></User> <Name></Name> <EndPoint> <EndpointAddress></EndpointAddress> <EndpointArgs></EndpointArgs> <EndpointTopic></EndpointTopic> </EndPoint> <TopicArn></TopicArn> <OpaqueData></OpaqueData> </member> </Topics> </ListTopicsResult> <ResponseMetadata> <RequestId></RequestId> </ResponseMetadata> </ListTopicsResponse>
NoteIf endpoint URL contains user and password information, in any of the topics, the request must be made over HTTPS. Otherwise, the topic list request is rejected.
2.15.6. Deleting topics
Removing a deleted topic results in no operation and is not a failure.
Prerequisites
- A running Red Hat Ceph Storage cluster.
- Root-level access.
- Installation of the Ceph Object Gateway.
- User access key and secret key.
- Endpoint parameters.
Procedure
Delete a topic with the following request format:
Syntax
POST Action=DeleteTopic &TopicArn=TOPIC_ARN
Here is an example of the response format:
<DeleteTopicResponse xmlns="https://sns.amazonaws.com/doc/2020-03-31/"> <ResponseMetadata> <RequestId></RequestId> </ResponseMetadata> </DeleteTopicResponse>
2.15.7. Using the command-line interface for topic management
You can list, get, and remove topics using the command-line interface.
Prerequisites
- Root-level access to the Ceph Object Gateway node.
Procedure
To get a list of all topics of a user:
Syntax
radosgw-admin topic list --uid=USER_ID
Example
[root@rgw ~]# radosgw-admin topic list --uid=example
To get configuration of a specific topic:
Syntax
radosgw-admin topic get --uid=USER_ID --topic=TOPIC_NAME
Example
[root@rgw ~]# radosgw-admin topic get --uid=example --topic=example-topic
To remove a specific topic:
Syntax
radosgw-admin topic rm --uid=USER_ID --topic=TOPIC_NAME
Example
[root@rgw ~]# radosgw-admin topic rm --uid=example --topic=example-topic
2.15.8. Managing notification configuration
You can list, get, and remove notification configuration of buckets using the command-line interface.
Prerequisites
- A running Red Hat Ceph Storage cluster.
- A Ceph Object Gateway configured.
Procedure
List all the bucket notification configuration:
Syntax
radosgw-admin notification list --bucket=BUCKET_NAME
Example
[root@host04 ~]# radosgw-admin notification list --bucket bkt2 { "notifications": [ { "TopicArn": "arn:aws:sns:default::topic1", "Id": "notif1", "Events": [ "s3:ObjectCreated:*", "s3:ObjectRemoved:*" ], "Filter": { "S3Key": {}, "S3Metadata": {}, "S3Tags": {} } }, { "TopicArn": "arn:aws:sns:default::topic1", "Id": "notif2", "Events": [ "s3:ObjectSynced:*" ], "Filter": { "S3Key": {}, "S3Metadata": {}, "S3Tags": {} } } ] }
Get the bucket notification configuration:
Syntax
radosgw-admin notification get --bucket BUCKET_NAME --notification-id NOTIFICATION_ID
Example
[root@host04 ~]# radosgw-admin notification get --bucket bkt2 --notification-id notif2 { "TopicArn": "arn:aws:sns:default::topic1", "Id": "notif2", "Events": [ "s3:ObjectSynced:*" ], "Filter": { "S3Key": {}, "S3Metadata": {}, "S3Tags": {} } }
Remove a specific bucket notification configuration:
Syntax
radosgw-admin notification rm --bucket BUCKET_NAME [--notification-id NOTIFICATION_ID]
Here, NOTIFICATION_ID is optional. If it is not specified, the command removes all the notification configurations of that bucket.
Example
[root@host04 ~]# radosgw-admin notification rm --bucket bkt2 --notification-id notif1
2.15.9. Event record
An event holds information about the operation done by the Ceph Object Gateway and is sent as a payload over the chosen endpoint, such as HTTP, HTTPS, Kafka, or AMQ0.9.1. The event record is in JSON format.
The following ObjectLifecycle:Expiration
events are supported:
-
ObjectLifecycle:Expiration:Current
-
ObjectLifecycle:Expiration:NonCurrent
-
ObjectLifecycle:Expiration:DeleteMarker
-
ObjectLifecycle:Expiration:AbortMultipartUpload
Example
{"Records":[ { "eventVersion":"2.1", "eventSource":"ceph:s3", "awsRegion":"us-east-1", "eventTime":"2019-11-22T13:47:35.124724Z", "eventName":"ObjectCreated:Put", "userIdentity":{ "principalId":"tester" }, "requestParameters":{ "sourceIPAddress":"" }, "responseElements":{ "x-amz-request-id":"503a4c37-85eb-47cd-8681-2817e80b4281.5330.903595", "x-amz-id-2":"14d2-zone1-zonegroup1" }, "s3":{ "s3SchemaVersion":"1.0", "configurationId":"mynotif1", "bucket":{ "name":"mybucket1", "ownerIdentity":{ "principalId":"tester" }, "arn":"arn:aws:s3:us-east-1::mybucket1", "id":"503a4c37-85eb-47cd-8681-2817e80b4281.5332.38" }, "object":{ "key":"myimage1.jpg", "size":"1024", "eTag":"37b51d194a7513e45b56f6524f2d51f2", "versionId":"", "sequencer": "F7E6D75DC742D108", "metadata":[], "tags":[] } }, "eventId":"", "opaqueData":"me@example.com" } ]}
These are the event record keys and their definitions:
-
awsRegion
: Zonegroup. -
eventTime
: Timestamp that indicates when the event was triggered. -
eventName
: The type of the event. It can beObjectCreated
,ObjectRemoved
, orObjectLifecycle:Expiration
-
userIdentity.principalId
: The identity of the user that triggered the event. -
requestParameters.sourceIPAddress
: The IP address of the client that triggered the event. This field is not supported. -
responseElements.x-amz-request-id
: The request ID that triggered the event. -
responseElements.x_amz_id_2
: The identity of the Ceph Object Gateway on which the event was triggered. The identity format is RGWID-ZONE-ZONEGROUP. -
s3.configurationId
: The notification ID that created the event. -
s3.bucket.name
: The name of the bucket. -
s3.bucket.ownerIdentity.principalId
: The owner of the bucket. -
s3.bucket.arn
: Amazon Resource Name (ARN) of the bucket. -
s3.bucket.id
: Identity of the bucket. -
s3.object.key
: The object key. -
s3.object.size
: The size of the object. -
s3.object.eTag
: The object etag. -
s3.object.version
: The object version in a versioned bucket. -
s3.object.sequencer
: Monotonically increasing identifier of the change per object in the hexadecimal format. -
s3.object.metadata
: Any metadata set on the object sent asx-amz-meta
. -
s3.object.tags
: Any tags set on the object. -
s3.eventId
: Unique identity of the event. -
s3.opaqueData
: Opaque data is set in the topic configuration and added to all notifications triggered by the topic.
Additional Resources
- See the Event Message Structure for more information.
2.15.10. Supported event types
The following event types are supported:
-
s3:ObjectCreated:*
-
s3:ObjectCreated:Put
-
s3:ObjectCreated:Post
-
s3:ObjectCreated:Copy
-
s3:ObjectCreated:CompleteMultipartUpload
In multipart upload, an ObjectCreated:CompleteMultipartUpload
notification is sent at the end of the process.
-
s3:ObjectRemoved:*
-
s3:ObjectRemoved:Delete
-
s3:ObjectRemoved:DeleteMarkerCreated
-
s3:ObjectLifecycle:Expiration:Current
-
s3:ObjectLifecycle:Expiration:NonCurrent
-
s3:ObjectLifecycle:Expiration:DeleteMarker
-
s3:ObjectLifecycle:Expiration:AbortMultipartUpload
-
s3:ObjectLifecycle:Transition:Current
-
s3:ObjectLifecycle:Transition:NonCurrent
-
s3:ObjectSynced:Create
2.15.11. Get bucket information
Get information about a subset of the existing buckets. If uid
is specified without bucket
then all buckets belonging to the user will be returned. If bucket
alone is specified, information for that particular bucket will be retrieved.
Capabilities
`buckets=read`
Syntax
GET /admin/bucket?format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket to return info on.
- Type
- String
- Example
-
foo_bucket
- Required
- No
uid
- Description
- The user to retrieve bucket information for.
- Type
- String
- Example
-
foo_user
- Required
- No
stats
- Description
- Return bucket statistics.
- Type
- Boolean
- Example
- True [False]
- Required
- No
Response Entities
stats
- Description
- Per bucket information.
- Type
- Container
- Parent
- N/A
buckets
- Description
- Contains a list of one or more bucket containers.
- Type
- Container
- Parent
-
buckets
bucket
- Description
- Container for single bucket information.
- Type
- Container
- Parent
-
buckets
name
- Description
- The name of the bucket.
- Type
- String
- Parent
-
bucket
pool
- Description
- The pool the bucket is stored in.
- Type
- String
- Parent
-
bucket
id
- Description
- The unique bucket ID.
- Type
- String
- Parent
-
bucket
marker
- Description
- Internal bucket tag.
- Type
- String
- Parent
-
bucket
owner
- Description
- The user ID of the bucket owner.
- Type
- String
- Parent
-
bucket
usage
- Description
- Storage usage information.
- Type
- Container
- Parent
-
bucket
index
- Description
- Status of bucket index.
- Type
- String
- Parent
-
bucket
If successful, then the request returns a bucket’s container with the bucket information.
Special Error Responses
IndexRepairFailed
- Description
- Bucket index repair failed.
- Code
- 409 Conflict
2.15.12. Check a bucket index
Check the index of an existing bucket.
To check multipart object accounting with check-objects
, fix
must be set to True.
Capabilities
buckets=write
Syntax
GET /admin/bucket?index&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket to return info on.
- Type
- String
- Example
-
foo_bucket
- Required
- Yes
check-objects
- Description
- Check multipart object accounting.
- Type
- Boolean
- Example
- True [False]
- Required
- No
fix
- Description
- Also fix the bucket index when checking.
- Type
- Boolean
- Example
- False [False]
- Required
- No
Response Entities
index
- Description
- Status of bucket index.
- Type
- String
Special Error Responses
IndexRepairFailed
- Description
- Bucket index repair failed.
- Code
- 409 Conflict
2.15.13. Remove a bucket
Removes an existing bucket.
Capabilities
`buckets=write`
Syntax
DELETE /admin/bucket?format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket to remove.
- Type
- String
- Example
-
foo_bucket
- Required
- Yes
purge-objects
- Description
- Remove a bucket’s objects before deletion.
- Type
- Boolean
- Example
- True [False]
- Required
- No
Response Entities
None.
Special Error Responses
BucketNotEmpty
- Description
- Attempted to delete non-empty bucket.
- Code
- 409 Conflict
ObjectRemovalFailed
- Description
- Unable to remove objects.
- Code
- 409 Conflict
2.15.14. Link a bucket
Link a bucket to a specified user, unlinking the bucket from any previous user.
Capabilities
`buckets=write`
Syntax
PUT /admin/bucket?format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket to unlink.
- Type
- String
- Example
-
foo_bucket
- Required
- Yes
uid
- Description
- The user ID to link the bucket to.
- Type
- String
- Example
-
foo_user
- Required
- Yes
Response Entities
bucket
- Description
- Container for single bucket information.
- Type
- Container
- Parent
- N/A
name
- Description
- The name of the bucket.
- Type
- String
- Parent
-
bucket
pool
- Description
- The pool the bucket is stored in.
- Type
- String
- Parent
-
bucket
id
- Description
- The unique bucket ID.
- Type
- String
- Parent
-
bucket
marker
- Description
- Internal bucket tag.
- Type
- String
- Parent
-
bucket
owner
- Description
- The user ID of the bucket owner.
- Type
- String
- Parent
-
bucket
usage
- Description
- Storage usage information.
- Type
- Container
- Parent
-
bucket
index
- Description
- Status of bucket index.
- Type
- String
- Parent
-
bucket
Special Error Responses
BucketUnlinkFailed
- Description
- Unable to unlink bucket from specified user.
- Code
- 409 Conflict
BucketLinkFailed
- Description
- Unable to link bucket to specified user.
- Code
- 409 Conflict
2.15.15. Unlink a bucket
Unlink a bucket from a specified user. Primarily useful for changing bucket ownership.
Capabilities
`buckets=write`
Syntax
POST /admin/bucket?format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket to unlink.
- Type
- String
- Example
-
foo_bucket
- Required
- Yes
uid
- Description
- The user ID to link the bucket to.
- Type
- String
- Example
-
foo_user
- Required
- Yes
Response Entities
None.
Special Error Responses
BucketUnlinkFailed
- Description
- Unable to unlink bucket from specified user.
- Type
- 409 Conflict
2.15.16. Get a bucket or object policy
Read the policy of an object or bucket.
Capabilities
`buckets=read`
Syntax
GET /admin/bucket?policy&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket to read the policy from.
- Type
- String
- Example
-
foo_bucket
- Required
- Yes
object
- Description
- The object to read the policy from.
- Type
- String
- Example
-
foo.txt
- Required
- No
Response Entities
policy
- Description
- Access control policy.
- Type
- Container
- Parent
- N/A
If successful, returns the object or bucket policy
Special Error Responses
IncompleteBody
- Description
- Either bucket was not specified for a bucket policy request or bucket and object were not specified for an object policy request.
- Code
- 400 Bad Request
2.15.17. Remove an object
Remove an existing object.
Does not require owner to be non-suspended.
Capabilities
`buckets=write`
Syntax
DELETE /admin/bucket?object&format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket containing the object to be removed.
- Type
- String
- Example
-
foo_bucket
- Required
- Yes
object
- Description
- The object to remove
- Type
- String
- Example
-
foo.txt
- Required
- Yes
Response Entities
None.
Special Error Responses
NoSuchObject
- Description
- Specified object does not exist.
- Code
- 404 Not Found
ObjectRemovalFailed
- Description
- Unable to remove objects.
- Code
- 409 Conflict
2.15.18. Quotas
The administrative Operations API enables you to set quotas on users and on buckets owned by users. Quotas include the maximum number of objects in a bucket and the maximum storage size in megabytes.
To view quotas, the user must have a users=read
capability. To set, modify or disable a quota, the user must have users=write
capability.
Valid parameters for quotas include:
-
Bucket: The
bucket
option allows you to specify a quota for buckets owned by a user. -
Maximum Objects: The
max-objects
setting allows you to specify the maximum number of objects. A negative value disables this setting. -
Maximum Size: The
max-size
option allows you to specify a quota for the maximum number of bytes. A negative value disables this setting. -
Quota Scope: The
quota-scope
option sets the scope for the quota. The options arebucket
anduser
.
2.15.19. Get a user quota
To get a quota, the user must have users
capability set with read
permission.
Syntax
GET /admin/user?quota&uid=UID"a-type=user
2.15.20. Set a user quota
To set a quota, the user must have users
capability set with write
permission.
Syntax
PUT /admin/user?quota&uid=UID"a-type=user
The content must include a JSON representation of the quota settings as encoded in the corresponding read operation.
2.15.21. Get a bucket quota
Get information about a subset of the existing buckets. If uid
is specified without bucket
then all buckets belonging to the user will be returned. If bucket
alone is specified, information for that particular bucket will be retrieved.
Capabilities
`buckets=read`
Syntax
GET /admin/bucket?format=json HTTP/1.1
Host FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
bucket
- Description
- The bucket to return info on.
- Type
- String
- Example
-
foo_bucket
- Required
- No
uid
- Description
- The user to retrieve bucket information for.
- Type
- String
- Example
-
foo_user
- Required
- No
stats
- Description
- Return bucket statistics.
- Type
- Boolean
- Example
- True [False]
- Required
- No
Response Entities
stats
- Description
- Per bucket information.
- Type
- Container
- Parent
- N/A
buckets
- Description
- Contains a list of one or more bucket containers.
- Type
- Container
- Parent
- N/A
bucket
- Description
- Container for single bucket information.
- Type
- Container
- Parent
-
buckets
name
- Description
- The name of the bucket.
- Type
- String
- Parent
-
bucket
pool
- Description
- The pool the bucket is stored in.
- Type
- String
- Parent
-
bucket
id
- Description
- The unique bucket ID.
- Type
- String
- Parent
-
bucket
marker
- Description
- Internal bucket tag.
- Type
- String
- Parent
-
bucket
owner
- Description
- The user ID of the bucket owner.
- Type
- String
- Parent
-
bucket
usage
- Description
- Storage usage information.
- Type
- Container
- Parent
-
bucket
index
- Description
- Status of bucket index.
- Type
- String
- Parent
-
bucket
If successful, then the request returns a bucket’s container with the bucket information.
Special Error Responses
IndexRepairFailed
- Description
- Bucket index repair failed.
- Code
- 409 Conflict
2.15.22. Set a bucket quota
To set a quota, the user must have users
capability set with write
permission.
Syntax
PUT /admin/user?quota&uid=UID"a-type=bucket
The content must include a JSON representation of the quota settings as encoded in the corresponding read operation.
2.15.23. Get usage information
Requesting bandwidth usage information.
Capabilities
`usage=read`
Syntax
GET /admin/usage?format=json HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user for which the information is requested.
- Type
- String
- Required
- Yes
start
- Description
-
The date, and optionally, the time of when the data request started. For example,
2012-09-25 16:00:00
. - Type
- String
- Required
- No
end
- Description
-
The date, and optionally, the time of when the data request ended. For example,
2012-09-25 16:00:00
. - Type
- String
- Required
- No
show-entries
- Description
- Specifies whether data entries should be returned.
- Type
- Boolean
- Required
- No
show-summary
- Description
- Specifies whether data entries should be returned.
- Type
- Boolean
- Required
- No
Response Entities
usage
- Description
- A container for the usage information.
- Type
- Container
entries
- Description
- A container for the usage entries information.
- Type
- Container
user
- Description
- A container for the user data information.
- Type
- Container
owner
- Description
- The name of the user that owns the buckets.
- Type
- String
bucket
- Description
- The bucket name.
- Type
- String
time
- Description
- Time lower bound for which data is being specified that is rounded to the beginning of the first relevant hour.
- Type
- String
epoch
- Description
-
The time specified in seconds since
1/1/1970
. - Type
- String
categories
- Description
- A container for stats categories.
- Type
- Container
entry
- Description
- A container for stats entry.
- Type
- Container
category
- Description
- Name of request category for which the stats are provided.
- Type
- String
bytes_sent
- Description
- Number of bytes sent by the Ceph Object Gateway.
- Type
- Integer
bytes_received
- Description
- Number of bytes received by the Ceph Object Gateway.
- Type
- Integer
ops
- Description
- Number of operations.
- Type
- Integer
successful_ops
- Description
- Number of successful operations.
- Type
- Integer
summary
- Description
- Number of successful operations.
- Type
- Container
total
- Description
- A container for stats summary aggregated total.
- Type
- Container
If successful, the response contains the requested information.
2.15.24. Remove usage information
Remove usage information. With no dates specified, removes all usage information.
Capabilities
`usage=write`
Syntax
DELETE /admin/usage?format=json HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
Request Parameters
uid
- Description
- The user for which the information is requested.
- Type
- String
- Example
-
foo_user
- Required
- Yes
start
- Description
-
The date, and optionally, the time of when the data request started. For example,
2012-09-25 16:00:00
. - Type
- String
- Example
-
2012-09-25 16:00:00
- Required
- No
end
- Description
-
The date, and optionally, the time of when the data request ended. For example,
2012-09-25 16:00:00
. - Type
- String
- Example
-
2012-09-25 16:00:00
- Required
- No
remove-all
- Description
-
Required when
uid
is not specified, in order to acknowledge multi-user data removal. - Type
- Boolean
- Example
- True [False]
- Required
- No
2.15.25. Standard error responses
The following list details standard error responses and their descriptions.
AccessDenied
- Description
- Access denied.
- Code
- 403 Forbidden
InternalError
- Description
- Internal server error.
- Code
- 500 Internal Server Error
NoSuchUser
- Description
- User does not exist.
- Code
- 404 Not Found
NoSuchBucket
- Description
- Bucket does not exist.
- Code
- 404 Not Found
NoSuchKey
- Description
- No such access key.
- Code
- 404 Not Found