Merge pull request #52520 from maxwelldb/shiftstack-external-ccm-osdocs3502

[OSDOCS-3502] Shiftstack external CCM GA

Author: maxwelldb

_topic_maps/_topic_map.yml

@@ -396,6 +396,8 @@ Topics:
     File: installing-openstack-user-kuryr
   - Name: Installing a cluster on OpenStack in a restricted network
     File: installing-openstack-installer-restricted
+  - Name: OpenStack Cloud Controller Manager reference guide
+    File: installing-openstack-cloud-config-reference
   # - Name: Load balancing deployments on OpenStack
   #   File: installing-openstack-load-balancing
   - Name: Uninstalling a cluster on OpenStack

installing/installing_openstack/installing-openstack-cloud-config-reference.adoc

@@ -0,0 +1,9 @@
+:_content-type: ASSEMBLY
+[id="installing-openstack-cloud-config-reference"]
+= OpenStack Cloud Controller Manager reference guide
+include::_attributes/common-attributes.adoc[]
+:context: installing-openstack-cloud-config-reference
+
+toc::[]
+
+include::modules/nw-openstack-external-ccm.adoc[leveloffset=+1]

modules/nw-openstack-external-ccm.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-cloud-config-reference.adoc
+// TODO: GitHub link clearance.
+
+:_content-type: CONCEPT
+[id="nw-openstack-external-ccm_{context}"]
+= The OpenStack Cloud Controller Manager
+
+In {product-title} 4.12, clusters that run on {rh-openstack-first} are switched from the legacy OpenStack cloud provider to the external OpenStack Cloud Controller Manager (CCM). This change follows the move in Kubernetes from in-tree, legacy cloud providers to external cloud providers that are implemented by using the link:https://kubernetes.io/docs/concepts/architecture/cloud-controller/[Cloud Controller Manager].
+
+To preserve user-defined configurations for the legacy cloud provider, existing configurations are mapped to new ones as part of the migration process. It searches for a configuration called `cloud-provider-config` in the `openshift-config` namespace.
+
+NOTE: The config map name `cloud-provider-config` is not statically configured. It is derived from the `spec.cloudConfig.name` value in the `infrastructure/cluster` CRD.
+
+Found configurations are synchronized to the `cloud-conf` config map in the `openshift-cloud-controller-manager` namespace.
+
+// To synchronize the configuration to a different namespace, you can override the default `openshift-cloud-controller-manager` namespace by passing the name of the namespace with the `--namespace` flag to the operator binary.
+
+As part of this synchronization, the OpenStack CCM Operator alters the new config map such that its properties are compatible with the external cloud provider. The file is changed in the following ways:
+
+* The `[Global] secret-name`, `[Global] secret-namespace`, and `[Global] kubeconfig-path` options are removed. They do not apply to the external cloud provider.
+
+* The `[Global] use-clouds`, `[Global] clouds-file`, and `[Global] cloud` options are added.
+
+* The entire `[BlockStorage]` section is removed. External cloud providers no longer perform storage operations. Block storage configuration is managed by the Cinder CSI driver.
+
+Additionally, the CCM Operator enforces a number of default options. Values for these options are always overriden as follows:
+
+[source,txt]
+----
+[Global]
+use-clouds = true
+clouds-file = /etc/openstack/secret/clouds.yaml
+cloud = openstack
+...
+
+[LoadBalancer]
+use-octavia = true
+enabled = true <1>
+----
+<1> If the network is configured to use Kuryr, this value is `false`.
+
+The `clouds-value` value, `/etc/openstack/secret/clouds.yaml`, is mapped to the `openstack-cloud-credentials` config in the `openshift-cloud-controller-manager` namespace. You can modify the {rh-openstack} cloud in this file as you do any other `clouds.yaml` file.