Motivation
The Gen2-to-Gen3 migration path has no authoritative framework contract for immutable selectors and legacy resource discovery. Operators that retain a legacy selector must also preserve matching pod labels and coordinate Service/PDB selectors. Framework health and orphan scans currently key on framework-managed labels, so legacy-labelled resources can escape those checks.
Downstream evidence
zncdatadev/airflow-operator, branch refactor/operator-go-v0.13: it preserves the immutable Gen2 StatefulSet selector and documents the health-scan limitation in docs/operator-go-v0.13-migration.md.zncdatadev/superset-operator: its migration guard takes the opposite safe choice and blocks migration until legacy StatefulSets are removed.
Proposed documentation
Document the Gen2-to-Gen3 migration contract in operator-go: canonical-name changes at the 54-character boundary, immutable selector preservation, required alignment of pod/Service/PDB selectors, legacy discovery limitations, and the trade-off between zero-downtime compatibility shims and an explicit stop-and-recreate migration.
Migration impact
This is a documentation/design contract rather than automatic legacy-resource adoption. It should make future operator migrations choose and test a strategy deliberately, without expanding the framework into product-specific guessing.
Motivation
The Gen2-to-Gen3 migration path has no authoritative framework contract for immutable selectors and legacy resource discovery. Operators that retain a legacy selector must also preserve matching pod labels and coordinate Service/PDB selectors. Framework health and orphan scans currently key on framework-managed labels, so legacy-labelled resources can escape those checks.
Downstream evidence
zncdatadev/airflow-operator, branchrefactor/operator-go-v0.13: it preserves the immutable Gen2 StatefulSet selector and documents the health-scan limitation indocs/operator-go-v0.13-migration.md.zncdatadev/superset-operator: its migration guard takes the opposite safe choice and blocks migration until legacy StatefulSets are removed.Proposed documentation
Document the Gen2-to-Gen3 migration contract in operator-go: canonical-name changes at the 54-character boundary, immutable selector preservation, required alignment of pod/Service/PDB selectors, legacy discovery limitations, and the trade-off between zero-downtime compatibility shims and an explicit stop-and-recreate migration.
Migration impact
This is a documentation/design contract rather than automatic legacy-resource adoption. It should make future operator migrations choose and test a strategy deliberately, without expanding the framework into product-specific guessing.