Merge pull request #80904 from lahinson/osdocs-11001-hcp-bm

[OSDOCS-11001]: Moving HCP bare metal content to OCP repo

Author: lahinson

_topic_maps/_topic_map.yml

@@ -2460,6 +2460,8 @@ Topics:
     File: hcp-destroy-virt
   - Name: Destroying a hosted cluster on IBM Z
     File: hcp-destroy-ibmz
+- Name: Manually importing a hosted control plane cluster
+  File: hcp-import
 ---
 Name: Nodes
 Dir: nodes

hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc

@@ -5,3 +5,72 @@ include::_attributes/common-attributes.adoc[]
 :context: hcp-deploy-bm
 
 toc::[]
+
+You can deploy {hcp} by configuring a cluster to function as a management cluster. The management cluster is the {product-title} cluster where the control planes are hosted. In some contexts, the management cluster is also known as the _hosting_ cluster.
+
+[NOTE]
+====
+The management cluster is not the same thing as the _managed_ cluster. A managed cluster is a cluster that the hub cluster manages.
+====
+
+The {hcp} feature is enabled by default.
+
+The {mce-short} supports only the default `local-cluster`, which is a hub cluster that is managed, and the hub cluster as the management cluster. If you have Red{nbsp}Hat Advanced Cluster Management installed, you can use the managed hub cluster, also known as the `local-cluster`, as the management cluster.
+
+A _hosted cluster_ is an {product-title} cluster with its API endpoint and control plane that are hosted on the management cluster. The hosted cluster includes the control plane and its corresponding data plane. You can use the {mce-short} console or the hosted control plane command line interface, `hcp`, to create a hosted cluster. 
+
+The hosted cluster is automatically imported as a managed cluster. If you want to disable this automatic import feature, see _Disabling the automatic import of hosted clusters into {mce-short}_.
+
+include::modules/hcp-bm-prepare.adoc[leveloffset=+1]
+include::modules/hcp-bm-prereqs.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html/clusters/cluster_mce_overview#advanced-config-engine[Advanced configuration]
+
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html/clusters/cluster_mce_overview#enable-cim[Enabling the central infrastructure management service]
+
+include::modules/hcp-bm-firewall-port-svc-reqs.adoc[leveloffset=+2]
+include::modules/hcp-bm-infra-reqs.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../scalability_and_performance/recommended-performance-scale-practices/recommended-etcd-practices.adoc#recommended-etcd-practices[Recommended etcd practices]
+
+* xref:../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc[Persistent storage using LVM Storage]
+
+* xref:../../hosted_control_planes/hcp-import.adoc#hcp-import-disable_hcp-import[Disabling the automatic import of hosted clusters into {mce-short}]
+
+* xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.adoc[Enabling or disabling the {hcp} feature]
+
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html/clusters/cluster_mce_overview#ansible-config-hosted-cluster[Configuring Ansible Automation Platform jobs to run on hosted clusters]
+
+include::modules/hcp-bm-dns.adoc[leveloffset=+1]
+include::modules/hcp-bm-hc.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../hosted_control_planes/hcp-import.adoc[Manually importing a hosted control plane cluster]
+
+include::modules/hcp-bm-hc-console.adoc[leveloffset=+2]
+
+.Next steps
+
+* To access the web console, see xref:../../web_console/web-console.adoc#web-console-overview[Accessing the web console].
+
+include::modules/hcp-bm-hc-mirror.adoc[leveloffset=+2]
+
+.Next steps
+
+* To create credentials that you can reuse when you create a hosted cluster with the console, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html/clusters/cluster_mce_overview#creating-a-credential-for-an-on-premises-environment[Creating a credential for an on-premises environment].
+
+* To access a hosted cluster, see xref:../../hosted_control_planes/hcp-manage/hcp-manage-bm.adoc#hcp-bm-access_hcp-manage-bm[Accessing the hosted cluster].
+
+* To add hosts to the host inventory by using the Discovery Image, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html/clusters/cluster_mce_overview#add-host-host-inventory[Adding hosts to the host inventory by using the Discovery Image].
+
+* To extract the {product-title} release image digest, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html/clusters/cluster_mce_overview#configure-hosted-disconnected-digest-image[Extracting the {product-title} release image digest].
+
+include::modules/hcp-bm-verify.adoc[leveloffset=+1]

hosted_control_planes/hcp-import.adoc

