docs(deployment-operator): clarify CustomHealth scripts

[plural-copilot]

Summary

• Document the authoritative CustomHealthSpec.Script Lua contract and regenerate the checked-in CRD reference docs.
• Include the matching controller-gen CustomHealth CRD description generated during the manifests attempt.

Lua output semantics

• The target Kubernetes resource is exposed to Lua as global Obj.
• A script must assign a Lua table to global healthStatus; return { ... } is not consumed and is insufficient.
• The table contains status and optional message, e.g. healthStatus = { status = "Healthy", message = "resource is ready" }.
• Supported/intended names and Console component states: Healthy → Running; Degraded → Failed; Paused → Paused; Unknown, Progressing, Suspended, and Missing → Pending.

Canonical guide

https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator/custom-health

Changed files

• go/deployment-operator/api/v1alpha1/customhealth_types.go — authoritative Script GoDoc.
• go/deployment-operator/docs/api.md — generated CRD reference Markdown from make crd-docs.
• go/deployment-operator/config/crd/bases/deployments.plural.sh_customhealths.yaml — controller-gen output for the Script description.

Generation and validation

• Passed: make crd-docs from go/deployment-operator (run in the pinned golang:1.26.5-alpine3.23 container because the host has no Go toolchain). crd-ref-docs emitted its existing max-recursion-depth warnings but generated docs/api.md successfully.
• make manifests was attempted. controller-gen generated the CustomHealth CRD description, then codegen-chart-crds failed with exit 2 because cp could not create the missing destination ../../charts/deployment-operator/crds. No generated YAML was hand-edited; only the legitimate CustomHealth controller-gen output is included, and unrelated regeneration output was reverted.
• Passed: gofmt with the pinned Go container, git diff --check, and a generated-document content check covering all required semantics and the exact guide URL.
• Blocked by environment: go test ./pkg/lua compiled but its Ginkgo BeforeSuite failed before specs because envtest etcd is absent at ../../bin/k8s/1.28.3-linux-amd64/etcd.

[plural-copilot]

This PR was generated by the codex Plural Agent Runtime. Here's some useful information you might want to know to evaluate the ai's perfomance:

Name	Details
💬 Prompt	Create one focused PR updating the authoritative CustomHealth CRD documentation in this repository. Do not modify pluralsh/documentation....
🔗 Run history	View run history

[soffi-ai]

Soffi AI Summary

This PR improves the developer and operator experience for the CustomHealth CRD in the deployment operator by documenting the previously undocumented Lua script contract. The CustomHealthSpec.Script field had no description, leaving users to guess how to write a valid health-assessment script. The changes add authoritative GoDoc comments to the Go type definition, which are then propagated via controller-gen into the CRD YAML manifest and regenerated into the Markdown API reference docs.

Key behavioral contract now documented:

• The target Kubernetes resource is exposed to Lua as the global Obj.
• Scripts must assign a Lua table to the global healthStatus (not return { ... }, which is silently ignored).
• The table accepts status and an optional message field.
• Valid status values are Healthy, Degraded, Paused, Unknown, Progressing, Suspended, and Missing, mapping to Console component states (Running, Failed, Paused, Pending).
• A canonical guide URL is embedded: https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator/custom-health

Commits

Commit	Summary
c97b2c1	Added full GoDoc to CustomHealthSpec.Script in customhealth_types.go documenting the Lua contract (global Obj, healthStatus assignment semantics, supported status values, and guide URL), and propagated those descriptions into the generated CRD YAML and Markdown API reference.
c60371c	Refined the documented status values list, simplifying and clarifying the set of supported/intended healthStatus.status names (e.g., trimming or consolidating less-common states) in the GoDoc, CRD YAML, and API reference.

Deploy in Soffi

---

Updated: 2026-08-13 20:00 UTC

[greptile-apps]

Greptile Summary

The PR documents the authoritative CustomHealth Lua script contract and propagates the description into the generated CRD schema and API reference.

• Explains the Obj input global and required healthStatus output global.
• Documents supported health values and their Console component-state mappings.
• Adds the canonical CustomHealth guide link across all three documentation surfaces.

Confidence Score: 5/5

The PR appears safe to merge because it changes documentation only and the documented Lua contract matches the existing evaluator and status-conversion behavior.

The source GoDoc and both generated documentation surfaces are consistent, and the documented globals, output shape, and health-state mappings agree with the implementation.

Important Files Changed

Filename	Overview
go/deployment-operator/api/v1alpha1/customhealth_types.go	Adds accurate GoDoc for the CustomHealth Lua globals, output table, status mappings, and canonical guide.
go/deployment-operator/config/crd/bases/deployments.plural.sh_customhealths.yaml	Propagates the authoritative Script description into the generated CustomHealth CRD schema without changing validation or runtime behavior.
go/deployment-operator/docs/api.md	Regenerates the API reference with content consistent with the source GoDoc and CRD description.

_{Reviews (1): Last reviewed commit: "docs(deployment-operator): clarify custo..." | Re-trigger Greptile}

[michaeljguarino]

don't include the translation results here, the values themselves are pretty self-explanatory.