SupportConsoleDevelopersStart a trialContact

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.

Note

Red Hat recommends using the command-line interface when configuring the Ceph Object Gateway.

Basic Access Diagram

The administrative API provides the following functionality:

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:

  1. Builds a URI.
  2. Builds an HTTP header string.
  3. Instantiates an HTTP request, for example, PUT, POST, GET, DELETE.
  4. Adds the Date header to the HTTP header string and the request header.
  5. Adds the Authorization header to the HTTP request header.
  6. Instantiates an HTTP client and passes it the instantiated HTTP request.
  7. Makes a request.
  8. 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:

  1. Adds a request type, for example, PUT, POST, GET, DELETE.
  2. Adds the date.
  3. 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

2.3. Creating an administrative user

Important

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

  1. 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": []
}

  2. 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

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

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

2.8. Create a subuser

Create a new subuser, primarily useful for clients using the Swift API.

Note

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.

Note

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.

Note

Required 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.

Note

In all topic actions, the parameters are URL encoded, and sent in the message body using application/x-www-form-urlencoded content type.

Note

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.

Note

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.

Note

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

  1. 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 is false.

    • 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 is true.

    • AMQP0.9.1 endpoint:

      • URL: amqp://USER:PASSWORD@FQDN:PORT[/VHOST].
      • User and password defaults to: guest and guest 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 considered delivered if sent to the broker.
        • broker: By default, the message is considered delivered if acknowledged by the broker.

        • routable: Message is considered delivered if the broker can route to a consumer.

          Note

          The 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.

          Note

          The topic-name is used for the AMQP topic.

    • Kafka endpoint:

      • URL: kafka://USER:PASSWORD@FQDN:PORT.
      • use-ssl is set to false by default. If use-ssl is set to true, 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 considered delivered if sent to the broker.
        • broker: By default, the message is considered delivered 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>

Note

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

  1. 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

  1. 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>
    Note

    If 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

  1. 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

  1. 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

  2. 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

  3. 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 be ObjectCreated, ObjectRemoved, or ObjectLifecycle: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 as x-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

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
Note

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.

Note

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.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.

Note

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 are bucket and user.

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&quota-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&quota-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&quota-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
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.