Merge pull request #3111 from larainema/docs/clarify-providerid-initialization

📖 Clarify providerID initialization approaches in documentation

Author: k8s-ci-robot

docs/book/src/topics/external-cloud-provider.md

@@ -3,6 +3,9 @@
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
 - [External Cloud Provider](#external-cloud-provider)
+  - [Setting the providerID on nodes](#setting-the-providerid-on-nodes)
+    - [Option 1: Bootstrap-driven initialization (recommended)](#option-1-bootstrap-driven-initialization-recommended)
+    - [Option 2: OCCM-driven initialization](#option-2-occm-driven-initialization)
   - [Steps of using external cloud provider template](#steps-of-using-external-cloud-provider-template)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -12,6 +15,69 @@
 All [cluster templates](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/templates) are meant to be used with the external cloud provider for OpenStack.
 Refer to the [external cloud provider repository](https://github.com/kubernetes/cloud-provider-openstack) or the [helm chart](https://github.com/kubernetes/cloud-provider-openstack/tree/master/charts/openstack-cloud-controller-manager) for more details.
 
+## Setting the providerID on nodes
+
+Kubernetes nodes need a `spec.providerID` for Cluster API to match nodes to
+machines. There are two supported approaches for setting it. Both are fully
+supported by CAPO.
+
+### Option 1: Bootstrap-driven initialization (recommended)
+
+Set `provider-id` directly via kubelet arguments during node bootstrap using
+OpenStack instance metadata exposed through cloud-init. This is what all
+default CAPO [cluster templates](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/templates) use and what is tested in CI.
+
+```yaml
+apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
+kind: KubeadmConfigTemplate
+spec:
+  template:
+    spec:
+      joinConfiguration:
+        nodeRegistration:
+          name: '{{ local_hostname }}'
+          kubeletExtraArgs:
+          - name: cloud-provider
+            value: external
+          - name: provider-id
+            value: openstack:///'{{ instance_id }}'
+```
+
+With this approach:
+
+- Nodes register with `providerID` already set.
+- Machine reconciliation completes without waiting for an external controller.
+- OCCM can still be deployed later if cloud features (e.g. LoadBalancer
+  services, node address management) are needed.
+
+### Option 2: OCCM-driven initialization
+
+Deploy the [OpenStack Cloud Controller Manager](https://github.com/kubernetes/cloud-provider-openstack) (OCCM) after the
+control plane is ready. OCCM populates `Node.spec.providerID` for all nodes.
+
+```yaml
+apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
+kind: KubeadmConfigTemplate
+spec:
+  template:
+    spec:
+      joinConfiguration:
+        nodeRegistration:
+          name: '{{ local_hostname }}'
+          kubeletExtraArgs:
+          - name: cloud-provider
+            value: external
+```
+
+With this approach:
+
+- Nodes register without `providerID`.
+- Machine reconciliation waits until OCCM sets the `providerID`.
+- OCCM must be deployed for the cluster to fully reconcile.
+
+See [Steps of using external cloud provider template](#steps-of-using-external-cloud-provider-template) below for OCCM
+deployment instructions.
+
 ## Steps of using external cloud provider template
 
 - After control plane is up and running, retrieve the workload cluster Kubeconfig: