CRD Versioning Strategy

[lukidoescode]

Motivation

CRDs start at v1alpha1. As the API stabilizes, versions will progress to v1beta1 and v1. Without a versioning strategy planned upfront, upgrading users will face breaking changes with no migration path.

Definition of Done

• A documented CRD versioning strategy is in place:
  • Criteria for graduating from v1alpha1 to v1beta1 (API stability, field coverage, at least one production deployment).
  • Criteria for graduating from v1beta1 to v1 (no breaking changes for N releases).
• The CRD schema generation (Ticket CRD Definitions (LldapUser, LldapGroup, LldapMembership, LldapAttributeSchema) #3) supports multiple stored versions when the time comes (via kube-rs #[kube(storage = "...")] attribute).
• A plan for conversion webhooks is documented: when a new version adds or renames fields, the webhook converts between versions transparently.
• For now (v1alpha1): breaking changes are allowed with a changeset bump. Users must delete and recreate CRDs across breaking changes. This is explicitly documented.
• Documentation: Add a "Versioning and Upgrades" chapter to the mdBook documenting the versioning strategy, what to expect at each stability level, and the upgrade procedure for breaking changes.

Technical Details

• This ticket is primarily documentation and planning — no code changes unless the CRD definitions need structural preparation (e.g., adding #[kube(storage = "v1alpha1")] annotations early).
• Conversion webhooks (when needed) can be served by the operator binary on a /convert endpoint, similar to the validation webhook (Ticket Cross-Field CRD Validation #4).
• Consider using kube::CustomResource with served and storage attributes to manage multi-version CRDs.
• The Helm chart must handle CRD upgrades carefully: CRDs are cluster-scoped and not managed by Helm's release lifecycle. Document the manual CRD upgrade step.