Story (Required)

As an Operator user or developer trying define and managed Operator objects (TetkonConfig, …). I want clear validation, documentation, and tooling support for my resources so I can avoid configuration errors and understand the resource structure easily.

Describes high level purpose and goal for this story. Answers the questions: Who is impacted, what is it and why do we need it? How does it improve the customer’s experience?

This story impacts users and developers working with Operator resources. By adding OpenAPI schema validation to the Repository CRD, we provide explicit structure and constraints. This allows client-side tooling (like kubectl and IDEs) to perform validation and offer better assistance (autocompletion, documentation tooltips). This significantly improves the user experience by catching configuration errors early and making the resource definition clearer and easier to use.

Background (Required)

Describes the context or background related to this story

Kubernetes Custom Resource Definitions (CRDs) support embedding OpenAPI v3 schema validation. This schema serves as a machine-readable contract for the resource structure, enabling client-side validation and tooling support. Currently, the Operator CRDs lacks comprehensive schema validation, which can lead to user errors and a less optimal developer experience when manually creating or editing Repository resources.

Out of scope

Defines what is not included in this story

• Implementing complex validation logic that cannot be expressed purely through OpenAPI schemas (these are typically handled by admission webhooks).

Approach (Required)

Description of the general technical path on how to achieve the goal of the story. Include details like json schema, class definitions
1. Enhance the Go types with `+kubebuilder` markers. These markers define the OpenAPI schema properties such as field types, descriptions, required fields, pattern validations, enum values, minimum/maximum values, and print columns for `kubectl get`.
2. Develop a script (`hack/update-schemas.sh`) that utilizes `controller-gen` to read the `+kubebuilder` markers from the Go types and generate the corresponding OpenAPI schema in YAML format. The script will use `yq` to merge this generated schema into the existing CRD files.
3. Update the `Makefile` to include a new target, `update-schemas`, which executes the schema generation script.
4. Integrate a new job into the CI pipeline . This job will run `make update-schemas` and verify that no changes were made to the CRD file, ensuring that the committed schema is always up-to-date with the Go types.
5. Create comprehensive user documentation explaining the benefits of OpenAPI schema validation, how to leverage it with tools like VS Code and `kubectl`, and how to troubleshoot validation errors.
6. Include `+kubebuilder:printcolumn` markers in the Go types to improve the default output columns when running `kubectl get repository`.

Dependencies

Describes what this story depends on. Dependent Stories and EPICs should be linked to the story.

• External tools: `controller-gen` (used for schema generation), `yq` (used by the generation script to merge schema).
• Go programming language and related Kubernetes libraries.

Acceptance Criteria (Mandatory)

Describe edge cases to consider when implementing the story and defining tests

Provides a required and minimum list of acceptance tests for this story. More is expected as the engineer implements this story

• The Operator's CRD files (`config/300-*.yaml`) contains a well-defined `openAPIV3Schema` under `spec.versions[0].schema`.
• The schema definition includes accurate types, descriptions, required fields, and validation rules (patterns, enums, minimums).
• Running `make update-schemas` successfully regenerates or updates the `openAPIV3Schema` section in the CRD file based on the Go types without manual intervention.
• A CI job successfully verifies that the committed CRD schema is synchronized with the schema generated from the Go types.
• Applying a Repository resource with invalid fields (e.g., wrong type, missing required field, invalid pattern) using `kubectl apply --validate=strict` results in a validation error reported by the Kubernetes API server.
• IDEs configured with Kubernetes/YAML extensions provide accurate autocompletion, hover documentation (field descriptions), and real-time validation for resources based on the schema.
• The new documentation page in the guide is clear, technically accurate, and provides useful information on utilizing schema validation.
• Running `kubectl get …` displays the additional status columns (URL, Succeeded, Reason, StartTime, CompletionTime) defined in the `+kubebuilder:printcolumn` markers.

INVEST Checklist

Dependencies identified - Verified

Blockers noted and expected delivery timelines set - Verified (Completed work)

Design is implementable - Verified (Completed work)