openapi: 3.1.0 info: title: Rook Ceph Object Storage 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/ externalDocs: description: Rook Ceph Object Storage Documentation url: https://rook.io/docs/rook/latest/CRDs/Object-Storage/ceph-object-store-crd/ 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 tags: - name: Buckets description: >- S3-compatible bucket creation, listing, deletion, and configuration operations on Ceph Object Storage provisioned by Rook - name: Multipart Uploads description: >- S3-compatible multipart upload operations for large objects, including initiation, part upload, completion, and abort - name: Objects description: >- S3-compatible object upload, download, listing, deletion, and metadata operations within Ceph Object Storage buckets security: - s3Auth: [] paths: /: get: operationId: listBuckets summary: List All Buckets description: >- Returns a list of all S3 buckets owned by the authenticated user in the Ceph Object Storage gateway. The response includes bucket names and creation dates. Credentials are provided via AWS Signature Version 4 or Version 2 authentication using access keys provisioned by CephObjectStoreUser CRDs. tags: - Buckets responses: '200': description: List of buckets owned by the authenticated user content: application/xml: schema: $ref: '#/components/schemas/ListAllMyBucketsResult' '401': description: Authentication credentials are missing or invalid content: application/xml: schema: $ref: '#/components/schemas/ErrorResponse' /{bucket}: parameters: - $ref: '#/components/parameters/BucketParam' put: operationId: createBucket summary: Create a Bucket description: >- Creates a new S3 bucket in the Ceph Object Storage gateway with the specified name. The bucket is created in the object store backing pool configured in the CephObjectStore CRD. Optional location constraint and ACL headers can be specified in the request. tags: - Buckets responses: '200': description: Bucket created successfully '400': description: >- Bad request. The bucket name is invalid or a required parameter is missing. content: application/xml: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Conflict. A bucket with the specified name already exists and is owned by a different account. content: application/xml: schema: $ref: '#/components/schemas/ErrorResponse' head: operationId: headBucket summary: Check Bucket Existence and Access description: >- Checks whether a bucket exists and whether the caller has permission to access it. Returns HTTP 200 if the bucket exists and is accessible, HTTP 403 if the bucket exists but access is denied, or HTTP 404 if the bucket does not exist. tags: - Buckets responses: '200': description: Bucket exists and is accessible '403': description: Bucket exists but access is denied '404': description: Bucket does not exist delete: operationId: deleteBucket summary: Delete a Bucket description: >- Deletes an empty S3 bucket from the Ceph Object Storage gateway. The bucket must be empty before it can be deleted. Returns HTTP 409 if the bucket is not empty. tags: - Buckets responses: '204': description: Bucket deleted successfully '404': description: Bucket not found content: application/xml: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Bucket is not empty and cannot be deleted content: application/xml: schema: $ref: '#/components/schemas/ErrorResponse' 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' /{bucket}?uploads: parameters: - $ref: '#/components/parameters/BucketParam' get: operationId: listMultipartUploads summary: List In-Progress Multipart Uploads description: >- Returns a list of in-progress multipart uploads for the specified bucket. Useful for identifying and cleaning up incomplete multipart uploads that may be consuming storage quota. tags: - Multipart Uploads parameters: - name: uploads in: query required: true schema: type: string enum: [''] responses: '200': description: List of in-progress multipart uploads content: application/xml: schema: $ref: '#/components/schemas/ListMultipartUploadsResult' '404': description: Bucket not found content: application/xml: schema: $ref: '#/components/schemas/ErrorResponse' /{bucket}/{key}?uploads: parameters: - $ref: '#/components/parameters/BucketParam' - $ref: '#/components/parameters/KeyParam' post: operationId: createMultipartUpload summary: Initiate a Multipart Upload description: >- Initiates a multipart upload for a large object and returns an upload ID that must be used in subsequent part upload and complete requests. Parts can then be uploaded in parallel using the upload ID. The multipart upload is not visible in the bucket until it is completed with a CompleteMultipartUpload request. tags: - Multipart Uploads parameters: - name: uploads in: query required: true schema: type: string enum: [''] responses: '200': description: Multipart upload initiated with upload ID returned content: application/xml: schema: $ref: '#/components/schemas/InitiateMultipartUploadResult' '404': description: Bucket not found content: application/xml: schema: $ref: '#/components/schemas/ErrorResponse' components: 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. 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 schemas: ListAllMyBucketsResult: type: object description: >- Response to a list buckets request containing all buckets owned by the authenticated user properties: Owner: type: object description: Identity of the bucket owner properties: ID: type: string description: Ceph user ID of the bucket owner DisplayName: type: string description: Display name of the bucket owner Buckets: type: object description: Container for the list of bucket entries properties: Bucket: type: array description: List of bucket entries items: $ref: '#/components/schemas/Bucket' Bucket: type: object description: An S3 bucket in the Ceph Object Storage gateway properties: Name: type: string description: Name of the bucket CreationDate: type: string format: date-time description: Date and time the bucket was created in ISO 8601 format 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 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 ListMultipartUploadsResult: type: object description: Response listing in-progress multipart uploads for a bucket properties: Bucket: type: string description: Name of the bucket Upload: type: array description: List of in-progress multipart upload entries items: type: object properties: Key: type: string description: Object key for the multipart upload UploadId: type: string description: Unique identifier for the multipart upload Initiated: type: string format: date-time description: Date and time the multipart upload was initiated Initiator: type: object properties: ID: type: string DisplayName: type: string InitiateMultipartUploadResult: type: object description: >- Response to a multipart upload initiation request containing the upload ID needed for subsequent part uploads properties: Bucket: type: string description: Name of the bucket where the object will be stored Key: type: string description: Object key for the multipart upload UploadId: type: string description: >- Unique identifier for this multipart upload, required in all subsequent part upload and complete/abort requests 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