[fabian-schmitt]

Description

This PR implements support for managed network creation in StackitCluster, resolving #9.

Previously, StackitCluster and StackitMachine required a pre-existing STACKIT network ID (.spec.network.id). This PR makes .spec.network.id optional, introducing two operational modes:

1. Managed Mode (omitted spec.network.id):

   • Automatically provisions a dedicated /24 STACKIT network named <cluster-name>-network.
   • Tags the network with canonical Cluster API tags (cluster.x-k8s.io/cluster-name, managed-by, etc.).
   • Stores { id: "<uuid>", managed: true } in status.network.
   • On cluster teardown: Deletes the managed network after machines, load balancers, and bastions are removed. If ports/interfaces are still detaching (409 Conflict), requeues with a NetworkInUse condition and warning event. If status was lost during deletion, falls back to tag-based discovery.

2. Bring-Your-Own (BYO) Mode (provided spec.network.id):

   • Validates that the network exists and records { id: "<uuid>", managed: false } in status.network.
   • Leaves the network untouched on cluster deletion.

Key Changes

• API & CRDs (api/v1alpha1/, config/crd/):

  • Made .spec.network and .spec.network.id optional in StackitCluster, StackitMachine, and their templates.
  • Added Status.Network (StackitNetworkStatus{ id, managed }) to StackitClusterStatus.
  • Updated kubectl printcolumn for Network ID to read from .status.network.id (works for both BYO and managed clusters).
  • Clarified documentation comments on network spec fields.

• Webhook Validation (webhook/v1alpha1/):

  • Allowed empty network IDs on create.
  • Enforced immutability: prevents changing .spec.network.id or switching between managed and BYO after creation.

• Cloud Client & Abstraction (cloud/):

  • Added CreateNetworkInput{ Name, IPv4Prefix, Tags }.
  • Added CreateNetwork, DeleteNetwork, FindNetworkByTags, and ListNetworksByTags to cloud.Client, SDKClient, and cloudfake.Client.
  • Implemented tag-based idempotency in CreateNetwork to avoid duplicate networks across reconcile retries.
  • Updated cloud.CleanupByTags to clean up managed networks in E2E environments.

• Scope & Service Layer (scope/, cloud/services/):

  • Created cloud/services/network/network.go for network input assembly and tag generation.
  • Added MachineScope.NetworkID() and ClusterScope.NetworkID() for encapsulated fallback resolution (Machine Spec -> Cluster Spec -> Cluster Status).
  • Updated API server load balancer and bastion services to accept *scope.ClusterScope and resolve the network ID via clusterScope.NetworkID().

• Reconciliation & Teardown (controller/):

  • Extracted network reconciliation into dedicated helper methods: ensureNetwork, ensureManagedNetwork, and getUnmanagedNetwork.
  • Updated reconcileNormal to ensure network readiness and set ClusterNetworkReadyCondition.
  • Updated reconcileDelete to delete managed networks, handling 409 Conflict requeues gracefully.
  • Updated machine provisioning to use the resolved network ID.

• Tests & Documentation (*_test.go, docs/):

  • Added unit tests for webhook validation, SDK client network creation/deletion, service input generation, scope fallback resolution, and controller reconciliation/deletion.
  • Updated docs/src/getting-started/cloud-resources.md with guidelines on managed network usage and STACKIT CCM configuration.

Testing

• Verified all unit and controller tests pass:

  make test

• Verified code formatting and linter checks pass with zero issues:
  make lint-fix

ToDo or FollowUp:

• Cluster-template changes: Should we now default to empty network?
  Answer: Kept as BYO for now.
  Follow-up issue opened: Cluster templates work out-of-the-box with managed networks (without provided network_id) #37

• LoadBalancer NetworkID:
  @ templates/cluster-template.yaml#L288-294
  How to handle the STACKIT_NETWORK_ID in the cloud.yaml in the generated secret?

Should a controller patch or generate the value after the network is generated?
Answer: Addressed via follow-up issue #37