✨ Introduce v1alpha3 API

[Fedosin]

What this PR does / why we need it:

Introduce v1alpha3 API with Simplified Provider Configuration

Motivation

The v1alpha2 API introduced a ManagerSpec type that abstracted manager configuration (metrics, health probes, leader election, etc.) into a separate structure. While well-intentioned, this approach created unnecessary complexity and reduced flexibility when users needed to configure provider-specific flags. This change simplifies the API by consolidating all provider configuration directly into ContainerSpec.Args, making the API more transparent and easier to understand.

Key Changes

1. Removed ManagerSpec and Related Types

The following types have been removed:

• ManagerSpec - All fields converted to container args
• ControllerManagerConfiguration - Configuration now in args
• ControllerConfigurationSpec - Controller settings now in args
• ControllerMetrics, ControllerHealth, ControllerWebhook - All configuration now in args

2. Simplified AdditionalDeployments

• v1alpha2: map[string]AdditionalDeployments (wrapper struct with Manager + Deployment fields)
• v1alpha3: map[string]DeploymentSpec (direct deployment specifications)

Note: During conversion, ManagerSpec fields in additionalDeployments are not converted to args, as additional deployments are not Cluster API providers.

3. Direct Container Args Configuration

All manager configuration is now specified directly as container arguments:

# v1alpha3
spec:
  deployment:
    containers:
    - name: ""  # Empty name for converted specs
      args:
        "--max-concurrent-reconciles": "10"
        "--v": "2"
        "--feature-gates": "featureA=true"

Instead of the previous structure:

# v1alpha2
spec:
  manager:
    maxConcurrentReconciles: 10
    verbosity: 2
    featureGates:
      FeatureA: true

4. Automatic Conversion

• Bidirectional conversion between v1alpha2 ↔ v1alpha3 is implemented
• v1alpha3 is the new hub and storage version
• Round-trip conversion preserves settings (with noted exception for additionalDeployments manager config)

Benefits

1. Simplicity: Single location for all provider configuration
2. Flexibility: Easy to add custom provider-specific flags without API changes
3. Transparency: Direct mapping to actual container arguments
4. Compatibility: Automatic conversion maintains backward compatibility

Migration

Users can continue using v1alpha2 resources - they will be automatically converted to v1alpha3 internally. A comprehensive migration guide is included in the documentation.

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #

[netlify]

✅ Deploy Preview for kubernetes-sigs-cluster-api-operator ready!

Name	Link
🔨 Latest commit	af9d074
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-sigs-cluster-api-operator/deploys/68e8d6663965280009f878ec
😎 Deploy Preview	https://deploy-preview-897--kubernetes-sigs-cluster-api-operator.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign fedosin for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Fedosin]

/test pull-cluster-api-operator-e2e-main

[k8s-ci-robot]

@Fedosin: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-cluster-api-operator-apidiff-main	af9d074	link	false	/test pull-cluster-api-operator-apidiff-main

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.