Rook Buckets API

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/