openapi.yaml

openapi: 3.0.0
info:
  title: HyperFleet API
  version: 1.0.9
  contact:
    name: HyperFleet Team
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: |-
    HyperFleet API provides simple CRUD operations for managing cluster resources and their status history.

    **Architecture**: Simple CRUD only, no business logic, no event creation.
    Sentinel operator handles all orchestration logic.
    Adapters handle the specifics of managing spec
tags: []
paths:
  /api/hyperfleet/v1/clusters:
    get:
      operationId: getClusters
      summary: List clusters
      parameters:
        - $ref: '#/components/parameters/SearchParams'
        - $ref: '#/components/parameters/QueryParams.page'
        - $ref: '#/components/parameters/QueryParams.pageSize'
        - $ref: '#/components/parameters/QueryParams.orderBy'
        - $ref: '#/components/parameters/QueryParams.order'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterList'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
    post:
      operationId: postCluster
      summary: Create cluster
      description: |-
        Create a new cluster resource.

        **Note**: The `status` object in the response is read-only and computed by the service.
        It is NOT part of the request body. Initially,
        status.conditions will include mandatory "Available", "Ready" and "Reconciled" conditions.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterCreateRequest'
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/clusters/{cluster_id}:
    get:
      operationId: getClusterById
      summary: Get cluster by ID
      parameters:
        - $ref: '#/components/parameters/SearchParams'
        - name: cluster_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
    patch:
      operationId: patchClusterById
      summary: Patch cluster by ID
      description: Patch a specific cluster by ID
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterPatchRequest'
      security:
        - BearerAuth: []
    delete:
      operationId: deleteClusterById
      summary: Request cluster deletion
      description: |-
        Marks the cluster for deletion by setting deleted_time to the current time, cascades to its nodepools.
        The cluster remains in the database until it is fully deleted.
        Returns the updated cluster with generation incremented.
      parameters:
        - name: cluster_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: The request has been accepted for processing, but processing has not yet completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
              example:
                kind: Cluster
                id: 019466a0-8f8e-7abc-9def-0123456789ab
                href: https://api.hyperfleet.com/v1/clusters/019466a0-8f8e-7abc-9def-0123456789ab
                name: cluster-123
                labels:
                  environment: production
                  team: platform
                spec: {}
                generation: 2
                status:
                  conditions:
                    - type: Ready
                      status: 'True'
                      reason: All adapters reported Ready True for the current generation
                      message: All adapters reported Ready True for the current generation
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Reconciled
                      status: 'True'
                      reason: All required adapters reported Available=True or Finalized=True at the current generation
                      message: All required adapters reported Available=True or Finalized=True at the current generation
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Available
                      status: 'True'
                      reason: All adapters reported Available True for the same generation
                      message: All adapters reported Available True for the same generation
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Adapter1Successful
                      status: 'True'
                      reason: This adapter1 is available
                      message: This adapter1 is available
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Adapter2Successful
                      status: 'True'
                      reason: This adapter2 is available
                      message: This adapter2 is available
                      observed_generation: 2
                      created_time: '2021-01-01T10:01:00Z'
                      last_updated_time: '2021-01-01T10:01:00Z'
                      last_transition_time: '2021-01-01T10:01:00Z'
                created_time: '2021-01-01T00:00:00Z'
                updated_time: '2021-01-01T10:02:00Z'
                deleted_time: '2021-01-01T10:05:00Z'
                created_by: user-123@example.com
                updated_by: user-123@example.com
                deleted_by: user-123@example.com
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/clusters/{cluster_id}/nodepools:
    get:
      operationId: getNodePoolsByClusterId
      summary: List all nodepools for cluster
      description: Returns the list of all nodepools for a cluster
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - $ref: '#/components/parameters/SearchParams'
        - $ref: '#/components/parameters/QueryParams.page'
        - $ref: '#/components/parameters/QueryParams.pageSize'
        - $ref: '#/components/parameters/QueryParams.orderBy'
        - $ref: '#/components/parameters/QueryParams.order'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodePoolList'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
    post:
      operationId: createNodePool
      summary: Create nodepool
      description: Create a NodePool for a cluster
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodePoolCreateResponse'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodePoolCreateRequest'
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}:
    get:
      operationId: getNodePoolById
      summary: Get nodepool by ID
      description: Returns specific nodepool
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - name: nodepool_id
          in: path
          required: true
          description: NodePool ID
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodePool'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
    delete:
      operationId: deleteNodePoolById
      summary: Request nodepool deletion
      description: |-
        Marks the nodepool for deletion by setting deleted_time and deleted_by. Does not affect the parent cluster.
        Returns the updated nodepool with generation incremented.
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - name: nodepool_id
          in: path
          required: true
          description: NodePool ID
          schema:
            type: string
      responses:
        '202':
          description: The request has been accepted for processing, but processing has not yet completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodePool'
              example:
                kind: NodePool
                id: 019466a1-2b3c-7def-8abc-456789abcdef
                href: https://api.hyperfleet.com/v1/nodepools/019466a1-2b3c-7def-8abc-456789abcdef
                name: worker-pool-1
                labels:
                  environment: production
                  pooltype: worker
                spec: {}
                generation: 2
                owner_references:
                  id: 019466a0-8f8e-7abc-9def-0123456789ab
                  kind: Cluster
                  href: https://api.hyperfleet.com/v1/clusters/019466a0-8f8e-7abc-9def-0123456789ab
                status:
                  conditions:
                    - type: Ready
                      status: 'True'
                      reason: All adapters reported Ready True for the current generation
                      message: All adapters reported Ready True for the current generation
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Reconciled
                      status: 'True'
                      reason: All required adapters reported Available=True or Finalized=True at the current generation
                      message: All required adapters reported Available=True or Finalized=True at the current generation
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Available
                      status: 'True'
                      reason: All adapters reported Available True for the same generation
                      message: All adapters reported Available True for the same generation
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Adapter1Successful
                      status: 'True'
                      reason: This adapter1 is available
                      message: This adapter1 is available
                      observed_generation: 2
                      created_time: '2021-01-01T10:00:00Z'
                      last_updated_time: '2021-01-01T10:00:00Z'
                      last_transition_time: '2021-01-01T10:00:00Z'
                    - type: Adapter2Successful
                      status: 'True'
                      reason: This adapter2 is available
                      message: This adapter2 is available
                      observed_generation: 2
                      created_time: '2021-01-01T10:01:00Z'
                      last_updated_time: '2021-01-01T10:01:00Z'
                      last_transition_time: '2021-01-01T10:01:00Z'
                created_time: '2021-01-01T00:00:00Z'
                updated_time: '2021-01-01T10:02:00Z'
                deleted_time: '2021-01-01T10:05:00Z'
                created_by: user-123@example.com
                updated_by: user-123@example.com
                deleted_by: user-123@example.com
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
    patch:
      operationId: patchNodePoolById
      summary: Patch nodepool by ID
      description: Patch a specific nodepool within a cluster
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - name: nodepool_id
          in: path
          required: true
          description: NodePool ID
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodePool'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodePoolPatchRequest'
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses:
    post:
      operationId: postNodePoolStatuses
      summary: Create or update adapter status
      description: |-
        Adapter creates or updates its status report for this nodepool.
        If adapter already has a status, it will be updated (upsert by adapter name).

        Response includes the full adapter status with all conditions.
        Adapter should call this endpoint every time it evaluates the nodepool.
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - name: nodepool_id
          in: path
          required: true
          description: Nodepool ID
          schema:
            type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdapterStatus'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        '409':
          description: The request conflicts with the current state of the server.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdapterStatusCreateRequest'
      security:
        - BearerAuth: []
    put:
      operationId: putNodePoolStatuses
      summary: Adapter creates or updates resource nodepool status
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - name: nodepool_id
          in: path
          required: true
          description: Nodepool ID
          schema:
            type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdapterStatus'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        '409':
          description: The request conflicts with the current state of the server.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdapterStatusCreateRequest'
      security:
        - BearerAuth: []
    get:
      operationId: getNodePoolsStatuses
      summary: List all adapter statuses for nodepools
      description: Returns adapter status reports for this nodepool
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - name: nodepool_id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/SearchParams'
        - $ref: '#/components/parameters/QueryParams.page'
        - $ref: '#/components/parameters/QueryParams.pageSize'
        - $ref: '#/components/parameters/QueryParams.orderBy'
        - $ref: '#/components/parameters/QueryParams.order'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdapterStatusList'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/hyperfleet/v1/clusters/{cluster_id}/statuses:
    post:
      operationId: postClusterStatuses
      summary: Create or update adapter status
      description: |-
        Adapter creates or updates its status report for this cluster.
        If adapter already has a status, it will be updated (upsert by adapter name).

        Response includes the full adapter status with all conditions.
        Adapter should call this endpoint every time it evaluates the cluster.
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdapterStatus'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        '409':
          description: The request conflicts with the current state of the server.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdapterStatusCreateRequest'
      security:
        - BearerAuth: []
    put:
      operationId: putClusterStatuses
      summary: Adapter creates or updates resource cluster status
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdapterStatus'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
        '409':
          description: The request conflicts with the current state of the server.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdapterStatusCreateRequest'
      security:
        - BearerAuth: []
    get:
      operationId: getClusterStatuses
      summary: List all adapter statuses for cluster
      description: Returns adapter status reports for this cluster
      parameters:
        - name: cluster_id
          in: path
          required: true
          description: Cluster ID
          schema:
            type: string
        - $ref: '#/components/parameters/SearchParams'
        - $ref: '#/components/parameters/QueryParams.page'
        - $ref: '#/components/parameters/QueryParams.pageSize'
        - $ref: '#/components/parameters/QueryParams.orderBy'
        - $ref: '#/components/parameters/QueryParams.order'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdapterStatusList'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '404':
          description: The server cannot find the requested resource.
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/nodepools:
    get:
      operationId: getNodePools
      summary: List all nodepools for cluster
      description: Returns the list of all nodepools
      parameters:
        - $ref: '#/components/parameters/SearchParams'
        - $ref: '#/components/parameters/QueryParams.page'
        - $ref: '#/components/parameters/QueryParams.pageSize'
        - $ref: '#/components/parameters/QueryParams.orderBy'
        - $ref: '#/components/parameters/QueryParams.order'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodePoolList'
        '400':
          description: The server could not understand the request due to invalid syntax.
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
components:
  parameters:
    QueryParams.order:
      name: order
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/OrderDirection'
      explode: false
    QueryParams.orderBy:
      name: orderBy
      in: query
      required: false
      schema:
        type: string
        default: created_time
      explode: false
    QueryParams.page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 1
      explode: false
    QueryParams.pageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 20
      explode: false
    SearchParams:
      name: search
      in: query
      required: false
      description: |-
        Filter results using TSL (Tree Search Language) query syntax.
        Examples: `status.conditions.Ready='True'`, `name in ('c1','c2')`, `labels.region='us-east'`
      schema:
        type: string
      explode: false
  schemas:
    AdapterCondition:
      type: object
      required:
        - type
        - last_transition_time
        - status
      properties:
        type:
          type: string
          description: Condition type
        reason:
          type: string
          description: Machine-readable reason code
        message:
          type: string
          description: Human-readable message
        last_transition_time:
          type: string
          format: date-time
          description: |-
            When this condition last transitioned status (API-managed)
            Only updated when status changes (True/False), not when reason/message changes
        status:
          $ref: '#/components/schemas/AdapterConditionStatus'
      description: |-
        Condition in AdapterStatus
        Used for standard Kubernetes condition types: "Available", "Applied", "Health", "Finalized"
        Note: observed_generation is at AdapterStatus level, not per-condition,
        since all conditions in one AdapterStatus share the same observed generation
    AdapterConditionStatus:
      type: string
      enum:
        - 'True'
        - 'False'
        - Unknown
      description: Status value for adapter conditions
    AdapterStatus:
      type: object
      required:
        - adapter
        - observed_generation
        - conditions
        - created_time
        - last_report_time
      properties:
        adapter:
          type: string
          description: Adapter name (e.g., "validator", "dns", "provisioner")
        observed_generation:
          type: integer
          format: int32
          description: Which generation of the resource this status reflects
        metadata:
          type: object
          properties:
            job_name:
              type: string
            job_namespace:
              type: string
            attempt:
              type: integer
              format: int32
            started_time:
              type: string
              format: date-time
            completed_time:
              type: string
              format: date-time
            duration:
              type: string
          description: Job execution metadata
        data:
          type: object
          additionalProperties: {}
          description: Adapter-specific data (structure varies by adapter type)
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AdapterCondition'
          description: |-
            Kubernetes-style conditions tracking adapter state
            Typically includes: Available, Applied, Health, Finalized
        created_time:
          type: string
          format: date-time
          description: When this adapter status was first created (API-managed)
        last_report_time:
          type: string
          format: date-time
          description: |-
            When this adapter last reported its status (API-managed)
            Updated every time the adapter POSTs, even if conditions haven't changed
            Used by Sentinel to detect adapter liveness
      description: |-
        AdapterStatus represents the complete status report from an adapter
        Contains multiple conditions, job metadata, and adapter-specific data
      example:
        adapter: adapter1
        observed_generation: 1
        conditions:
          - type: Available
            status: 'True'
            reason: This adapter1 is available
            message: This adapter1 is available
            last_transition_time: '2021-01-01T10:00:00Z'
          - type: Applied
            status: 'True'
            reason: Validation job applied
            message: Adapter1 validation job applied successfully
            last_transition_time: '2021-01-01T10:00:00Z'
          - type: Health
            status: 'True'
            reason: All adapter1 operations completed successfully
            message: All adapter1 runtime operations completed successfully
            last_transition_time: '2021-01-01T10:00:00Z'
          - type: Finalized
            status: 'True'
            reason: All resources deleted; cleanup confirmed
            message: All resources deleted; cleanup confirmed
            last_transition_time: '2021-01-01T10:00:00Z'
        metadata:
          job_name: validator-job-abc123
          job_namespace: hyperfleet-system
          attempt: 1
          started_time: '2021-01-01T10:00:00Z'
          completed_time: '2021-01-01T10:02:00Z'
          duration: 2m
        data:
          validation_results:
            total_tests: 30
            passed: 30
            failed: 0
        created_time: '2021-01-01T10:00:00Z'
        last_report_time: '2021-01-01T10:02:00Z'
    AdapterStatusCreateRequest:
      type: object
      required:
        - adapter
        - observed_generation
        - observed_time
        - conditions
      properties:
        adapter:
          type: string
          description: Adapter name (e.g., "validator", "dns", "provisioner")
        observed_generation:
          type: integer
          format: int32
          description: Which generation of the resource this status reflects
        metadata:
          type: object
          properties:
            job_name:
              type: string
            job_namespace:
              type: string
            attempt:
              type: integer
              format: int32
            started_time:
              type: string
              format: date-time
            completed_time:
              type: string
              format: date-time
            duration:
              type: string
          description: Job execution metadata
        data:
          type: object
          additionalProperties: {}
          description: Adapter-specific data (structure varies by adapter type)
        observed_time:
          type: string
          format: date-time
          description: |-
            When the adapter observed this resource state
            API will use this to set AdapterStatus.last_report_time
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ConditionRequest'
      description: Request payload for creating/updating adapter status
      example:
        adapter: validator
        observed_generation: 1
        observed_time: '2021-01-01T10:00:00Z'
        conditions:
          - type: Available
            status: 'True'
            reason: This adapter1 is available
            message: This adapter1 is available
          - type: Applied
            status: 'True'
            reason: Validation job applied
            message: Adapter1 validation job applied successfully
          - type: Health
            status: 'True'
            reason: All adapter1 operations completed successfully
            message: All adapter1 runtime operations completed successfully
          - type: Finalized
            status: 'True'
            reason: All resources deleted; cleanup confirmed
            message: All resources deleted; cleanup confirmed
        metadata:
          job_name: validator-job-abc123
          job_namespace: hyperfleet-system
          attempt: 1
          started_time: '2021-01-01T10:00:00Z'
          completed_time: '2021-01-01T10:02:00Z'
          duration: 2m
        data:
          validation_results:
            total_tests: 30
            passed: 30
            failed: 0
    AdapterStatusList:
      type: object
      required:
        - kind
        - page
        - size
        - total
        - items
      properties:
        kind:
          type: string
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/AdapterStatus'
      description: List of adapter statuses with pagination metadata
      example:
        kind: AdapterStatusList
        page: 1
        size: 2
        total: 2
        items:
          - adapter: adapter1
            observed_generation: 1
            conditions:
              - type: Available
                status: 'True'
                reason: This adapter1 is available
                message: This adapter1 is available
                last_transition_time: '2021-01-01T10:00:00Z'
            metadata:
              job_name: validator-job-abc123
              duration: 2m
            created_time: '2021-01-01T10:00:00Z'
            last_report_time: '2021-01-01T10:02:00Z'
          - adapter: adapter2
            observed_generation: 1
            conditions:
              - type: Available
                status: 'True'
                reason: This adapter2 is available
                message: This adapter2 is available
                last_transition_time: '2021-01-01T10:01:00Z'
            created_time: '2021-01-01T10:01:00Z'
            last_report_time: '2021-01-01T10:01:30Z'
    BearerAuth:
      type: object
      required:
        - type
        - scheme
      properties:
        type:
          type: string
          enum:
            - http
        scheme:
          type: string
          enum:
            - bearer
    Cluster:
      type: object
      required:
        - name
        - spec
        - created_time
        - updated_time
        - created_by
        - updated_by
        - generation
        - status
      properties:
        id:
          type: string
          description: Resource identifier
        kind:
          type: string
          description: Resource kind
        href:
          type: string
          description: Resource URI
        labels:
          type: object
          additionalProperties:
            type: string
          description: labels for the API resource as pairs of name:value strings
        name:
          type: string
          minLength: 3
          maxLength: 53
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
          description: Cluster name (unique)
        spec:
          $ref: '#/components/schemas/ClusterSpec'
        created_time:
          type: string
          format: date-time
          description: Timestamp when the resource was created
        updated_time:
          type: string
          format: date-time
          description: Timestamp when the resource was last updated
        created_by:
          type: string
          format: email
          description: Identity that created the resource
        updated_by:
          type: string
          format: email
          description: Identity that last updated the resource
        deleted_time:
          type: string
          format: date-time
          description: Timestamp when deletion was requested; omitted if not marked for deletion
        deleted_by:
          type: string
          format: email
          description: Identity that requested deletion; omitted if not marked for deletion
        generation:
          type: integer
          format: int32
          minimum: 1
          description: Generation field is updated on customer updates, reflecting the version of the "intent" of the customer
        status:
          $ref: '#/components/schemas/ClusterStatus'
      example:
        kind: Cluster
        id: 019466a0-8f8e-7abc-9def-0123456789ab
        href: https://api.hyperfleet.com/v1/clusters/019466a0-8f8e-7abc-9def-0123456789ab
        name: cluster-123
        labels:
          environment: production
          team: platform
        spec: {}
        generation: 1
        status:
          conditions:
            - type: Ready
              status: 'True'
              reason: All adapters reported Ready True for the current generation
              message: All adapters reported Ready True for the current generation
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Reconciled
              status: 'True'
              reason: All required adapters reported Available=True or Finalized=True at the current generation
              message: All required adapters reported Available=True or Finalized=True at the current generation
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Available
              status: 'True'
              reason: All adapters reported Available True for the same generation
              message: All adapters reported Available True for the same generation
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Adapter1Successful
              status: 'True'
              reason: This adapter1 is available
              message: This adapter1 is available
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Adapter2Successful
              status: 'True'
              reason: This adapter2 is available
              message: This adapter2 is available
              observed_generation: 1
              created_time: '2021-01-01T10:01:00Z'
              last_updated_time: '2021-01-01T10:01:00Z'
              last_transition_time: '2021-01-01T10:01:00Z'
        created_time: '2021-01-01T00:00:00Z'
        updated_time: '2021-01-01T10:02:00Z'
        created_by: user-123@example.com
        updated_by: user-123@example.com
    ClusterCreateRequest:
      type: object
      required:
        - name
        - spec
      properties:
        id:
          type: string
          description: Resource identifier
        kind:
          type: string
          description: Resource kind
        href:
          type: string
          description: Resource URI
        labels:
          type: object
          additionalProperties:
            type: string
          description: labels for the API resource as pairs of name:value strings
        name:
          type: string
          minLength: 3
          maxLength: 53
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
          description: Cluster name (unique)
        spec:
          $ref: '#/components/schemas/ClusterSpec'
      example:
        kind: Cluster
        name: cluster-123
        labels:
          environment: production
          team: platform
        spec: {}
    ClusterList:
      type: object
      required:
        - kind
        - page
        - size
        - total
        - items
      properties:
        kind:
          type: string
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Cluster'
    ClusterPatchRequest:
      type: object
      properties:
        spec:
          $ref: '#/components/schemas/ClusterSpec'
        labels:
          type: object
          additionalProperties:
            type: string
      example:
        spec: {}
        labels:
          env: staging
      additionalProperties: false
      minProperties: 1
    ClusterSpec:
      type: object
      description: |-
        Core cluster specification.
        Accepts any properties as the spec is provider-agnostic.
        This is represented as a simple object to allow flexibility.
    ClusterStatus:
      type: object
      required:
        - conditions
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ResourceCondition'
          minItems: 2
          description: |-
            List of status conditions for the cluster.

            **Mandatory conditions**: 
            - `type: "Ready"` *(deprecated — use Reconciled)*: Whether all adapters report successfully at the current generation.
            - `type: "Reconciled"`: Whether the resource's desired state has been fully reconciled by all adapters at the current generation.
            - `type: "Available"`: Aggregated adapter result for a common observed_generation.   

            These conditions are present immediately upon resource creation.
      description: |-
        Cluster status computed from all status conditions.

        This object is computed by the service and CANNOT be modified directly.
        It is aggregated from condition updates posted to `/clusters/{id}/statuses`.

        Provides quick overview of all reported conditions.
    ConditionRequest:
      type: object
      required:
        - type
        - status
      properties:
        type:
          type: string
        status:
          $ref: '#/components/schemas/AdapterConditionStatus'
        reason:
          type: string
        message:
          type: string
      description: |-
        Condition data for create/update requests (from adapters)
        observed_generation and observed_time are now at AdapterStatusCreateRequest level
    Error:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: URI reference identifying the problem type
          example: https://api.hyperfleet.io/errors/validation-error
        title:
          type: string
          description: Short human-readable summary of the problem
          example: Validation Failed
        status:
          type: integer
          description: HTTP status code
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
          example: The cluster name field is required
        instance:
          type: string
          format: uri
          description: URI reference for this specific occurrence
          example: /api/hyperfleet/v1/clusters
        code:
          type: string
          description: Machine-readable error code in HYPERFLEET-CAT-NUM format
          example: HYPERFLEET-VAL-001
        timestamp:
          type: string
          format: date-time
          description: RFC3339 timestamp of when the error occurred
          example: '2024-01-15T10:30:00Z'
        trace_id:
          type: string
          description: Distributed trace ID for correlation
          example: abc123def456
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Field-level validation errors (for validation failures)
      description: RFC 9457 Problem Details error format with HyperFleet extensions
    NodePool:
      type: object
      required:
        - name
        - spec
        - created_time
        - updated_time
        - created_by
        - updated_by
        - generation
        - owner_references
        - status
      properties:
        id:
          type: string
          description: Resource identifier
        kind:
          type: string
          description: Resource kind
        href:
          type: string
          description: Resource URI
        labels:
          type: object
          additionalProperties:
            type: string
          description: labels for the API resource as pairs of name:value strings
        name:
          type: string
          minLength: 3
          maxLength: 15
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
          description: NodePool name (unique in a cluster)
        spec:
          $ref: '#/components/schemas/NodePoolSpec'
        created_time:
          type: string
          format: date-time
          description: Timestamp when the resource was created
        updated_time:
          type: string
          format: date-time
          description: Timestamp when the resource was last updated
        created_by:
          type: string
          format: email
          description: Identity that created the resource
        updated_by:
          type: string
          format: email
          description: Identity that last updated the resource
        deleted_time:
          type: string
          format: date-time
          description: Timestamp when deletion was requested; omitted if not marked for deletion
        deleted_by:
          type: string
          format: email
          description: Identity that requested deletion; omitted if not marked for deletion
        generation:
          type: integer
          format: int32
          minimum: 1
          description: Generation field is updated on customer updates, reflecting the version of the "intent" of the customer
        owner_references:
          $ref: '#/components/schemas/ObjectReference'
        status:
          $ref: '#/components/schemas/NodePoolStatus'
      example:
        kind: NodePool
        id: 019466a1-2b3c-7def-8abc-456789abcdef
        href: https://api.hyperfleet.com/v1/nodepools/019466a1-2b3c-7def-8abc-456789abcdef
        name: worker-pool-1
        labels:
          environment: production
          pooltype: worker
        spec: {}
        generation: 1
        owner_references:
          id: 019466a0-8f8e-7abc-9def-0123456789ab
          kind: Cluster
          href: https://api.hyperfleet.com/v1/clusters/019466a0-8f8e-7abc-9def-0123456789ab
        status:
          conditions:
            - type: Ready
              status: 'True'
              reason: All adapters reported Ready True for the current generation
              message: All adapters reported Ready True for the current generation
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Reconciled
              status: 'True'
              reason: All required adapters reported Available=True or Finalized=True at the current generation
              message: All required adapters reported Available=True or Finalized=True at the current generation
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Available
              status: 'True'
              reason: All adapters reported Available True for the same generation
              message: All adapters reported Available True for the same generation
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Adapter1Successful
              status: 'True'
              reason: This adapter1 is available
              message: This adapter1 is available
              observed_generation: 1
              created_time: '2021-01-01T10:00:00Z'
              last_updated_time: '2021-01-01T10:00:00Z'
              last_transition_time: '2021-01-01T10:00:00Z'
            - type: Adapter2Successful
              status: 'True'
              reason: This adapter2 is available
              message: This adapter2 is available
              observed_generation: 1
              created_time: '2021-01-01T10:01:00Z'
              last_updated_time: '2021-01-01T10:01:00Z'
              last_transition_time: '2021-01-01T10:01:00Z'
        created_time: '2021-01-01T00:00:00Z'
        updated_time: '2021-01-01T10:02:00Z'
        created_by: user-123@example.com
        updated_by: user-123@example.com
    NodePoolCreateRequest:
      type: object
      required:
        - name
        - spec
      properties:
        id:
          type: string
          description: Resource identifier
        kind:
          type: string
          description: Resource kind
        href:
          type: string
          description: Resource URI
        labels:
          type: object
          additionalProperties:
            type: string
          description: labels for the API resource as pairs of name:value strings
        name:
          type: string
          minLength: 3
          maxLength: 15
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
          description: NodePool name (unique in a cluster)
        spec:
          $ref: '#/components/schemas/NodePoolSpec'
      example:
        name: worker-pool-1
        labels:
          environment: production
          pooltype: worker
        spec: {}
    NodePoolCreateResponse:
      type: object
      required:
        - name
        - spec
        - created_time
        - updated_time
        - created_by
        - updated_by
        - generation
        - owner_references
        - status
      properties:
        id:
          type: string
          description: Resource identifier
        kind:
          type: string
          description: Resource kind
        href:
          type: string
          description: Resource URI
        labels:
          type: object
          additionalProperties:
            type: string
          description: labels for the API resource as pairs of name:value strings
        name:
          type: string
          minLength: 3
          maxLength: 15
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
          description: NodePool name (unique in a cluster)
        spec:
          $ref: '#/components/schemas/NodePoolSpec'
        created_time:
          type: string
          format: date-time
          description: Timestamp when the resource was created
        updated_time:
          type: string
          format: date-time
          description: Timestamp when the resource was last updated
        created_by:
          type: string
          format: email
          description: Identity that created the resource
        updated_by:
          type: string
          format: email
          description: Identity that last updated the resource
        deleted_time:
          type: string
          format: date-time
          description: Timestamp when deletion was requested; omitted if not marked for deletion
        deleted_by:
          type: string
          format: email
          description: Identity that requested deletion; omitted if not marked for deletion
        generation:
          type: integer
          format: int32
          minimum: 1
          description: Generation field is updated on customer updates, reflecting the version of the "intent" of the customer
        owner_references:
          $ref: '#/components/schemas/ObjectReference'
        status:
          $ref: '#/components/schemas/NodePoolStatus'
    NodePoolList:
      type: object
      required:
        - kind
        - page
        - size
        - total
        - items
      properties:
        kind:
          type: string
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/NodePool'
    NodePoolPatchRequest:
      type: object
      properties:
        spec:
          $ref: '#/components/schemas/NodePoolSpec'
        labels:
          type: object
          additionalProperties:
            type: string
      example:
        spec: {}
        labels:
          env: staging
      additionalProperties: false
      minProperties: 1
    NodePoolSpec:
      type: object
      description: |-
        Core nodepool specification.
        Accepts any properties as the spec is provider-agnostic.
        This is represented as a simple object to allow flexibility.
    NodePoolStatus:
      type: object
      required:
        - conditions
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ResourceCondition'
          minItems: 2
          description: |-
            List of status conditions for the nodepool.

            **Mandatory conditions**: 
            - `type: "Ready"` *(deprecated — use Reconciled)*: Whether all adapters report successfully at the current generation.
            - `type: "Reconciled"`: Whether the resource's desired state has been fully reconciled by all adapters at the current generation.
            - `type: "Available"`: Aggregated adapter result for a common observed_generation.   

            These conditions are present immediately upon resource creation.
      description: |-
        NodePool status computed from all status conditions.

        This object is computed by the service and CANNOT be modified directly.
    ObjectReference:
      type: object
      properties:
        id:
          type: string
          description: Resource identifier
        kind:
          type: string
          description: Resource kind
        href:
          type: string
          description: Resource URI
    OrderDirection:
      type: string
      enum:
        - asc
        - desc
    ResourceCondition:
      type: object
      required:
        - type
        - last_transition_time
        - status
        - observed_generation
        - created_time
        - last_updated_time
      properties:
        type:
          type: string
          description: Condition type
        reason:
          type: string
          description: Machine-readable reason code
        message:
          type: string
          description: Human-readable message
        last_transition_time:
          type: string
          format: date-time
          description: |-
            When this condition last transitioned status (API-managed)
            Only updated when status changes (True/False), not when reason/message changes
        status:
          $ref: '#/components/schemas/ResourceConditionStatus'
        observed_generation:
          type: integer
          format: int32
          description: Generation of the spec that this condition reflects
        created_time:
          type: string
          format: date-time
          description: When this condition was first created (API-managed)
        last_updated_time:
          type: string
          format: date-time
          description: |-
            When the corresponding adapter last reported (API-managed)
            Updated every time the adapter POSTs, even if condition status hasn't changed
            Copied from AdapterStatus.last_report_time
      description: |-
        Condition in Cluster/NodePool status
        Used for semantic condition types: "ValidationSuccessful", "DNSSuccessful", "NodePoolSuccessful", etc.
        Includes observed_generation and last_updated_time to track adapter-specific state
    ResourceConditionStatus:
      type: string
      enum:
        - 'True'
        - 'False'
      description: Status value for resource conditions
    ValidationError:
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: JSON path to the field that failed validation
          example: spec.name
        value:
          description: The invalid value that was provided (if safe to include)
        constraint:
          type: string
          enum:
            - required
            - min
            - max
            - min_length
            - max_length
            - pattern
            - enum
            - format
            - unique
          description: The validation constraint that was violated
          example: required
        message:
          type: string
          description: Human-readable error message for this field
          example: Cluster name is required
      description: Field-level validation error detail
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
servers:
  - url: https://hyperfleet.redhat.com
    description: Production
    variables: {}