Umbrella issue: API changes

[sbueringer]

Goal of this issue is to provide an overview over issues related to API changes.

Important

• Tracking issue for v1Beta2 #11947
• Audit Machine-level fields across CC, Cluster.spec.topology, MD, MS, KCP and check if we can make it more consistent
• Consider to stop embedding Machine struct directly in MD/MS (e.g. fields like providerID don't belong there)
• API field best practices
  • @sbueringer Make all replica counter status fields pointers + omitempty (like the new v1beta2 replica counter fields)
  • optionalfields: New Linter: optionalfields kube-api-linter#21
    • Ensure all optional fields that are structs are pointers
    • Most of our *string fields should just be string
    • Cluster's spec.ControlPlaneEndpoint is marked optional but not a pointer type #6416 [waiting for v1beta2]
      • @sbueringer Also check usages of APIEndpoint and take a look at Change the controlPlaneEndpoint during kubernetes cluster running #5005
  • nomaps: 🌱 Add nomaps API linter #12083
  • ssatags: New Linter: ssatags kube-api-linter#32 (decide case by case because of edge cases with schema transitions)
  • statusoptional: all direct children within status should be optional: New Linter: statusoptional kube-api-linter#31
  • nodurations: Remove Duration types: New Linter: nodurations kube-api-linter#24
  • Try to remove KAL exception for v1beta2

ClusterClass & Cluster.spec.topology:

• v1beta2: Class Namespace API change #11500
• Deprecate definitionFrom in cluster variables #10666 [deprecated] [will be removed in v1beta2]
• Enable lifecycle hooks explicitly in the ClusterClass #8211 [not planned]
• Simplify external patch definition in ClusterClass #8210 [not planned] [Stefan: we should look into at least cleaning up the field names]
• Remove IP Family from API types and cluster class builtin variables #7521 [deprecated] [will be removed in v1beta2]
• Provide explicit definition of variables scope in ClusterClass #6706 [not planned]
• Consider making .spec.controlPlane mandatory
• Introduce InfrastructureClass (context in Add namingStrategy for InfrastructureCluster #11671 (comment))

Cluster:

• Add strict validation for CIDR ranges in the Cluster webhook #7538 [waiting for v1beta2]

MachineDeployment:

• Remove spec.ProgressDeadlineSeconds in MachineDeployments #11470 [deprecated] [will be removed in v1beta2]
• Remove revision management in MachineDeployments #10479 [deprecated] [will be removed in v1beta2]
• Paused behaviour is inconsistent  #6966
• Configurable machine replacement #10946 (potentially we want to redesign our rollout* fields)

MachineSet

Machine:

• Allow user to opt-in to Node draining during Cluster delete #9692 [not planned]
• Improve API around machine deletion strategy #7021
• Check how bootstrap.ref/datasecret are modelled: BootstrapConfig should be optional for MachinePool based ClusterClass #10943 (comment) & check in all the places where we use MachineSpec (MD/MS/MP/...)

KubeadmControlPlane:

• Remove ClusterConfiguration.KubernetesVersion field

KubeadmConfig / KubeadmConfigTemplate / KubeadmControlPlane / KubeadmControlPlaneTemplate:

• Remove experimentalRetryJoin #6942 [deprecated] [will be removed in v1beta2]
• Make KubeadmConfig and the KubeadmConfigTemplate immutable #4910 [not planned]
• Implement support for kubeadm v1beta4 API #10708 (see "Changes deferred to when we implement CAPI v1beta2 types")
• Consider changing Networking.ServiceSubnet and Networking.PodSubnet to a list: ⚠️ Add MaxLength & MinLength markers #11949 (comment)
• Consider changing Filesystem.Partition to IntOrString: ⚠️ Add MaxLength & MinLength markers #11949 (comment)

MachinePool:

• MachinePools cannot be upgraded atomically when used with managed providers #7248 [not planned] [TBD if blocker for MP graduation]

MachineHealthCheck:

• Deprecate MachineHealthCheck MaxUnhealthy and UnhealthyRange #10722 [deprecated] [will be removed in v1beta2]
• Improve UX of MachineHealthCheckStatus fields #5291 [not planned]
• Rename conditions to nodeConditions?

ClusterResourceSet:

• When the clusterresourcesetbinding is v1beta2, set the clusterName field to be required. #8267 [waiting for v1beta2]

clusterctl:

• Deprecate & remove "clusterctl alpha topology plan" #10138 [deprecated] [will be removed in v1.9]

Finalizers:

• Our finalizers are not domain-qualified, and therefore do not conform to requirements #10914

Status fields & conditions:

• @fabriziopandini (📖 Proposal: Improving status in CAPI resources #10897)
  • Consider aligning Cluster API conditions to upstream conditions #7635
  • Deprecate KCP.Available condition #10532
  • Improve status.Ready Fields in the contract #10707
  • Mismatch between ControlPlaneReady and Conditions.ControlPlaneReady #7099
  • Add MachineNodeHealthyCondition to Machine’s Ready condition #3974
  • Add conditions to MachineDeployment Object #3486
  • Machine failures not propagated up to MachineDeployment.Status #5635
  • Consistent reporting of paused resources #10130
  • The ready condition of MachineDeployment doesn't change when a Machine CR is deleted #7461
  • out of scope for the first iteration of the proposal, but the same principles will apply
    • Make it easier to understand if a ClusterClass is ready #8137
• MachinePool observedGeneration is updated without changing conditions on upgrades #10059
• How to surfacing runtime hook blocking cluster deletion in condition #6807
• MachineSet should reset MachineReady conditions when scaled down to zero replicas #5453
• Add more descriptive Message to DrainingFailedReason and DrainingReason #10056
• Feedback: 🌱 Add BootstrapFailedMachineError error #10360

CRD Columns: (can be already done today)

• @fabriziopandini (📖 Proposal: Improving status in CAPI resources #10897)
  • Ensure consistency across replica-based CLI printer columns #6238
  • Rename 'replicas' to 'current' in KubeadmControlPlane, MachineDeployments and MachineSet kubectl output #6227
  • API conventions: CRD columns: status vs intent #5332
  • out of scope for the first iteration of the proposal, but the same principles will apply
    • Add more print columns to ClusterResourceSet/Bindings for better tracking #9007

Smaller improvements: (can be already done today)

• Current v1beta1 API Types do not define list-type annotation #6504
• Add OpenAPI required tag for all required types #6397

Bigger changes:

• prepare replacing corev1.ObjectReference in v1beta2 #6539

Backlog: (require some design/proposal)

• Cleaner separation of kubeadm and machine bootstrapping #5294
• Inconsistent provider behaviour with API server ports #5517

Explanations:

• [waiting for v1beta2]: There is absolutely nothing we can do today, we are just waiting for v1beta2

[sbueringer]

/triage accepted

[sbueringer]

I have 3 PRs open for deprecations for v1.8:

• Deprecate definitionFrom ⚠️ Adjust CC & Cluster controller to block on variable conflicts, deprecate definitionFrom #10841
• Deprecate MHC: 🌱 Deprecate MHC MaxUnhealthy & UnhealthyRange fields #10853
• Deprecate MD revision management: 🌱 Deprecate MachineDeployment revision management #10855

[sbueringer]

Added all condition issues I could find to the list above. I think there is a huge overlap with #10897 (i.e. most of these issues would be solved if the proposal is implemented). We should check if there are gaps/conflicts