Docs: CRD Upgrade Safety

[everettraven]

User story

Describe the user story or stories for this epic:

• As a user, I expect updates to a CRD to be rejected (install/upgrade fails) when:
  • the scope changes from Cluster --> Namespace or Namespace --> Cluster
  • an existing stored version is removed
  • a new required field is added to an existing version
  • an existing field is removed from an existing version
  • an existing field type is changed in an existing version
  • a valid enum value is removed for a field in an existing version
• As a user, I expect updates to a CRD to be accepted (install/upgrade succeeds) when:
  • An enum value is added for a field in an existing version
  • An existing required field is updated to be optional in an existing version
  • The minimum value of an existing field is decreased in an existing version
  • The maximum value of an existing field is increased in an existing version
  • A new version of the CRD is added with no modifications to existing versions
• As a user I should be able to disable the CRD Upgrade Safety validations for a particular ClusterExtension

List the user-facing issues in the epic that require documentation.

• Add configuration to the ClusterExtension API for disabling CRD Upgrade Safety validations #745
• Implement generic, extensible pre-flight check functionality based on the new Helm direction #741
• Could probably be grouped into a singular section:
  • Add a check for existing version that is a stored version being removed #662
  • Add a check for new required field #663
  • Add a check for removing an existing field #664
  • Add a check for scope change (Namespace <--> Cluster) #665
  • Add a check for handling updates to existing fields to increase the maximums #714
  • Add a check for ensuring that existing required fields can be marked as optional #715
  • Add a check for ensuring that more enum values can be added for an existing field #716
  • Add a check for handling updates to existing fields to decrease the minimums #713

Does this epic require new content or updates to existing content?

• Net-new content
• Update existing content

What type of documentation is required for this epic?

• Release note
• Concept
• Procedure
• Reference

Is there prior art or reference materials that would help write the documentation?

• Once the feature is complete and in place, there will likely be some unit and e2e tests that could be used as reference for how CRDs with allowed and disallowed changes look

Documentation should be contributed to the docs/drafts/ directory

[trgeiger]

/assign