Add HyperJob user guide and example manifests

[Copilot]

No user-facing documentation existed for HyperJob despite the CRD and controller design doc being present. This adds a user guide and annotated example YAMLs covering the primary use cases.

User guide (docs/user-guide/hyperjob-user-guide.md)

• Prerequisites and CRD installation
• Full API reference table for HyperJobSpec / ReplicatedJob fields
• Status semantics — when conditions are/aren't set, what replicatedJobsStatus aggregates
• Child resource naming convention: {hyperjob-name}-{replicatedjob-name}-{index}
• Three annotated use cases with inline YAML (see below)
• kubectl commands for apply / monitor / delete
• Troubleshooting section (missing CRD, VCJobs not scheduled, stuck conditions)

Example manifests (docs/deploy/example/hyperjob/)

File	Use case
llm-training.yaml	Split 256-GPU job across two clusters (replicas: 2, 128 workers each)
heterogeneous-training.yaml	Ascend 910B + 910C clusters with node affinity and clusterNames pinning
cluster-affinity-training.yaml	3-cluster fault-tolerant job with minAvailable: 2 and PodEvicted → RestartJob

Example — large-scale job splitting:

apiVersion: training.volcano.sh/v1alpha1
kind: HyperJob
metadata:
  name: llm-training
spec:
  minAvailable: 2
  replicatedJobs:
  - name: trainer
    replicas: 2          # creates llm-training-trainer-0 and llm-training-trainer-1
    templateSpec:
      tasks:
      - name: worker
        replicas: 128
        template:
          spec:
            containers:
            - name: trainer
              image: training-image:v1
              resources:
                requests:
                  nvidia.com/gpu: "1"

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add user guide and examples for HyperJob</issue_title>
<issue_description>Currently, there are no user guides or practical examples for HyperJob in the docs directory. While the repository contains the CRD definition (docs/deploy/training.volcano.sh_hyperjobs.yaml) and the controller design document (docs/proposals/hyperjob-controller-design.md), users need clear guidance on how to actually use this feature.

We should add:

1. A comprehensive user guide for HyperJob in volcano-global.
2. Example YAML manifests demonstrating different HyperJob configurations.

The documentation and examples can be based on the use cases described in the HyperJob API proposal from the main volcano repository.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add user guide and examples for HyperJob #62

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[volcano-sh-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from jessestutler. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Copilot]

Pull request overview

Adds missing end-user documentation for the HyperJob CRD in volcano-global, including a user guide and example manifests to help users apply, monitor, and troubleshoot multi-cluster AI training jobs.

Changes:

• Added a HyperJob user guide with prerequisites, API/status explanations, and usage/troubleshooting commands.
• Added three annotated HyperJob example YAML manifests covering job splitting, heterogeneous clusters, and cluster-affinity scenarios.
• Documented child resource naming conventions and linked to the controller design doc and related references.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 9 comments.

File	Description
docs/user-guide/hyperjob-user-guide.md	New end-user guide describing HyperJob usage, API fields, status semantics, and troubleshooting.
docs/deploy/example/hyperjob/llm-training.yaml	Example manifest for splitting a large GPU training job across clusters.
docs/deploy/example/hyperjob/heterogeneous-training.yaml	Example manifest showing accelerator/cluster targeting with clusterNames + node affinity.
docs/deploy/example/hyperjob/cluster-affinity-training.yaml	Example manifest for multi-cluster placement and restart policy behavior (wording needs alignment with current controller behavior).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The header comment says clusterNames pins each replica to a specific cluster and that each VCJob will be scheduled to its “respective” preferred cluster. In practice the controller sets clusterAffinity.clusterNames for every generated PropagationPolicy, which only restricts eligible clusters; it does not guarantee a 1:1 mapping between replicas and clusters or that replicas land on distinct clusters. Please adjust the wording to avoid over-promising placement behavior.

[Copilot]

pending/running/succeeded/failed/... here are aggregated from each child VCJob’s status.{pending,running,...} fields (i.e., task/pod counts in Volcano JobStatus), not counts of child VCJobs. Consider clarifying this in the snippet/description to prevent users from interpreting running: 256 as “256 VCJobs”.

[Copilot]

The API reference/field table claims to describe HyperJobSpec/ReplicatedJob, but it omits fields that exist in the shipped CRD (e.g., spec.maxDomains, spec.plugins, and replicatedJobs[].splitPolicy). Either document these fields or explicitly state the table is a partial subset so readers don’t assume they don’t exist.

[Copilot]

clusterNames is described here as a preference list ("attempts to place replicas on these clusters first"), but the controller generates a Karmada clusterAffinity.clusterNames, which is a hard constraint/restriction to those clusters (not an ordered preference). Update the description to reflect the actual behavior.

[Copilot]

This status example shows both Completed and Failed conditions set to True at the same time. The controller sets a single terminal condition (either Completed or Failed) once all child VCJobs are finished. Adjust the example to show only one terminal condition being present.

[Copilot]

The jobStates map values are not just a phase string. In the CRD/controller they are a JobState object (e.g., phase, reason, message, lastTransitionTime). Consider updating the snippet to reflect the actual structure so users know what to expect in status.replicatedJobsStatus[].jobStates.

[Copilot]

This case describes spec.minAvailable as enabling fault-tolerance/health semantics ("remains healthy even if one cluster becomes unavailable"), but HyperJob.spec.minAvailable is currently not enforced by the controller. Please reword this section to avoid implying it affects scheduling or job continuity today (or clearly mark it as future/placeholder behavior).

[Copilot]

This example text implies spec.minAvailable: 2 makes the HyperJob “considered healthy” while 2/3 jobs are running, but HyperJob.spec.minAvailable is currently not enforced by the controller. Consider removing/softening this claim or adding a note that it’s reserved for future fault-tolerance behavior.

[Copilot]

The inline comment in the API YAML (minAvailable: ... # Minimum number of VCJobs that must be running) reads like an enforced guarantee, but later the guide notes this field is currently not enforced by the controller. Consider aligning the comment here with that reality (e.g., mark it as reserved/future behavior).