openapi: 3.1.0 info: title: Rook Ceph Object Storage Buckets 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: Buckets description: S3-compatible bucket creation, listing, deletion, and configuration operations on Ceph Object Storage provisioned by Rook 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' components: 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]$ schemas: 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 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' 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 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/