@@ -0,0 +1,14 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="hcp-import"]
+include::_attributes/common-attributes.adoc[]
+= Manually importing a hosted control plane cluster
+:context: hcp-import
+
+toc::[]
+
+Hosted clusters are automatically imported into {mce-short} after the hosted control plane becomes available.
+
+include::modules/hcp-import-manual.adoc[leveloffset=+1]
+include::modules/hcp-import-manual-aws.adoc[leveloffset=+1]
+include::modules/hcp-import-disable.adoc[leveloffset=+1]
+

hosted_control_planes/hcp-manage/hcp-manage-bm.adoc

@@ -5,3 +5,31 @@ include::_attributes/common-attributes.adoc[]
 :context: hcp-manage-bm
 
 toc::[]
+
+After you deploy {hcp} on bare metal, you can manage a hosted cluster by completing the following tasks.
+
+include::modules/hcp-bm-access.adoc[leveloffset=+1]
+include::modules/hcp-bm-scale-np.adoc[leveloffset=+1]
+include::modules/hcp-bm-add-np.adoc[leveloffset=+2]
+include::modules/hcp-bm-autoscale.adoc[leveloffset=+2]
+include::modules/hcp-bm-autoscale-disable.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../hosted_control_planes/hcp-troubleshooting.adoc#scale-down-data-plane_hcp-troubleshooting[Scaling down the data plane to zero]
+
+include::modules/hcp-bm-ingress.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../networking/metallb/about-metallb.adoc#about-metallb[About MetalLB and the MetalLB Operator]
+
+include::modules/hcp-bm-machine-health.adoc[leveloffset=+1]
+include::modules/hcp-bm-machine-health-disable.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../machine_management/deploying-machine-health-checks.adoc#deploying-machine-health-checks[Deploying machine health checks]

modules/hcp-bm-access.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-manage/hcp-manage-bm.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-bm-access_{context}"]
+= Accessing the hosted cluster
+
+You can access the hosted cluster by either getting the `kubeconfig` file and `kubeadmin` credential directly from resources, or by using the `hcp` command line interface to generate a `kubeconfig` file.
+
+.Prerequisites
+
+To access the hosted cluster by getting the `kubeconfig` file and credentials directly from resources, you need to be familiar with the access secrets for hosted control plane clusters. The secrets are stored in the hosted cluster (hosting) namespace. The _hosted cluster (hosting)_ namespace contains hosted cluster resources, and the _hosted control plane_ namespace is where the hosted control plane runs.
+
+The secret name formats are as follows:
+
+** `kubeconfig` secret: `<hosted-cluster-namespace>-<name>-admin-kubeconfig` (clusters-hypershift-demo-admin-kubeconfig)
+** `kubeadmin` password secret: `<hosted-cluster-namespace>-<name>-kubeadmin-password` (clusters-hypershift-demo-kubeadmin-password)
+
+The `kubeconfig` secret contains a Base64-encoded `kubeconfig` field, which you can decode and save into a file to use with the following command:
+
+[source,terminal]
+----
+$ oc --kubeconfig <hosted-cluster-name>.kubeconfig get nodes
+----
+
+The `kubeadmin` password secret is also Base64-encoded. You can decode it and use the password to log in to the API server or console of the hosted cluster.
+
+.Procedure
+
+* To access the hosted cluster by using the `hcp` CLI to generate the `kubeconfig` file, take the following steps:
+
+. Generate the `kubeconfig` file by entering the following command:
++
+[source,terminal]
+----
+$ hcp create kubeconfig --namespace <hosted-cluster-namespace> --name <hosted-cluster-name> > <hosted-cluster-name>.kubeconfig
+----
+
+. After you save the `kubeconfig` file, you can access the hosted cluster by entering the following example command:
++
+[source,terminal]
+----
+$ oc --kubeconfig <hosted-cluster-name>.kubeconfig get nodes
+----

modules/hcp-bm-add-np.adoc

