Merge pull request #72885 from jeana-redhat/OSDOCS-9925-CAPI-assembly

OSDOCS-9925: Create CAPI directory

Author: jeana-redhat

_topic_maps/_topic_map.yml

@@ -2300,8 +2300,6 @@ Topics:
     File: adding-vsphere-compute-user-infra
   - Name: Adding compute machines to bare metal
     File: adding-bare-metal-compute-user-infra
-- Name: Managing machines with the Cluster API
-  File: capi-machine-management
 - Name: Managing control plane machines
   Dir: control_plane_machine_management
   Topics:
@@ -2334,6 +2332,30 @@ Topics:
     File: cpmso-troubleshooting
   - Name: Disabling the control plane machine set
     File: cpmso-disabling
+- Name: Managing machines with the Cluster API
+  Dir: cluster_api_machine_management
+  Topics:
+  - Name: About the Cluster API
+    File: cluster-api-about
+  - Name: Getting started with the Cluster API
+    File: cluster-api-getting-started
+  - Name: Managing machines with the Cluster API
+    File: cluster-api-managing-machines
+  - Name: Cluster API configuration
+    File: cluster-api-configuration
+  - Name: Configuration options for Cluster API machines
+    Dir: cluster_api_provider_configurations
+    Topics:
+    - Name: Cluster API configuration options for Amazon Web Services
+      File: cluster-api-config-options-aws
+    - Name: Cluster API configuration options for Google Cloud Platform
+      File: cluster-api-config-options-gcp
+#  - Name: Cluster API resiliency and recovery
+#    File: cluster-api-resiliency
+  - Name: Troubleshooting Cluster API clusters
+    File: cluster-api-troubleshooting
+#  - Name: Disabling Cluster API machine sets
+#    File: cluster-api-disabling
 - Name: Deploying machine health checks
   File: deploying-machine-health-checks
 ---

machine_management/capi-machine-management.adoc

@@ -0,0 +1 @@
+../../_attributes/

machine_management/cluster_api_machine_management/_attributes

@@ -0,0 +1,45 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-about"]
+= About the Cluster API
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-about
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+The link:https://cluster-api.sigs.k8s.io/[Cluster API] is an upstream project that is integrated into {product-title} as a Technology Preview for Amazon Web Services (AWS) and Google Cloud Platform (GCP).
+
+//Cluster API overview
+include::modules/capi-overview.adoc[leveloffset=+1]
+
+//Cluster API benefits
+include::modules/capi-benefits.adoc[leveloffset=+2]
+
+//Cluster API limitations
+include::modules/capi-limitations.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features-about_nodes-cluster-enabling[Enabling features using feature gates]
+
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc#cluster-api-getting-started[Getting started with the Cluster API]
+
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-cli-reference-intended-objects_cluster-api-troubleshooting[Referencing the intended objects when using the CLI]
+
+[id="cluster-api-architecture_{context}"]
+== Cluster API architecture
+
+The {product-title} integration of the upstream Cluster API is implemented and managed by the Cluster CAPI Operator.
+The Cluster CAPI Operator and its operands are provisioned in the `openshift-cluster-api` namespace, in contrast to the Machine API, which uses the `openshift-machine-api` namespace.
+
+//The Cluster CAPI Operator
+include::modules/capi-arch-operator.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../operators/operator-reference.adoc#cluster-capi-operator_cluster-operators-ref[Cluster CAPI Operator]
+
+//Cluster API primary resources
+include::modules/capi-arch-resources.adoc[leveloffset=+2]

machine_management/cluster_api_machine_management/cluster-api-about.adoc

