openapi: 3.1.0
info:
  title: Volcano Job Jobs Queues API
  description: The Volcano Job API provides Kubernetes CRD endpoints for defining and managing batch workloads using Volcano's Job resource (vcjob). Volcano Jobs support multiple task types, lifecycle policies, gang scheduling, and integration with frameworks including TensorFlow, PyTorch, Spark, and MPI. All operations go through the Kubernetes API server.
  version: 1.10.0
  contact:
    name: Volcano Community
    url: https://volcano.sh/en/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{kubernetes-api-server}
  description: Kubernetes API server
  variables:
    kubernetes-api-server:
      default: localhost:6443
      description: Address of the Kubernetes API server
tags:
- name: Queues
  description: Operations for managing Volcano Queue cluster-scoped custom resources. Queues define scheduling namespaces with weight-based fair sharing, resource capacity, and state management for batch workloads.
paths:
  /apis/scheduling.volcano.sh/v1beta1/queues:
    get:
      operationId: listQueues
      summary: List Volcano Queues
      description: Returns all Volcano Queue resources in the cluster. Queues are cluster-scoped resources and are not namespaced. Each queue defines a scheduling partition with weight, capacity, and state.
      tags:
      - Queues
      parameters:
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/fieldSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continueToken'
      responses:
        '200':
          description: List of Volcano Queues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      operationId: createQueue
      summary: Create a Volcano Queue
      description: Creates a new cluster-scoped Volcano Queue resource. The queue spec defines its weight for fair-share scheduling, resource capacity, and whether it allows preemption of lower-priority jobs.
      tags:
      - Queues
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Queue'
      responses:
        '201':
          description: Queue created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '400':
          description: Invalid Queue specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: Queue with this name already exists
  /apis/scheduling.volcano.sh/v1beta1/queues/{name}:
    get:
      operationId: readQueue
      summary: Get a Volcano Queue
      description: Returns the specified Volcano Queue resource including its current state, allocated resources, pending jobs, and condition information.
      tags:
      - Queues
      parameters:
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Queue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Queue not found
    put:
      operationId: replaceQueue
      summary: Replace a Volcano Queue
      description: Replaces the entire Volcano Queue resource with the provided specification.
      tags:
      - Queues
      parameters:
      - $ref: '#/components/parameters/name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Queue'
      responses:
        '200':
          description: Queue updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '400':
          description: Invalid specification
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
    patch:
      operationId: patchQueue
      summary: Partially update a Volcano Queue
      description: Applies a partial update to the specified Queue using JSON Merge Patch or Strategic Merge Patch.
      tags:
      - Queues
      parameters:
      - $ref: '#/components/parameters/name'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
      responses:
        '200':
          description: Queue patched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '400':
          description: Invalid patch
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
    delete:
      operationId: deleteQueue
      summary: Delete a Volcano Queue
      description: Deletes the specified Volcano Queue. Deleting a queue that has pending jobs will cause those jobs to fail to be scheduled.
      tags:
      - Queues
      parameters:
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Queue deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Queue not found
components:
  schemas:
    Queue:
      type: object
      description: A Volcano Queue cluster-scoped custom resource defining a scheduling partition with weight-based fair sharing, resource quotas, and job admission controls.
      required:
      - apiVersion
      - kind
      - metadata
      - spec
      properties:
        apiVersion:
          type: string
          enum:
          - scheduling.volcano.sh/v1beta1
        kind:
          type: string
          enum:
          - Queue
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/QueueSpec'
        status:
          $ref: '#/components/schemas/QueueStatus'
    QueueList:
      type: object
      description: A list of Volcano Queue resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          enum:
          - QueueList
        metadata:
          type: object
          properties:
            resourceVersion:
              type: string
        items:
          type: array
          description: List of Queue resources.
          items:
            $ref: '#/components/schemas/Queue'
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the queue, unique cluster-wide.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Labels for organizing and selecting the queue.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Non-identifying metadata for the queue.
        resourceVersion:
          type: string
          description: Internal version for optimistic concurrency.
        uid:
          type: string
        creationTimestamp:
          type: string
          format: date-time
    Status:
      type: object
      description: Kubernetes Status object for error responses.
      properties:
        message:
          type: string
        reason:
          type: string
        code:
          type: integer
    QueueSpec:
      type: object
      description: Specification of a Volcano Queue.
      properties:
        weight:
          type: integer
          description: Relative weight of this queue for fair-share scheduling. Higher weight queues receive proportionally more resources when there is resource contention. Defaults to 1.
          minimum: 1
          default: 1
        capability:
          type: object
          description: Maximum resource allocation for this queue. Jobs submitted to this queue cannot collectively use more resources than specified here. Uses Kubernetes resource quantity format.
          additionalProperties:
            type: string
          example:
            cpu: '16'
            memory: 32Gi
        reclaimable:
          type: boolean
          description: If true, resources allocated to idle jobs in this queue can be reclaimed by other queues that need them. Enables opportunistic resource sharing.
          default: true
        extendClusters:
          type: array
          description: List of extended cluster references for multi-cluster scheduling. Allows jobs in this queue to be dispatched across cluster boundaries.
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the remote cluster.
              weight:
                type: integer
                description: Relative scheduling weight for this remote cluster.
              capacity:
                type: object
                description: Resource capacity of the remote cluster.
                additionalProperties:
                  type: string
        guarantee:
          type: object
          description: Guaranteed minimum resource allocation for this queue. The scheduler ensures at least this amount of resources is always available to jobs in this queue regardless of other queue pressure.
          properties:
            resource:
              type: object
              additionalProperties:
                type: string
              description: 'Minimum guaranteed resources using Kubernetes resource quantity format, e.g. {"cpu": "4", "memory": "8Gi"}.'
        parent:
          type: string
          description: Name of the parent queue for hierarchical queue structures. Enables nested queue trees for complex multi-tenant scheduling.
    QueueStatus:
      type: object
      description: Observed status of a Volcano Queue including resource usage, job counts, and operational state.
      properties:
        state:
          type: string
          description: Current operational state of the queue.
          enum:
          - Open
          - Closed
          - Draining
          - Unknown
        pending:
          type: integer
          format: int32
          description: Number of PodGroups in the Pending phase in this queue.
        running:
          type: integer
          format: int32
          description: Number of PodGroups in the Running phase in this queue.
        unknown:
          type: integer
          format: int32
          description: Number of PodGroups in the Unknown phase in this queue.
        inqueue:
          type: integer
          format: int32
          description: Number of PodGroups queued and waiting for resources.
        guaranteed:
          type: object
          description: Guaranteed resource allocation for this queue.
          additionalProperties:
            type: string
        allocated:
          type: object
          description: Currently allocated resources across all running jobs in this queue.
          additionalProperties:
            type: string
        reservation:
          type: object
          description: Reserved resource allocation for this queue.
          properties:
            nodes:
              type: object
              additionalProperties:
                type: string
            resource:
              type: object
              additionalProperties:
                type: string
        conditions:
          type: array
          description: Current conditions of the queue.
          items:
            type: object
            properties:
              type:
                type: string
              status:
                type: string
                enum:
                - 'True'
                - 'False'
                - Unknown
              reason:
                type: string
              message:
                type: string
              transitionID:
                type: string
              lastTransitionTime:
                type: string
                format: date-time
  parameters:
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results per page.
      schema:
        type: integer
        minimum: 1
    fieldSelector:
      name: fieldSelector
      in: query
      required: false
      description: Field selector to restrict results.
      schema:
        type: string
    labelSelector:
      name: labelSelector
      in: query
      required: false
      description: Label selector to restrict results.
      schema:
        type: string
    continueToken:
      name: continue
      in: query
      required: false
      description: Continuation token for paginating large result sets.
      schema:
        type: string
    name:
      name: name
      in: path
      required: true
      description: The name of the Queue resource.
      schema:
        type: string
externalDocs:
  description: Volcano Job Documentation
  url: https://volcano.sh/en/docs/vcjob/