docs(deployment-operator): clarify CustomHealth scripts (#4000)

Co-authored-by: Michael Guarino <mjg@plural.sh>

Author: plural-copilot[bot]

go/deployment-operator/api/v1alpha1/customhealth_types.go

@@ -23,6 +23,14 @@ import (
 
 // CustomHealthSpec defines the desired state of CustomHealth
 type CustomHealthSpec struct {
+	// Script is a Lua health-assessment script. The target resource is available as the global `Obj`.
+	//
+	// The script must assign a Lua table to the global `healthStatus`; a Lua `return { ... }` is not consumed.
+	// The table uses `status` and an optional `message`, for example: `healthStatus = { status = "Healthy", message = "resource is ready" }`.
+	//
+	// Supported/intended status values are `Healthy`, `Degraded`, `Paused`, `Unknown`, `Progressing`, `Suspended`, and `Missing`.
+	//
+	// See https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator/custom-health for the full guide.
 	Script string `json:"script,omitempty"`
 
 	// +kubebuilder:validation:Optional

go/deployment-operator/config/crd/bases/deployments.plural.sh_customhealths.yaml

@@ -44,6 +44,15 @@ spec:
               kind:
                 type: string
               script:
+                description: |-
+                  Script is a Lua health-assessment script. The target resource is available as the global `Obj`.
+
+                  The script must assign a Lua table to the global `healthStatus`; a Lua `return { ... }` is not consumed.
+                  The table uses `status` and an optional `message`, for example: `healthStatus = { status = "Healthy", message = "resource is ready" }`.
+
+                  Supported/intended status values are `Healthy`, `Degraded`, `Paused`, `Unknown`, `Progressing`, `Suspended`, and `Missing`.
+
+                  See https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator/custom-health for the full guide.
                 type: string
               version:
                 type: string

go/deployment-operator/docs/api.md

@@ -585,7 +585,7 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `script` _string_ |  |  |  |
+| `script` _string_ | Script is a Lua health-assessment script. The target resource is available as the global `Obj`.<br />The script must assign a Lua table to the global `healthStatus`; a Lua `return \{ ... \}` is not consumed.<br />The table uses `status` and an optional `message`, for example: `healthStatus = \{ status = "Healthy", message = "resource is ready" \}`.<br />Supported/intended status values are `Healthy`, `Degraded`, `Paused`, `Unknown`, `Progressing`, `Suspended`, and `Missing`.<br />See https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator/custom-health for the full guide. |  |  |
 | `group` _string_ |  |  | Optional: \{\} <br /> |
 | `version` _string_ |  |  | Optional: \{\} <br /> |
 | `kind` _string_ |  |  | Optional: \{\} <br /> |