butane: stabilize OpenShift spec 5.0.0 #2333

Summary

Stabilize the Butane openshift configuration specification for OCP 5.0.

Butane now lives under butane/ in the Ignition repository and is built and shipped with Ignition. This tracks the OpenShift-specific stabilization; it does not require stabilizing a new Ignition specification.

OCP 5.0 is the immediate target. OCP 4.23 stabilization will be handled separately after 5.0, with the expectation of reusing the same underlying implementation where compatible. Preserve the existing 4.23.0-experimental spec for now.

Ignition compatibility

Select the output Ignition spec based on what OCP 5.0's Machine Config Operator actually supports, not merely the Ignition library it vendors.

The inspected MCO release-5.0 revision still uses config/v3_5 and v3_5.ParseCompatibleVersion, making Ignition 3.5.0 the current target:
https://github.com/openshift/machine-config-operator/blob/cafc37a760319b235d5301e3790f83e2de9d78f7/pkg/controller/common/helpers.go#L32-L33

Reconfirm this against the target release before shipping. Review #2279 for unsupported features, including GRUB configuration and special file-mode bits.

Checklist

Spec implementation

• Confirm the Ignition spec and feature support in OCP 5.0's MCO.
• Add butane/config/openshift/v5_0, using the existing 3.5-compatible stable implementation as the baseline.
• Update package names, imports, translation methods, and tests.
• Register openshift version 5.0.0 in butane/config/config.go.
• Retain the required MCO restrictions documented in OpenShift stabilisation tracker for (missing) support in the MCO #2279.
• Preserve existing stable specs and 4.23.0-experimental.
• Decide whether to introduce 5.1.0-experimental in this change or track it separately.

Documentation

• Register the new spec in butane/internal/doc/main.go.
• Update butane/internal/doc/butane.yaml for the supported feature set without changing the retained 4.23 experimental documentation.
• Run ./generate from the butane/ directory.
• Update butane/docs/specs.md, including the Ignition version mapping.
• Document migration to 5.0.0 in butane/docs/upgrading-openshift.md.
• Note stabilization in the root docs/release-notes.md.

Validation

• Test version dispatch, MachineConfig output, and raw Ignition output.
• Test required metadata and unsupported-feature handling.
• Verify existing OpenShift specs retain their behavior.
• Run go test ./butane/..., root ./test, and ./build butane.
• Verify generated documentation is reproducible.
• Validate generated configs with the target OCP 5.0 MCO.

References

• Previous checklist: New stabilization for Butane: openshift-4.22 butane#702
• Previous stabilization: OCP 4.22 stabilization butane#704
• MCO compatibility tracker: OpenShift stabilisation tracker for (missing) support in the MCO #2279
• Previous Ignition version mismatch: openshift 4.22.0 spec targets Ignition 3.6.0, which the OCP 4.22 MCO does not support butane#715