Add custom interpreter for Raycluster

[owenowenisme]

What type of PR is this?
/kind feature

What this PR does / why we need it:

Which issue(s) this PR fixes:

Part of #6588
Special notes for your reviewer:

❯ karmadactl interpret -f customizations.yaml --operation InterpretHealth --observed-file testdata/observed-raycluster.yaml
 
---
# [1/1] healthy:
true

❯ karmadactl interpret -f customizations.yaml --operation InterpretReplica --desired-file testdata/desired-raycluster.yaml
---
# [1/2] replica:
2
---
# [2/2] requires:
resourceRequest:
    cpu: "1"
    memory: 2G

❯ karmadactl interpret -f customizations.yaml --operation AggregateStatus 
--desired-file testdata/desired-raycluster.yaml --status-file testdata/sta
tus-file.yaml
---
# [1/1] aggregatedStatus:
apiVersion: ray.io/v1
kind: RayCluster
metadata:
    name: sample
spec:
    headGroupSpec:
        template:
            spec:
                containers:
                    - image: rayproject/ray:2.46.0
                      name: ray-head
                      ports:
                        - containerPort: 6379
                          name: gcs-server
                        - containerPort: 8265
                          name: dashboard
                        - containerPort: 10001
                          name: client
                      resources:
                        limits:
                            cpu: 1
                            memory: 2G
                        requests:
                            cpu: 1
                            memory: 2G
    rayVersion: 2.46.0
    workerGroupSpecs:
        - groupName: workergroup
          maxReplicas: 5
          minReplicas: 1
          replicas: 1
          template:
            spec:
                containers:
                    image: rayproject/ray:2.46.0
                    resources:
                        limits:
                            cpu: 1
                            memory: 1G
                        requests:
                            cpu: 1
                            memory: 1G
status:
    conditions:
        - lastTransitionTime: "2025-09-21T03:55:30Z"
          message: ""
          reason: HeadPodRunningAndReady
          status: "True"
          type: HeadPodReady
        - lastTransitionTime: "2025-09-21T03:55:45Z"
          message: All Ray Pods are ready for the first time
          reason: AllPodRunningAndReadyFirstTime
          status: "True"
          type: RayClusterProvisioned
        - lastTransitionTime: "2025-09-21T03:54:44Z"
          message: ""
          reason: RayClusterSuspended
          status: "False"
          type: RayClusterSuspended
        - lastTransitionTime: "2025-09-21T03:54:44Z"
          message: ""
          reason: RayClusterSuspending
          status: "False"
          type: RayClusterSuspending
    desiredCPU: "2"
    desiredGPU: "0"
    desiredMemory: 3G
    desiredTPU: "0"
    endpoints:
        client: "10001"
        dashboard: "8265"
        gcs-server: "6379"
        metrics: "8080"
    head:
        podIP: 10.244.0.6
        podName: sample-head-9cvfc
        serviceIP: 10.244.0.6
        serviceName: sample-head-svc
    lastUpdateTime: "2025-09-21T03:55:45Z"
    maxWorkerReplicas: 5
    minWorkerReplicas: 1
    observedGeneration: 1
    readyWorkerReplicas: 1
    state: ready
    stateTransitionTimes:
        ready: "2025-09-21T03:55:45Z"

❯ karmadactl interpret -f customizations.yaml --operation InterpretComponent --observ
ed-file testdata/observed-raycluster.yaml
---
# [1/1] components:
- name: ray-head
  replicaRequirements:
    resourceRequest:
        cpu: "1"
        memory: 1953125Ki
  replicas: 1
- name: workergroup
  replicaRequirements:
    resourceRequest:
        cpu: "1"
        memory: 1G
  replicas: 1

Does this PR introduce a user-facing change?:

[karmada-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 assign chaunceyjiang for approval. For more information see the Kubernetes Code Review Process.

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

Needs approval from an approver in each of these files:

• pkg/resourceinterpreter/default/thirdparty/OWNERS

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

[karmada-bot]

Welcome @owenowenisme! It looks like this is your first PR to karmada-io/karmada 🎉

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 45.86%. Comparing base (f9cd5c9) to head (2c8a60a).
⚠️ Report is 34 commits behind head on master.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6766      +/-   ##
==========================================
+ Coverage   45.73%   45.86%   +0.13%     
==========================================
  Files         689      690       +1     
  Lines       57152    57392     +240     
==========================================
+ Hits        26136    26322     +186     
- Misses      29384    29432      +48     
- Partials     1632     1638       +6     

Flag	Coverage Δ
unittests	45.86% <ø> (+0.13%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[RainbowMango]

Looks pretty good so far. Thank Owne, please cc me once this ready for review.

Just a reminder, you might need it when implementing the GetComponents interface, we have the util accuratePodRequirements, it helps to parse the requirements from a pod template. For example:

karmada/pkg/resourceinterpreter/default/thirdparty/resourcecustomizations/argoproj.io/v1alpha1/Workflow/customizations.yaml

Line 23 in 13c28a0

requirement = kube.accuratePodRequirements(podTemplateSpec)

[owenowenisme]

@RainbowMango Would you mind reviewing this PR?

[Copilot]

Pull Request Overview

This PR adds a custom resource interpreter for RayCluster resources from the ray.io/v1 API. It provides comprehensive interpretation capabilities for handling Ray distributed computing clusters within Karmada.

Key changes:

• Implements five core operations: health interpretation, replica calculation, status aggregation, status reflection, and component resource analysis
• Provides proper handling of Ray's head and worker group architecture with resource requirements calculation
• Includes comprehensive test data and test configurations

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
customizations.yaml	Main interpreter configuration with Lua scripts for all RayCluster operations
customizations_tests.yaml	Test configuration defining test cases for each operation
desired-raycluster.yaml	Test data representing desired RayCluster state
observed-raycluster.yaml	Test data representing observed RayCluster state with full status
status-file.yaml	Test data containing status information for aggregation testing

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[RainbowMango]

@RainbowMango Would you mind reviewing this PR?

Sure, will do by this week. (Not sure if I have enough time before Wednesday, as I'm on a business trip.)