openapi: 3.1.0
info:
  title: Volcano Job Jobs PodGroups 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: PodGroups
  description: Operations for managing Volcano PodGroup custom resources. PodGroups define gang scheduling units with minimum availability requirements and queue assignment.
paths:
  /apis/scheduling.volcano.sh/v1beta1/namespaces/{namespace}/podgroups:
    get:
      operationId: listNamespacedPodGroup
      summary: Volcano List PodGroups in a namespace
      description: Returns all Volcano PodGroup resources in the specified namespace. PodGroups are typically created automatically by the Volcano controller when a Volcano Job is submitted, but can also be created manually for pods without a Job parent.
      tags:
      - PodGroups
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/fieldSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continueToken'
      responses:
        '200':
          description: List of PodGroups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodGroupList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      operationId: createNamespacedPodGroup
      summary: Volcano Create a PodGroup
      description: Creates a new PodGroup resource in the specified namespace. Pods can reference this PodGroup via the scheduling.volcano.sh/pod-group annotation to join the group and benefit from gang scheduling.
      tags:
      - PodGroups
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PodGroup'
      responses:
        '201':
          description: PodGroup created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodGroup'
        '400':
          description: Invalid PodGroup specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: PodGroup with this name already exists
  /apis/scheduling.volcano.sh/v1beta1/namespaces/{namespace}/podgroups/{name}:
    get:
      operationId: readNamespacedPodGroup
      summary: Volcano Get a PodGroup
      description: Returns the specified PodGroup resource including its current phase, pod counts, and condition information.
      tags:
      - PodGroups
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: PodGroup details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodGroup'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: PodGroup not found
    put:
      operationId: replaceNamespacedPodGroup
      summary: Volcano Replace a PodGroup
      description: Replaces the entire PodGroup resource with the provided specification.
      tags:
      - PodGroups
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PodGroup'
      responses:
        '200':
          description: PodGroup updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodGroup'
        '400':
          description: Invalid specification
        '401':
          description: Unauthorized
        '404':
          description: PodGroup not found
    patch:
      operationId: patchNamespacedPodGroup
      summary: Volcano Partially update a PodGroup
      description: Applies a partial update to the specified PodGroup.
      tags:
      - PodGroups
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
      responses:
        '200':
          description: PodGroup patched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodGroup'
        '400':
          description: Invalid patch
        '401':
          description: Unauthorized
        '404':
          description: PodGroup not found
    delete:
      operationId: deleteNamespacedPodGroup
      summary: Volcano Delete a PodGroup
      description: Deletes the specified PodGroup resource. Pods in the group that are pending may be removed from scheduling consideration.
      tags:
      - PodGroups
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: PodGroup deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: PodGroup not found
  /apis/scheduling.volcano.sh/v1beta1/podgroups:
    get:
      operationId: listPodGroupAllNamespaces
      summary: Volcano List PodGroups across all namespaces
      description: Returns all PodGroup resources across all namespaces in the cluster.
      tags:
      - PodGroups
      parameters:
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/fieldSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continueToken'
      responses:
        '200':
          description: All PodGroups in the cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodGroupList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the PodGroup, unique within its namespace.
        namespace:
          type: string
          description: Namespace the PodGroup belongs to.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Labels for organizing and selecting the PodGroup.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Non-identifying metadata for the PodGroup.
        resourceVersion:
          type: string
        uid:
          type: string
        creationTimestamp:
          type: string
          format: date-time
    PodGroupSpec:
      type: object
      description: Specification of a PodGroup defining gang scheduling requirements.
      properties:
        minMember:
          type: integer
          description: Minimum number of pods that must be scheduled simultaneously. If fewer than this number of pods can be placed, no pods in the group are scheduled (all-or-nothing semantics).
          minimum: 1
          default: 1
        minResources:
          type: object
          description: Minimum aggregate resource requests that must be satisfiable for the PodGroup to be scheduled. Expressed as Kubernetes resource quantities.
          additionalProperties:
            type: string
          example:
            cpu: '8'
            memory: 16Gi
        queue:
          type: string
          description: Name of the Volcano Queue this PodGroup belongs to. Determines scheduling priority and resource quota application. Defaults to the 'default' queue.
          default: default
        priorityClassName:
          type: string
          description: Name of the PriorityClass for this PodGroup, controlling its scheduling priority relative to other PodGroups.
        minTaskMember:
          type: object
          description: Map of task names to minimum member counts for per-task gang scheduling requirements within a multi-task job.
          additionalProperties:
            type: integer
    Status:
      type: object
      description: Kubernetes Status object for error responses.
      properties:
        message:
          type: string
        reason:
          type: string
        code:
          type: integer
    PodGroupCondition:
      type: object
      description: A condition describing the state of the PodGroup.
      properties:
        type:
          type: string
          description: Type of PodGroup condition.
          enum:
          - Unschedulable
          - Scheduled
        status:
          type: string
          enum:
          - 'True'
          - 'False'
          - Unknown
        transitionID:
          type: string
          description: Identifier linking this condition to a specific scheduler transition.
        lastTransitionTime:
          type: string
          format: date-time
          description: Time when this condition last transitioned.
        reason:
          type: string
          description: Short reason code for the condition.
        message:
          type: string
          description: Human-readable details about the condition.
    PodGroup:
      type: object
      description: A Volcano PodGroup custom resource representing a set of pods that must be co-scheduled together. PodGroups enable gang scheduling semantics for distributed computing workloads.
      required:
      - apiVersion
      - kind
      - metadata
      - spec
      properties:
        apiVersion:
          type: string
          enum:
          - scheduling.volcano.sh/v1beta1
        kind:
          type: string
          enum:
          - PodGroup
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/PodGroupSpec'
        status:
          $ref: '#/components/schemas/PodGroupStatus'
    PodGroupList:
      type: object
      description: A list of PodGroup resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          enum:
          - PodGroupList
        metadata:
          type: object
          properties:
            resourceVersion:
              type: string
        items:
          type: array
          description: List of PodGroup resources.
          items:
            $ref: '#/components/schemas/PodGroup'
    PodGroupStatus:
      type: object
      description: Observed status of a PodGroup as reported by the Volcano scheduler, including current phase and pod state counts.
      properties:
        phase:
          type: string
          description: Current scheduling phase of the PodGroup.
          enum:
          - Pending
          - Running
          - Unknown
          - Inqueue
          - Completing
        occupiedBy:
          type: string
          description: Name of the Volcano Job that owns this PodGroup, if any.
        conditions:
          type: array
          description: Conditions describing the current state of the PodGroup.
          items:
            $ref: '#/components/schemas/PodGroupCondition'
        succeeded:
          type: integer
          format: int32
          description: Number of pods in the Succeeded phase.
        failed:
          type: integer
          format: int32
          description: Number of pods in the Failed phase.
        running:
          type: integer
          format: int32
          description: Number of pods in the Running phase.
  parameters:
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results per page.
      schema:
        type: integer
        minimum: 1
    labelSelector:
      name: labelSelector
      in: query
      required: false
      description: Label selector to restrict results.
      schema:
        type: string
    fieldSelector:
      name: fieldSelector
      in: query
      required: false
      description: Field selector to restrict results.
      schema:
        type: string
    namespace:
      name: namespace
      in: path
      required: true
      description: The Kubernetes namespace of the resource.
      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 resource.
      schema:
        type: string
externalDocs:
  description: Volcano Job Documentation
  url: https://volcano.sh/en/docs/vcjob/