openapi.yaml

openapi: 3.0.0
info:
  title: HyperFleet API
  version: 1.0.24
  contact:
    name: HyperFleet Team
    url: https://github.com/openshift-hyperfleet
  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:
  - name: Clusters
  - name: NodePools
  - name: Channels
  - name: Versions
  - name: WifConfigs
paths:
  /api/hyperfleet/v1/channels:
    get:
      operationId: getChannels
      summary: List channels
      description: Returns a paginated list of channels, optionally filtered by labels or TSL query.
      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/ChannelList'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Channels
      security:
        - BearerAuth: []
    post:
      operationId: postChannel
      summary: Create channel
      description: Creates a new channel.
      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/Channel'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Channels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelCreateRequest'
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/channels/{channel_id}:
    get:
      operationId: getChannelById
      summary: Get channel by ID
      description: Returns a single channel by its ID.
      parameters:
        - $ref: '#/components/parameters/SearchParams'
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Channels
      security:
        - BearerAuth: []
    patch:
      operationId: patchChannelById
      summary: Patch channel by ID
      description: Patches a channel by ID. Supports partial updates to spec and labels.
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Channels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelPatchRequest'
      security:
        - BearerAuth: []
    delete:
      operationId: deleteChannelById
      summary: Request channel deletion
      description: Marks the channel for deletion. Returns 409 if versions still exist (RESTRICT policy).
      parameters:
        - name: channel_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/Channel'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Channels
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/channels/{channel_id}/versions:
    get:
      operationId: getVersionsByChannelId
      summary: List versions for channel
      description: Returns a paginated list of versions for a channel.
      parameters:
        - name: channel_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/VersionList'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Versions
      security:
        - BearerAuth: []
    post:
      operationId: postVersion
      summary: Create version
      description: Creates a new version under a channel.
      parameters:
        - name: channel_id
          in: path
          required: true
          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/Version'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Versions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionCreateRequest'
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/channels/{channel_id}/versions/{version_id}:
    get:
      operationId: getVersionById
      summary: Get version by ID
      description: Returns a single version by its ID within a channel.
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Versions
      security:
        - BearerAuth: []
    patch:
      operationId: patchVersionById
      summary: Patch version by ID
      description: Patch a version by ID. Supports partial updates to spec and labels.
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Versions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionPatchRequest'
      security:
        - BearerAuth: []
    delete:
      operationId: deleteVersionById
      summary: Request version deletion
      description: Marks a version for deletion.
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
        - name: version_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/Version'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Versions
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/clusters:
    get:
      operationId: getClusters
      summary: List clusters
      description: Returns a list of all 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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Clusters
      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 "LastKnownReconciled" 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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Clusters
      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
      description: Returns a single cluster by its 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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Clusters
      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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Clusters
      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:
                  platform:
                    type: template
                    template:
                      projectID: project-123
                      region: us-central1
                      zone: us-central1-a
                      network: network-123
                      subnet: subnet-123
                  release:
                    image: registry.redhat.io/openshift4/ose-cluster-version-operator:v4.14.0
                    version: 4.14.0
                  networking:
                    clusterNetwork:
                      - cidr: 10.10.0.0/16
                        hostPrefix: 24
                    serviceNetwork:
                      - 10.96.0.0/12
                  dns:
                    baseDomain: example.com
                generation: 2
                status:
                  conditions:
                    - type: Reconciled
                      status: 'True'
                      reason: ReconciledAll
                      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: LastKnownReconciled
                      status: 'True'
                      reason: AllAdaptersReconciled
                      message: All required adapters report Available=True for the tracked 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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - Clusters
      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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - NodePools
      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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - NodePools
      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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - NodePools
      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
                generation: 2
                spec:
                  platform:
                    type: template
                    template:
                      machineType: n1-standard-4
                      diskSize: 100
                      diskType: pd-standard
                      zones:
                        - us-central1-a
                        - us-central1-b
                      preemptible: false
                      labels:
                        team: platform
                        managedby: hyperfleet
                  nodeCount: 3
                  autoscaling:
                    enabled: true
                    minNodes: 1
                    maxNodes: 10
                    targetCPUUtilization: 80
                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: Reconciled
                      status: 'True'
                      reason: ReconciledAll
                      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: LastKnownReconciled
                      status: 'True'
                      reason: AllAdaptersReconciled
                      message: All required adapters report Available=True for the tracked 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: ValidationSuccessful
                      status: 'True'
                      reason: All validations passed
                      message: NodePool validation passed
                      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: NodePoolSuccessful
                      status: 'True'
                      reason: NodePool provisioned successfully
                      message: NodePool has 3 nodes running
                      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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - NodePools
      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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - NodePools
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodePoolPatchRequest'
      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.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '401':
          description: The request requires valid authentication credentials.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - NodePools
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/wifconfigs:
    get:
      operationId: getWifConfigs
      summary: List WIF configs
      description: Returns a paginated list of WIF configs, optionally filtered by labels or TSL query.
      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/WifConfigList'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - WifConfigs
      security:
        - BearerAuth: []
    post:
      operationId: postWifConfig
      summary: Create WIF config
      description: Creates a new WIF config.
      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/WifConfig'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - WifConfigs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WifConfigCreateRequest'
      security:
        - BearerAuth: []
  /api/hyperfleet/v1/wifconfigs/{wifconfig_id}:
    get:
      operationId: getWifConfigById
      summary: Get WIF config by ID
      description: Returns a single WIF config by its ID.
      parameters:
        - $ref: '#/components/parameters/SearchParams'
        - name: wifconfig_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WifConfig'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - WifConfigs
      security:
        - BearerAuth: []
    patch:
      operationId: patchWifConfigById
      summary: Patch WIF config by ID
      description: Patches a WIF config by ID. Supports partial updates to spec and labels.
      parameters:
        - name: wifconfig_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WifConfig'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - WifConfigs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WifConfigPatchRequest'
      security:
        - BearerAuth: []
    delete:
      operationId: deleteWifConfigById
      summary: Request WIF config deletion
      description: Marks a WIF config for deletion.
      parameters:
        - name: wifconfig_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/WifConfig'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictDetails'
        default:
          description: An unexpected error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
        - WifConfigs
      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
        minimum: 1
        default: 1
      explode: false
    QueryParams.pageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 20
      explode: false
    SearchParams:
      name: search
      in: query
      required: false
      description: |-
        Filter results using TSL (Tree Search Language) query syntax.
        Examples: `status.conditions.Reconciled='True'`, `name in ('c1','c2')`, `labels.region='us-east'`
      schema:
        type: string
      explode: false
  schemas:
    AcceleratorSpec:
      type: object
      required:
        - type
        - count
      properties:
        type:
          type: string
        count:
          type: integer
          minimum: 1
    AutoscalingSpec:
      type: object
      properties:
        enabled:
          type: boolean
        minNodes:
          type: integer
          minimum: 0
        maxNodes:
          type: integer
          minimum: 1
        targetCPUUtilization:
          type: integer
          minimum: 1
          maximum: 100
        targetMemoryUtilization:
          type: integer
          minimum: 1
          maximum: 100
        scaleDownDelay:
          type: string
        scaleUpDelay:
          type: string
    BadRequestDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      example:
        type: https://api.hyperfleet.io/errors/validation-error
        title: Validation Failed
        status: 400
        detail: The cluster name field is required
        instance: /api/hyperfleet/v1/clusters
        code: HYPERFLEET-VAL-001
        timestamp: '2024-01-15T10:30:00Z'
        trace_id: aabbccddeeff0011
    BearerAuth:
      type: object
      required:
        - type
        - scheme
      properties:
        type:
          type: string
          enum:
            - http
        scheme:
          type: string
          enum:
            - bearer
    Channel:
      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: 1
          maxLength: 63
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
        spec:
          $ref: '#/components/schemas/ChannelSpec'
        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
        status:
          $ref: '#/components/schemas/ResourceStatus'
      example:
        kind: Channel
        id: 019466a2-1234-7abc-9def-0123456789ab
        href: /api/hyperfleet/v1/channels/019466a2-1234-7abc-9def-0123456789ab
        name: stable
        labels:
          tier: production
        spec:
          is_default: true
          enabled_regex: ^4\.\d+\.\d+$
        generation: 1
        status:
          conditions: []
        created_time: '2025-06-01T00:00:00Z'
        updated_time: '2025-06-01T10:02:00Z'
        created_by: user-123@example.com
        updated_by: user-123@example.com
    ChannelCreateRequest:
      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: 1
          maxLength: 63
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
        spec:
          $ref: '#/components/schemas/ChannelSpec'
      example:
        kind: Channel
        name: stable
        labels:
          tier: production
        spec:
          is_default: true
          enabled_regex: ^4\.\d+\.\d+$
    ChannelList:
      type: object
      required:
        - page
        - size
        - total
        - items
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
    ChannelPatchRequest:
      type: object
      properties:
        spec:
          $ref: '#/components/schemas/ChannelSpec'
        labels:
          type: object
          additionalProperties:
            type: string
      example:
        spec:
          is_default: false
          enabled_regex: ^4\.17\.\d+$
        labels:
          tier: staging
      additionalProperties: false
      minProperties: 1
    ChannelSpec:
      type: object
      required:
        - is_default
        - enabled_regex
      properties:
        is_default:
          type: boolean
          description: Whether this is the default channel for new clusters
        enabled_regex:
          type: string
          description: Regex pattern for matching enabled version strings
    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:
          platform:
            type: template
            template:
              projectID: project-123
              region: us-central1
              zone: us-central1-a
              network: network-123
              subnet: subnet-123
          release:
            image: registry.redhat.io/openshift4/ose-cluster-version-operator:v4.14.0
            version: 4.14.0
          networking:
            clusterNetwork:
              - cidr: 10.10.0.0/16
                hostPrefix: 24
            serviceNetwork:
              - 10.96.0.0/12
          dns:
            baseDomain: example.com
        generation: 1
        status:
          conditions:
            - type: Reconciled
              status: 'True'
              reason: ReconciledAll
              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: LastKnownReconciled
              status: 'True'
              reason: AllAdaptersReconciled
              message: All required adapters report Available=True for the tracked 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:
          platform:
            type: template
            template:
              projectID: project-123
              region: us-central1
              zone: us-central1-a
              network: network-123
              subnet: subnet-123
          release:
            image: registry.redhat.io/openshift4/ose-cluster-version-operator:v4.14.0
            version: 4.14.0
          networking:
            clusterNetwork:
              - cidr: 10.10.0.0/16
                hostPrefix: 24
            serviceNetwork:
              - 10.96.0.0/12
          dns:
            baseDomain: example.com
    ClusterList:
      type: object
      required:
        - page
        - size
        - total
        - items
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Cluster'
    ClusterNetworkEntry:
      type: object
      properties:
        cidr:
          type: string
        hostPrefix:
          type: integer
    ClusterPatchRequest:
      type: object
      properties:
        spec:
          $ref: '#/components/schemas/ClusterSpec'
        labels:
          type: object
          additionalProperties:
            type: string
      example:
        spec:
          platform:
            type: template
            template:
              projectID: project-123
              region: us-central1
              zone: us-central1-a
              network: network-123
              subnet: subnet-123
          release:
            image: registry.redhat.io/openshift4/ose-cluster-version-operator:v4.14.0
            version: 4.14.0
          networking:
            clusterNetwork:
              - cidr: 10.10.0.0/16
                hostPrefix: 24
            serviceNetwork:
              - 10.96.0.0/12
          dns:
            baseDomain: example.com
        labels:
          env: staging
      additionalProperties: false
      minProperties: 1
    ClusterPlatform:
      type: object
      properties:
        projectID:
          type: string
        region:
          type: string
        zone:
          type: string
        network:
          type: string
        subnet:
          type: string
    ClusterPlatformSpec:
      type: object
      required:
        - type
        - template
      properties:
        type:
          type: string
          enum:
            - template
        template:
          $ref: '#/components/schemas/ClusterPlatform'
    ClusterSpec:
      type: object
      required:
        - platform
      properties:
        infraID:
          type: string
        platform:
          $ref: '#/components/schemas/ClusterPlatformSpec'
        release:
          $ref: '#/components/schemas/ReleaseSpec'
        networking:
          $ref: '#/components/schemas/NetworkingSpec'
        dns:
          $ref: '#/components/schemas/DNSSpec'
    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: "Reconciled"`: Whether the resource's desired state has been fully reconciled by all adapters at the current generation.
            - `type: "LastKnownReconciled"`: Sticky cross-generation condition — stays True as long as all required adapters were reconciled at a common observed generation, even if a newer generation is being processed.

            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.
    ConflictDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      example:
        type: https://api.hyperfleet.io/errors/resource-conflict
        title: Resource Conflict
        status: 409
        detail: This Cluster already exists
        instance: /api/hyperfleet/v1/clusters
        code: HYPERFLEET-CNF-001
        timestamp: '2024-01-15T10:30:00Z'
        trace_id: cafe0011aabb9988
    DNSSpec:
      type: object
      properties:
        baseDomain:
          type: string
    ForbiddenDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      example:
        type: https://api.hyperfleet.io/errors/permission-denied
        title: Permission Denied
        status: 403
        detail: You do not have permission to perform this action
        instance: /api/hyperfleet/v1/clusters
        code: HYPERFLEET-AUZ-001
        timestamp: '2024-01-15T10:30:00Z'
        trace_id: 99aabbcc11223344
    ForbiddenResponse:
      type: object
      required:
        - body
      properties:
        body:
          $ref: '#/components/schemas/ForbiddenDetails'
      description: The client does not have permission to perform this action.
    NetworkingSpec:
      type: object
      properties:
        clusterNetwork:
          type: array
          items:
            $ref: '#/components/schemas/ClusterNetworkEntry'
        serviceNetwork:
          type: array
          items:
            type: string
    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
        generation: 1
        spec:
          platform:
            type: template
            template:
              machineType: n1-standard-4
              diskSize: 100
              diskType: pd-standard
              zones:
                - us-central1-a
                - us-central1-b
              preemptible: false
              labels:
                team: platform
                managedby: hyperfleet
          nodeCount: 3
          autoscaling:
            enabled: true
            minNodes: 1
            maxNodes: 10
            targetCPUUtilization: 80
        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: Reconciled
              status: 'True'
              reason: ReconciledAll
              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: LastKnownReconciled
              status: 'True'
              reason: AllAdaptersReconciled
              message: All required adapters report Available=True for the tracked 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: ValidationSuccessful
              status: 'True'
              reason: All validations passed
              message: NodePool validation passed
              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: NodePoolSuccessful
              status: 'True'
              reason: NodePool provisioned successfully
              message: NodePool has 3 nodes running
              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:
        kind: NodePool
        name: worker-pool-1
        labels:
          environment: production
          pooltype: worker
        spec:
          platform:
            type: template
            template:
              machineType: n1-standard-4
              diskSize: 100
              diskType: pd-standard
              zones:
                - us-central1-a
                - us-central1-b
              preemptible: false
              labels:
                team: platform
                managedby: hyperfleet
          nodeCount: 3
          autoscaling:
            enabled: true
            minNodes: 1
            maxNodes: 10
            targetCPUUtilization: 80
    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:
        - page
        - size
        - total
        - items
      properties:
        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:
          platform:
            type: template
            template:
              machineType: n1-standard-4
              diskSize: 100
              diskType: pd-standard
              zones:
                - us-central1-a
                - us-central1-b
              preemptible: false
              labels:
                team: platform
                managedby: hyperfleet
          nodeCount: 3
          autoscaling:
            enabled: true
            minNodes: 1
            maxNodes: 10
            targetCPUUtilization: 80
        labels:
          env: staging
      additionalProperties: false
      minProperties: 1
    NodePoolPlatform:
      type: object
      properties:
        machineType:
          type: string
        diskSize:
          type: integer
          minimum: 10
        diskType:
          type: string
          enum:
            - pd-standard
            - pd-ssd
            - pd-balanced
        zones:
          type: array
          items:
            type: string
        preemptible:
          type: boolean
        accelerators:
          type: array
          items:
            $ref: '#/components/schemas/AcceleratorSpec'
        labels:
          type: object
          additionalProperties:
            type: string
        taints:
          type: array
          items:
            $ref: '#/components/schemas/TaintSpec'
    NodePoolPlatformSpec:
      type: object
      required:
        - type
        - template
      properties:
        type:
          type: string
          enum:
            - template
        template:
          $ref: '#/components/schemas/NodePoolPlatform'
    NodePoolSpec:
      type: object
      required:
        - platform
      properties:
        platform:
          $ref: '#/components/schemas/NodePoolPlatformSpec'
        nodeCount:
          type: integer
          minimum: 0
        autoscaling:
          $ref: '#/components/schemas/AutoscalingSpec'
    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: "Reconciled"`: Whether the resource's desired state has been fully reconciled by all adapters at the current generation.
            - `type: "LastKnownReconciled"`: Sticky cross-generation condition — stays True as long as all required adapters were reconciled at a common observed generation, even if a newer generation is being processed.

            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.
    NotFoundDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      example:
        type: https://api.hyperfleet.io/errors/resource-not-found
        title: Resource Not Found
        status: 404
        detail: Cluster with id='019466a0-8f8e-7abc-9def-0123456789ab' not found
        instance: /api/hyperfleet/v1/clusters/019466a0-8f8e-7abc-9def-0123456789ab
        code: HYPERFLEET-NTF-001
        timestamp: '2024-01-15T10:30:00Z'
        trace_id: deadbeef12345678
    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
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: URI reference identifying the problem type
        title:
          type: string
          description: Short human-readable summary of the problem
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
        instance:
          type: string
          format: uri-reference
          description: URI reference for this specific occurrence
        code:
          type: string
          description: Machine-readable error code in HYPERFLEET-CAT-NUM format
        timestamp:
          type: string
          format: date-time
          description: RFC3339 timestamp of when the error occurred
        trace_id:
          type: string
          description: Distributed trace ID for correlation
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Field-level validation errors (for validation failures)
      description: RFC 9457 Problem Details for HTTP APIs
      example:
        type: https://api.hyperfleet.io/errors/internal-error
        title: Internal Server Error
        status: 500
        detail: Unspecified error
        instance: /api/hyperfleet/v1/clusters
        code: HYPERFLEET-INT-001
        timestamp: '2024-01-15T10:30:00Z'
        trace_id: f0f0f0f0a1a1a1a1
    ReleaseSpec:
      type: object
      properties:
        image:
          type: string
        version:
          type: string
        channelGroup:
          type: string
    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 PUTs, 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
    ResourceStatus:
      type: object
      required:
        - conditions
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ResourceCondition'
      description: |-
        Aggregated status of the resource, populated by the status aggregation
        pipeline from adapter condition reports.
    TaintSpec:
      type: object
      required:
        - key
        - effect
      properties:
        key:
          type: string
        value:
          type: string
        effect:
          type: string
          enum:
            - NoSchedule
            - PreferNoSchedule
            - NoExecute
    UnauthorizedDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      example:
        type: https://api.hyperfleet.io/errors/authentication-required
        title: Authentication Required
        status: 401
        detail: Account authentication could not be verified
        instance: /api/hyperfleet/v1/clusters
        code: HYPERFLEET-AUT-001
        timestamp: '2024-01-15T10:30:00Z'
        trace_id: '1122334455667788'
    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
    Version:
      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: 1
          maxLength: 63
        spec:
          $ref: '#/components/schemas/VersionSpec'
        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
        owner_references:
          $ref: '#/components/schemas/ObjectReference'
        status:
          $ref: '#/components/schemas/ResourceStatus'
      example:
        kind: Version
        id: 019466a3-5678-7abc-9def-0123456789ab
        href: /api/hyperfleet/v1/channels/019466a2-1234-7abc-9def-0123456789ab/versions/019466a3-5678-7abc-9def-0123456789ab
        name: 4.17.12
        labels: {}
        spec:
          raw_version: 4.17.12
          enabled: true
          is_default: true
          release_image: quay.io/openshift-release-dev/ocp-release:4.17.12-multi
        generation: 1
        owner_references:
          id: 019466a2-1234-7abc-9def-0123456789ab
          kind: Channel
          href: /api/hyperfleet/v1/channels/019466a2-1234-7abc-9def-0123456789ab
        status:
          conditions: []
        created_time: '2025-06-01T00:00:00Z'
        updated_time: '2025-06-01T10:02:00Z'
        created_by: user-123@example.com
        updated_by: user-123@example.com
    VersionCreateRequest:
      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: 1
          maxLength: 63
        spec:
          $ref: '#/components/schemas/VersionSpec'
      example:
        kind: Version
        name: 4.17.12
        labels: {}
        spec:
          raw_version: 4.17.12
          enabled: true
          is_default: true
          release_image: quay.io/openshift-release-dev/ocp-release:4.17.12-multi
    VersionList:
      type: object
      required:
        - page
        - size
        - total
        - items
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Version'
    VersionPatchRequest:
      type: object
      properties:
        spec:
          $ref: '#/components/schemas/VersionSpec'
        labels:
          type: object
          additionalProperties:
            type: string
      example:
        spec:
          raw_version: 4.17.12
          enabled: false
          is_default: false
          release_image: quay.io/openshift-release-dev/ocp-release:4.17.12-multi
        labels:
          deprecated: 'true'
      additionalProperties: false
      minProperties: 1
    VersionSpec:
      type: object
      required:
        - raw_version
        - enabled
        - is_default
        - release_image
      properties:
        raw_version:
          type: string
          description: Raw version string (e.g., "4.17.12")
        enabled:
          type: boolean
          description: Whether this version is enabled for provisioning
        is_default:
          type: boolean
          description: Whether this is the default version for its channel
        release_image:
          type: string
          description: Container image reference for the release
        end_of_life_time:
          type: string
          format: date-time
          description: When this version reaches end of life
    WifConfig:
      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: 1
          maxLength: 63
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
        spec:
          $ref: '#/components/schemas/WifConfigSpec'
        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
        status:
          $ref: '#/components/schemas/ResourceStatus'
      example:
        kind: WifConfig
        id: 019466a2-5678-7abc-9def-0123456789ab
        href: /api/hyperfleet/v1/wifconfigs/019466a2-5678-7abc-9def-0123456789ab
        name: my-wif-config
        labels:
          environment: production
        spec:
          version: '4.17'
          project_id: my-gcp-project-123
        generation: 1
        status:
          conditions: []
        created_time: '2025-06-01T00:00:00Z'
        updated_time: '2025-06-01T10:02:00Z'
        created_by: user-123@example.com
        updated_by: user-123@example.com
    WifConfigCreateRequest:
      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: 1
          maxLength: 63
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
        spec:
          $ref: '#/components/schemas/WifConfigSpec'
      example:
        kind: WifConfig
        name: my-wif-config
        labels:
          environment: production
        spec:
          version: '4.17'
          project_id: my-gcp-project-123
    WifConfigList:
      type: object
      required:
        - page
        - size
        - total
        - items
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/WifConfig'
    WifConfigPatchRequest:
      type: object
      properties:
        spec:
          $ref: '#/components/schemas/WifConfigSpec'
        labels:
          type: object
          additionalProperties:
            type: string
      example:
        spec:
          version: '4.18'
          project_id: my-gcp-project-456
        labels:
          environment: staging
      additionalProperties: false
      minProperties: 1
    WifConfigSpec:
      type: object
      required:
        - version
        - project_id
      properties:
        version:
          type: string
          description: Version of the WIF configuration
        project_id:
          type: string
          description: GCP project identifier
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
servers:
  - url: https://hyperfleet.redhat.com
    description: Production
    variables: {}