feat: add ExternalAccess API and announce human-readable node names

[scrothers]

Part of the external cluster access effort (umbrella #276). This is the first of four stacked PRs; the rest build on it.

Summary

This adds an optional externalAccess block to ValkeyCluster. It will hold the configuration for reaching a cluster from outside Kubernetes. The field is nil by default, so a cluster that doesn't opt in renders exactly as it does today.

To keep this PR small and easy to review on its own, the only behaviour it wires up is announcing a human-readable node name. With external access enabled, each node gets --cluster-announce-human-nodename set to its ValkeyNode name (for example cluster-sample-1-2). Cluster events like failures then show that name next to the opaque node ID instead of just the ID. It's a small quality-of-life win, and a natural place to introduce the new API.

Features / Behaviour Changes

• New optional spec.externalAccess.enabled on ValkeyCluster.
• When enabled, nodes announce a human-readable node name. Node-to-node traffic is untouched.

Implementation

• Added ExternalAccessSpec to the ValkeyCluster API and mirrored the field onto ValkeyNode. It's copied through buildClusterValkeyNode like the other propagated spec fields.
• buildContainersDef appends --cluster-announce-human-nodename to the server command when external access is enabled. This uses the same argument seam that already sets --cluster-announce-ip.
• cluster-announce-human-nodename is a Valkey 9.0+ directive, which matches the operator's documented baseline.

Limitations

This only lands the API and the node-name announce. The networking pieces (per-shard Services, hostnames, client redirects) come in the follow-up PRs in this stack.

Testing

• Unit tests confirm the node name is announced when enabled, and that a nil or disabled externalAccess leaves the server command unchanged.
• make test and make lint pass locally.
• See docs/valkeycluster.md for the user-facing description.

Checklist

• This Pull Request is related to one issue.
• Commit message explains what changed and why
• Tests are added or updated.
• Documentation files are updated.
• I have run pre-commit locally (ran make test and make lint instead)

[Copilot]

Pull request overview

This PR introduces an initial externalAccess API surface on ValkeyCluster (propagated to ValkeyNode) as the first step in the broader “external cluster access” effort. In this first slice, the only wired behavior is improving cluster observability by announcing a human-readable node name when external access is enabled.

Changes:

• Add optional spec.externalAccess.enabled to ValkeyClusterSpec and mirror/propagate it onto ValkeyNodeSpec.
• When externalAccess.enabled is true, append --cluster-announce-human-nodename <valkeyNodeName> to the server command.
• Add unit tests, docs, CRD schema updates, and a sample manifest for the new API.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/controller/valkeynode_resources.go	Append --cluster-announce-human-nodename to the server command when ExternalAccess.Enabled is set.
internal/controller/valkeynode_resources_test.go	Add tests covering enabled vs disabled/nil ExternalAccess command rendering.
internal/controller/valkeycluster_controller.go	Propagate cluster.Spec.ExternalAccess into the constructed ValkeyNode spec.
api/v1alpha1/valkeycluster_types.go	Define ExternalAccessSpec and add it to ValkeyClusterSpec.
api/v1alpha1/valkeynode_types.go	Mirror ExternalAccess onto ValkeyNodeSpec.
api/v1alpha1/zz_generated.deepcopy.go	Generated deepcopy updates for the new API fields/types.
config/crd/bases/valkey.io_valkeyclusters.yaml	Generated CRD schema update for ValkeyCluster.externalAccess.
config/crd/bases/valkey.io_valkeynodes.yaml	Generated CRD schema update for ValkeyNode.externalAccess.
docs/valkeycluster.md	Document the new externalAccess block and current behavior.
config/samples/v1alpha1_valkeycluster-external-access.yaml	Add a sample ValkeyCluster manifest enabling external access.
config/samples/kustomization.yaml	Include the new sample in the samples kustomization.

Files not reviewed (1)

• api/v1alpha1/zz_generated.deepcopy.go: Generated file

---

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

[greptile-apps]

Greptile Summary

This PR adds the first external access API hook for Valkey clusters. The main changes are:

• Adds optional spec.externalAccess.enabled to ValkeyCluster.
• Propagates external access settings onto generated ValkeyNode resources.
• Appends --cluster-announce-human-nodename when external access is enabled.
• Updates CRDs, docs, samples, generated deepcopy code, and unit tests.

Confidence Score: 5/5

The change appears safe to merge based on the reviewed API, CRD, controller propagation, command generation, docs, samples, and tests.

The implementation is narrowly scoped, preserves default behavior when external access is unset or disabled, and includes targeted coverage for the new command argument behavior.

T-Rex Logs

What T-Rex did

• T-Rex attempted the base external-access test command, but the run failed with exit code 127 due to a missing Go tool.
• T-Rex re-ran the head external-access test command, which also failed with exit code 127 because Go was not available.
• T-Rex added external-access command tests before-test.go and after-test.go to validate the command arrays and propagation when Go would be present.
• T-Rex inspected the baseline CRDs and confirmed they did not contain spec.properties.externalAccess and that the external-access sample was not included.
• T-Rex inspected the updated CRDs and confirmed externalAccess.enabled type boolean is present, externalAccess is optional, there is no default for enabled, and samples/docs reference externalAccess behavior.
• T-Rex re-ran the validation commands after the CRD changes and both commands exited with code 0 while capturing command details, working directory, captions, commits, verbose checks, and exit codes.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "feat: add ExternalAccess API and announc..." | Re-trigger Greptile}