S3-compatible object upload, download, listing, deletion, and metadata operations within Ceph Object Storage buckets
openapi: 3.1.0
info:
title: Rook Ceph Object Storage Buckets Objects API
description: Rook provisions Ceph Object Storage gateways (Ceph RADOS Gateway / RGW) that expose an S3-compatible REST API for object storage operations. The gateway is managed through Rook CephObjectStore and CephObjectStoreUser Kubernetes CRDs. Applications interact with the object storage using standard S3 API semantics including bucket operations, object CRUD, multipart uploads, access control lists, and presigned URLs. User credentials are provisioned via CephObjectStoreUser CRDs and accessed through Kubernetes Secrets.
version: 1.0.0
contact:
name: Rook Community
url: https://rook.io/community/
termsOfService: https://rook.io/
servers:
- url: http://{rgw-host}:{port}
description: Ceph RADOS Gateway endpoint as provisioned by Rook CephObjectStore
variables:
rgw-host:
default: rook-ceph-rgw-my-store.rook-ceph.svc
description: Kubernetes Service hostname for the RGW endpoint as created by the CephObjectStore CRD. Format is rook-ceph-rgw-{store-name}.{namespace}.svc
port:
default: '80'
description: Port for the RGW service, typically 80 for HTTP or 443 for HTTPS as configured in the CephObjectStore gateway spec
security:
- s3Auth: []
tags:
- name: Objects
description: S3-compatible object upload, download, listing, deletion, and metadata operations within Ceph Object Storage buckets
paths:
/{bucket}:
parameters:
- $ref: '#/components/parameters/BucketParam'
get:
operationId: listObjects
summary: List Objects in a Bucket
description: Returns a list of objects stored in the specified S3 bucket. Supports filtering by prefix, delimiter for hierarchical listings, and pagination through continuation tokens. Returns up to 1000 objects per request by default.
tags:
- Objects
parameters:
- name: list-type
in: query
description: Set to 2 to use the newer List Objects V2 API which uses continuation tokens instead of markers for pagination.
schema:
type: integer
enum:
- 2
- name: prefix
in: query
description: Limits the response to keys beginning with the specified prefix. Used to organize objects into virtual directories.
schema:
type: string
- name: delimiter
in: query
description: Character used to group keys. All keys that contain the delimiter between the prefix and the first occurrence of the delimiter are grouped into a single CommonPrefix entry.
schema:
type: string
- name: max-keys
in: query
description: Maximum number of keys to return in a single response. Defaults to 1000, maximum is 1000.
schema:
type: integer
minimum: 1
maximum: 1000
default: 1000
- name: continuation-token
in: query
description: Token from a previous List Objects V2 response used to continue listing from where the previous call left off.
schema:
type: string
- name: marker
in: query
description: Key after which listing should begin, used for pagination in List Objects V1 API.
schema:
type: string
responses:
'200':
description: List of objects in the bucket
content:
application/xml:
schema:
$ref: '#/components/schemas/ListBucketResult'
'404':
description: Bucket not found
content:
application/xml:
schema:
$ref: '#/components/schemas/ErrorResponse'
/{bucket}/{key}:
parameters:
- $ref: '#/components/parameters/BucketParam'
- $ref: '#/components/parameters/KeyParam'
put:
operationId: putObject
summary: Upload an Object
description: Uploads an object to the specified key in the S3 bucket. The object data is included in the request body. Optional request headers allow specifying content type, content encoding, server-side encryption, storage class, and custom metadata prefixed with x-amz-meta-.
tags:
- Objects
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: Object uploaded successfully
'400':
description: Bad request due to invalid parameters or malformed request
content:
application/xml:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Bucket not found
content:
application/xml:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
operationId: getObject
summary: Download an Object
description: Downloads the data and metadata of an object from the specified key in the S3 bucket. Supports range requests for partial content retrieval and conditional requests using ETag or Last-Modified headers. Returns the object data in the response body.
tags:
- Objects
parameters:
- name: Range
in: header
description: HTTP range header for partial content requests, e.g. bytes=0-1023 to retrieve the first 1024 bytes.
schema:
type: string
- name: If-Match
in: header
description: Returns the object only if the ETag matches the specified value, otherwise returns HTTP 412.
schema:
type: string
- name: If-None-Match
in: header
description: Returns the object only if the ETag does not match the specified value, used for cache validation.
schema:
type: string
responses:
'200':
description: Object data retrieved successfully
content:
application/octet-stream:
schema:
type: string
format: binary
'206':
description: Partial content returned for range request
content:
application/octet-stream:
schema:
type: string
format: binary
'304':
description: Not modified, returned for conditional requests
'404':
description: Object or bucket not found
content:
application/xml:
schema:
$ref: '#/components/schemas/ErrorResponse'
head:
operationId: headObject
summary: Get Object Metadata
description: Retrieves the metadata of an object without downloading the object data. Returns HTTP headers containing content type, content length, ETag, last modified date, and any custom metadata associated with the object.
tags:
- Objects
responses:
'200':
description: Object metadata retrieved successfully
'404':
description: Object or bucket not found
delete:
operationId: deleteObject
summary: Delete an Object
description: Deletes the specified object from the S3 bucket. If versioning is enabled, this creates a delete marker rather than permanently removing the object. The operation is idempotent and returns HTTP 204 even if the object does not exist.
tags:
- Objects
responses:
'204':
description: Object deleted successfully
'404':
description: Bucket not found
content:
application/xml:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
Object:
type: object
description: An S3 object stored in a Ceph Object Storage bucket
properties:
Key:
type: string
description: Object key within the bucket
LastModified:
type: string
format: date-time
description: Date and time the object was last modified
ETag:
type: string
description: MD5 hash of the object data enclosed in double quotes, used for data integrity verification
Size:
type: integer
description: Size of the object in bytes
StorageClass:
type: string
description: Storage class of the object
enum:
- STANDARD
- REDUCED_REDUNDANCY
Owner:
type: object
description: Owner of the object
properties:
ID:
type: string
DisplayName:
type: string
ListBucketResult:
type: object
description: Response to a list objects request for a bucket
properties:
Name:
type: string
description: Name of the bucket containing the listed objects
Prefix:
type: string
description: Prefix used to filter the listed objects
Delimiter:
type: string
description: Delimiter used for hierarchical grouping of keys
MaxKeys:
type: integer
description: Maximum number of keys returned in this response
IsTruncated:
type: boolean
description: True if the response was truncated and more objects are available via pagination
NextContinuationToken:
type: string
description: Token for retrieving the next page of results in List Objects V2
Contents:
type: array
description: List of object entries matching the listing criteria
items:
$ref: '#/components/schemas/Object'
CommonPrefixes:
type: array
description: Virtual directory prefixes grouped by the delimiter character
items:
type: object
properties:
Prefix:
type: string
description: Common prefix string for grouped keys
ErrorResponse:
type: object
description: S3-compatible error response returned when an operation fails
properties:
Code:
type: string
description: S3 error code string identifying the type of error, e.g. NoSuchBucket, AccessDenied, InvalidBucketName
Message:
type: string
description: Human-readable description of the error
Resource:
type: string
description: The bucket or object key that caused the error
RequestId:
type: string
description: Unique identifier for the failed request for debugging
parameters:
BucketParam:
name: bucket
in: path
required: true
description: Name of the S3 bucket in the Ceph Object Storage gateway. Must be globally unique within the object store and follow DNS naming conventions.
schema:
type: string
minLength: 3
maxLength: 63
pattern: ^[a-z0-9][a-z0-9\-]*[a-z0-9]$
KeyParam:
name: key
in: path
required: true
description: Object key (path) within the bucket. Can include forward slashes to simulate a directory hierarchy, with a maximum length of 1024 bytes.
schema:
type: string
minLength: 1
maxLength: 1024
securitySchemes:
s3Auth:
type: apiKey
in: header
name: Authorization
description: AWS Signature Version 4 (SigV4) or AWS Signature Version 2 authentication using access key and secret key pairs provisioned by CephObjectStoreUser Kubernetes CRDs. Credentials are available in the Kubernetes Secret created by Rook for each CephObjectStoreUser.
externalDocs:
description: Rook Ceph Object Storage Documentation
url: https://rook.io/docs/rook/latest/CRDs/Object-Storage/ceph-object-store-crd/