@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-manage/hcp-manage-bm.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-bm-add-np_{context}"]
+= Adding node pools
+
+You can create node pools for a hosted cluster by specifying a name, number of replicas, and any additional information, such as an agent label selector.
+
+.Procedure
+
+. To create a node pool, enter the following information:
++
+[source,terminal]
+----
+export NODEPOOL_NAME=${CLUSTER_NAME}-extra-cpu
+export WORKER_COUNT="2"
+
+$ hcp create nodepool agent \
+  --cluster-name $CLUSTER_NAME \
+  --name $NODEPOOL_NAME \
+  --node-count $WORKER_COUNT \
+  --agentLabelSelector '{"matchLabels": {"size": "medium"}}' <1>
+----
++
+<1> The `--agentLabelSelector` is optional. The node pool uses agents with the `"size" : "medium"` label.
+
+. Check the status of the node pool by listing `nodepool` resources in the `clusters` namespace:
++
+[source,terminal]
+----
+$oc get nodepools --namespace clusters
+----
+
+. Extract the `admin-kubeconfig` secret by entering the following command:
++
+[source,terminal]
+----
+$ oc extract -n <hosted-control-plane-namespace> secret/admin-kubeconfig --to=./hostedcluster-secrets --confirm
+----
++
+.Example output
+[source,terminal]
+----
+hostedcluster-secrets/kubeconfig
+----
+
+. After some time, you can check the status of the node pool by entering the following command:
++
+[source,terminal]
+----
+$ oc --kubeconfig ./hostedcluster-secrets get nodes
+----
+
+. Verify that the number of available node pools match the number of expected node pools by entering this command:
++
+[source,terminal]
+----
+$ oc get nodepools --namespace clusters
+----

modules/hcp-bm-autoscale-disable.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-manage/hcp-manage-bm.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-bm-autoscale-disable_{context}"]
+= Disabling node auto-scaling for the hosted cluster
+
+To disable node auto-scaling, complete the following procedure.
+
+.Procedure
+
+* Enter the following command:
++
+[source,terminal]
+----
+$ oc -n <hosted-cluster-namespace> patch nodepool <hosted-cluster-name> --type=json -p '[\{"op":"remove", "path": "/spec/autoScaling"}, \{"op": "add", "path": "/spec/replicas", "value": <specify-value-to-scale-replicas>]'
+----
++
+The command removes `"spec.autoScaling"` from the YAML file, adds `"spec.replicas"`, and sets `"spec.replicas"` to the integer value that you specify.

modules/hcp-bm-autoscale.adoc

@@ -0,0 +1,100 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-manage/hcp-manage-bm.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-bm-autoscale_{context}"]
+= Enabling node auto-scaling for the hosted cluster
+
+When you need more capacity in your hosted cluster and spare agents are available, you can enable auto-scaling to install new worker nodes.
+
+.Procedure
+
+. To enable auto-scaling, enter the following command:
++
+[source,terminal]
+----
+$ oc -n <hosted-cluster-namespace> patch nodepool <hosted-cluster-name> --type=json -p '[{"op": "remove", "path": "/spec/replicas"},{"op":"add", "path": "/spec/autoScaling", "value": { "max": 5, "min": 2 }}]'
+----
++
+[NOTE]
+====
+In the example, the minimum number of nodes is 2, and the maximum is 5. The maximum number of nodes that you can add might be bound by your platform. For example, if you use the Agent platform, the maximum number of nodes is bound by the number of available agents.
+====
+
+. Create a workload that requires a new node.
+
+.. Create a YAML file that contains the workload configuration, by using the following example:
++
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  creationTimestamp: null
+  labels:
+    app: reversewords
+  name: reversewords
+  namespace: default
+spec:
+  replicas: 40
+  selector:
+    matchLabels:
+      app: reversewords
+  strategy: {}
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        app: reversewords
+  spec:
+    containers:
+    - image: quay.io/mavazque/reversewords:latest
+      name: reversewords
+      resources:
+        requests:
+          memory: 2Gi
+status: {}
+----
+
+.. Save the file as `workload-config.yaml`.
+
+.. Apply the YAML by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f workload-config.yaml
+----
+
+. Extract the `admin-kubeconfig` secret by entering the following command:
++
+[source,terminal]
+----
+$ oc extract -n <hosted-cluster-namespace> secret/<hosted-cluster-name>-admin-kubeconfig --to=./hostedcluster-secrets --confirm
+----
++
+.Example output
+----
+hostedcluster-secrets/kubeconfig
+----
+
+. You can check if new nodes are in the `Ready` status by entering the following command:
++
+[source,terminal]
+----
+$ oc --kubeconfig ./hostedcluster-secrets get nodes
+----
+
+. To remove the node, delete the workload by entering the following command:
++
+[source,terminal]
+----
+$ oc --kubeconfig ./hostedcluster-secrets -n default delete deployment reversewords
+----
+
+. Wait for several minutes to pass without requiring the additional capacity. On the Agent platform, the agent is decommissioned and can be reused. You can confirm that the node was removed by entering the following command:
++
+[source,terminal]
+----
+$ oc --kubeconfig ./hostedcluster-secrets get nodes
+----