@@ -0,0 +1,25 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-configuration"]
+= Cluster API configuration
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-configuration
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+The following example YAML files show how to make the Cluster API primary resources work together and configure settings for the machines that they create that are appropriate for your environment.
+
+//Sample YAML for a CAPI cluster resource
+include::modules/capi-yaml-cluster.adoc[leveloffset=+1]
+
+[id="cpmso-sample-yaml-provider-specific_{context}"]
+== Provider-specific configuration options
+
+The remaining Cluster API resources are provider-specific.
+For provider-specific configuration options for your cluster, see the following resources:
+
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#cluster-api-config-options-aws[Cluster API configuration options for {aws-full}]
+
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#cluster-api-config-options-gcp[Cluster API configuration options for {gcp-full}]

machine_management/cluster_api_machine_management/cluster-api-configuration.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-disabling"]
+= Disabling Cluster API machine sets
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-disabling
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+//Placeholder assembly, commented out in the topic map.
+//how to disable, clean up, verify, and reenable

machine_management/cluster_api_machine_management/cluster-api-disabling.adoc

@@ -0,0 +1,49 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-getting-started"]
+= Getting started with the Cluster API
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-getting-started
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+For the Cluster API Technology Preview, you must create the primary resources that the Cluster API requires manually.
+
+[id="creating-primary-resources_{context}"]
+== Creating the Cluster API primary resources
+
+To create the Cluster API primary resources, you must obtain the cluster ID value, which you use for the `<cluster_name>` parameter in the cluster resource manifest.
+
+//Obtaining the cluster ID value
+include::modules/obtaining-value-cluster-id.adoc[leveloffset=+2]
+
+You can create the Cluster API primary resources manually by creating YAML manifest files and applying them with the {oc-first}.
+
+//Creating the Cluster API cluster resource
+include::modules/capi-creating-cluster-resource.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-configuration.adoc#cluster-api-configuration[Cluster API configuration]
+
+//Creating a Cluster API infrastructure resource
+include::modules/capi-creating-infrastructure-resource.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-infrastructure-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API infrastructure resource on {aws-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-infrastructure-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API infrastructure resource on {gcp-full}]
+
+//Creating a Cluster API machine template
+include::modules/capi-creating-machine-template.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-template-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API machine template resource on {aws-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-template-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API machine template resource on {gcp-full}]
+
+//Creating a Cluster API compute machine set
+include::modules/capi-creating-machine-set.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-set-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API compute machine set resource on {aws-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-set-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API compute machine set resource on {gcp-full}]

machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc

@@ -0,0 +1,25 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-managing-machines"]
+= Managing machines with the Cluster API
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-managing-machines
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+//Modifying a Cluster API machine template
+include::modules/capi-modifying-machine-template.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-template-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API machine template resource on {aws-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-template-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API machine template resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-managing-machines.adoc#machineset-modifying_cluster-api-managing-machines[Modifying a compute machine set by using the CLI]
+
+//Modifying a compute machine set by using the CLI
+include::modules/machineset-modifying.adoc[leveloffset=+1,tags=!*;CAPI]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-set-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API compute machine set resource on {aws-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-set-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API compute machine set resource on {gcp-full}]

machine_management/cluster_api_machine_management/cluster-api-managing-machines.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-resiliency"]
+= Cluster API resiliency and recovery
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-resiliency
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+//Placeholder assembly, commented out in the topic map.
+// MAPI would be HA/failure domains, recovery with machine health checks. Not sure about CAPI version

machine_management/cluster_api_machine_management/cluster-api-resiliency.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-troubleshooting"]
+= Troubleshooting clusters that use the Cluster API
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-troubleshooting
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+Use the information in this section to understand and recover from issues you might encounter.
+Generally, troubleshooting steps for problems with the Cluster API are similar to those steps for problems with the Machine API.
+
+The Cluster CAPI Operator and its operands are provisioned in the `openshift-cluster-api` namespace, whereas the Machine API uses the `openshift-machine-api` namespace. When using `oc` commands that reference a namespace, be sure to reference the correct one.
+
+//Returning the intended machines when using the CLI
+include::modules/ts-capi-cli-reference-intended-objects.adoc[leveloffset=+1]