OSDOCS-2333: Azure Stack Hub MAPI integration

_topic_maps/_topic_map.yml

@@ -1658,6 +1658,8 @@ Topics:
     File: creating-machineset-aws
   - Name: Creating a machine set on Azure
     File: creating-machineset-azure
+  - Name: Creating a machine set on Azure Stack Hub
+    File: creating-machineset-azure-stack-hub
   - Name: Creating a machine set on GCP
     File: creating-machineset-gcp
   - Name: Creating a machine set on OpenStack

machine_management/creating-infrastructure-machinesets.adoc

@@ -13,7 +13,7 @@ You can use infrastructure machine sets to create machines that host only infras
 
 include::modules/infrastructure-components.adoc[leveloffset=+1]
 
-For information on infrastructure nodes and which components can run on infrastructure nodes, see the "Red Hat OpenShift control plane and infrastructure nodes" section in the link:https://www.redhat.com/en/resources/openshift-subscription-sizing-guide[OpenShift sizing and subscription guide for enterprise Kubernetes] document.   
+For information about infrastructure nodes and which components can run on infrastructure nodes, see the "Red Hat OpenShift control plane and infrastructure nodes" section in the link:https://www.redhat.com/en/resources/openshift-subscription-sizing-guide[OpenShift sizing and subscription guide for enterprise Kubernetes] document.
 
 [id="creating-infrastructure-machinesets-production"]
 == Creating infrastructure machine sets for production environments
@@ -34,6 +34,13 @@ include::modules/machineset-yaml-azure.adoc[leveloffset=+3]
 
 Machine sets running on Azure support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-non-guaranteed-instance_creating-machineset-azure[Spot VMs]. You can save on costs by using Spot VMs at a lower price compared to standard VMs on Azure. You can xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-azure[configure Spot VMs] by adding `spotVMOptions` to the `MachineSet` YAML file.
 
+include::modules/machineset-yaml-azure-stack-hub.adoc[leveloffset=+3]
+
+[NOTE]
+====
+Machine sets running on Azure Stack Hub do not support non-guaranteed Spot VMs.
+====
+
 include::modules/machineset-yaml-gcp.adoc[leveloffset=+3]
 
 Machine sets running on GCP support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-non-guaranteed-instance_creating-machineset-gcp[preemptible VM instances]. You can save on costs by using preemptible VM instances at a lower price

machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc

@@ -0,0 +1,23 @@
+[id="creating-machineset-azure-stack-hub"]
+= Creating a machine set on Azure Stack Hub
+include::modules/common-attributes.adoc[]
+:context: creating-machineset-azure-stack-hub
+
+toc::[]
+
+You can create a different machine set to serve a specific purpose in your {product-title} cluster on Microsoft Azure Stack Hub. For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines.
+
+//[IMPORTANT] admonition for UPI
+include::modules/machine-user-provisioned-limitations.adoc[leveloffset=+1]
+
+//Machine API overview
+include::modules/machine-api-overview.adoc[leveloffset=+1]
+
+//Sample YAML for a machine set custom resource on Azure Stack Hub
+include::modules/machineset-yaml-azure-stack-hub.adoc[leveloffset=+1]
+
+//Creating a machine set
+include::modules/machineset-creating.adoc[leveloffset=+1]
+
+//Enabling customer-managed encryption keys for a machine set
+include::modules/machineset-customer-managed-encryption-azure.adoc[leveloffset=+1]

modules/machine-api-overview.adoc

@@ -2,6 +2,7 @@
 //
 // * machine_management/creating_machinesets/creating-machineset-aws.adoc
 // * machine_management/creating_machinesets/creating-machineset-azure.adoc
+// * machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc
 // * machine_management/creating_machinesets/creating-machineset-gcp.adoc
 // * machine_management/creating_machinesets/creating-machineset-osp.adoc
 // * machine_management/creating_machinesets/creating-machineset-vsphere.adoc

modules/machine-user-provisioned-limitations.adoc

@@ -3,6 +3,7 @@
 // * machine_management/creating-infrastructure-machinesets.adoc
 // * machine_management/creating_machinesets/creating-machineset-aws.adoc
 // * machine_management/creating_machinesets/creating-machineset-azure.adoc
+// * machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc
 // * machine_management/creating_machinesets/creating-machineset-gcp.adoc
 // * machine_management/creating_machinesets/creating-machineset-osp.adoc
 // * machine_management/creating_machinesets/creating-machineset-rhv.adoc

modules/machineset-creating.adoc

@@ -3,6 +3,7 @@
 // * machine_management/creating-infrastructure-machinesets.adoc
 // * machine_management/creating_machinesets/creating-machineset-aws.adoc
 // * machine_management/creating_machinesets/creating-machineset-azure.adoc
+// * machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc
 // * machine_management/creating_machinesets/creating-machineset-gcp.adoc
 // * machine_management/creating_machinesets/creating-machineset-osp.adoc
 // * machine_management/creating_machinesets/creating-machineset-vsphere.adoc
@@ -17,10 +18,12 @@ endif::[]
 ifeval::["{context}" == "creating-windows-machineset-azure"]
 :win:
 endif::[]
+ifeval::["{context}" == "creating-machineset-azure-stack-hub"]
+:ash:
+endif::[]
 ifeval::["{context}" == "creating-windows-machineset-vsphere"]
 :win:
 endif::[]
-
 ifeval::["{context}" == "creating-machineset-vsphere"]
 :vsphere:
 endif::[]
@@ -39,12 +42,20 @@ ifdef::vsphere[]
 * Create a tag inside your vCenter instance based on the cluster API name. This tag is utilized by the machine set to associate the {product-title} nodes to the provisioned virtual machines (VM). For directions on creating tags in vCenter, see the VMware documentation for link:https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.vcenterhost.doc/GUID-E8E854DD-AA97-4E0C-8419-CE84F93C4058.html[vSphere Tags and Attributes].
 * Have the necessary permissions to deploy VMs in your vCenter instance and have the required access to the datastore specified.
 endif::vsphere[]
+ifdef::ash[]
+* Create an availability set in which to deploy Azure Stack Hub machines.
+endif::ash[]
 
 .Procedure
 
 . Create a new YAML file that contains the machine set custom resource (CR) sample and is named `<file_name>.yaml`.
 +
+ifndef::ash[]
 Ensure that you set the `<clusterID>` and `<role>` parameter values.
+endif::ash[]
+ifdef::ash[]
+Ensure that you set the `<availabilitySet>`, `<clusterID>`, and `<role>` parameter values.
+endif::ash[]
 
 .. If you are not sure which value to set for a specific field, you can check an existing machine set from your cluster:
 +

modules/machineset-customer-managed-encryption-azure.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
 // * machine_management/creating_machinesets/creating-machineset-gcp.adoc
+// * machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc
 
 [id="machineset-enabling-customer-managed-encryption-azure_{context}"]
 = Enabling customer-managed encryption keys for a machine set

modules/machineset-yaml-azure-stack-hub.adoc

@@ -0,0 +1,176 @@
+// Module included in the following assemblies:
+//
+// * machine_management/creating-infrastructure-machinesets.adoc
+// * machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc
+// * post_installation_configuration/cluster-tasks.adoc
+
+ifeval::["{context}" == "creating-infrastructure-machinesets"]
+:infra:
+endif::[]
+ifeval::["{context}" == "post-install-cluster-tasks"]
+:infra:
+endif::[]
+
+[id="machineset-yaml-azure-stack-hub_{context}"]
+= Sample YAML for a machine set custom resource on Azure Stack Hub
+
+This sample YAML defines a machine set that runs in the `1` Microsoft Azure zone in a region and creates nodes that are labeled with
+ifndef::infra[`node-role.kubernetes.io/<role>: ""`.]
+ifdef::infra[`node-role.kubernetes.io/infra: ""`.]
+
+In this sample, `<infrastructure_id>` is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and
+ifndef::infra[`<role>`]
+ifdef::infra[`<infra>`]
+is the node label to add.
+
+[source,yaml]
+----
+apiVersion: machine.openshift.io/v1beta1
+kind: MachineSet
+metadata:
+  labels:
+    machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1>
+ifndef::infra[]
+    machine.openshift.io/cluster-api-machine-role: <role> <2>
+    machine.openshift.io/cluster-api-machine-type: <role> <2>
+  name: <infrastructure_id>-<role>-<region> <3>
+endif::infra[]
+ifdef::infra[]
+    machine.openshift.io/cluster-api-machine-role: <infra> <2>
+    machine.openshift.io/cluster-api-machine-type: <infra> <2>
+  name: <infrastructure_id>-infra-<region> <3>
+endif::infra[]
+  namespace: openshift-machine-api
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1>
+ifndef::infra[]
+      machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role>-<region> <3>
+endif::infra[]
+ifdef::infra[]
+      machine.openshift.io/cluster-api-machineset: <infrastructure_id>-infra-<region> <3>
+endif::infra[]
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1>
+ifndef::infra[]
+        machine.openshift.io/cluster-api-machine-role: <role> <2>
+        machine.openshift.io/cluster-api-machine-type: <role> <2>
+        machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role>-<region> <3>
+endif::infra[]
+ifdef::infra[]
+        machine.openshift.io/cluster-api-machine-role: <infra> <2>
+        machine.openshift.io/cluster-api-machine-type: <infra> <2>
+        machine.openshift.io/cluster-api-machineset: <infrastructure_id>-infra-<region> <3>
+endif::infra[]
+    spec:
+      metadata:
+        creationTimestamp: null
+        labels:
+ifndef::infra[]
+          node-role.kubernetes.io/<role>: "" <2>
+endif::infra[]
+ifdef::infra[]
+          node-role.kubernetes.io/infra: "" <2>
+      taints: <4>
+      - key: node-role.kubernetes.io/infra
+        effect: NoSchedule
+endif::infra[]
+      providerSpec:
+        value:
+          apiVersion: machine.openshift.io/v1beta1
+          availabilitySet: <availability_set> <6>
+          credentialsSecret:
+            name: azure-cloud-credentials
+            namespace: openshift-machine-api
+          image:
+            offer: ""
+            publisher: ""
+            resourceID: /resourceGroups/<infrastructure_id>-rg/providers/Microsoft.Compute/images/<infrastructure_id> <1>
+            sku: ""
+            version: ""
+          internalLoadBalancer: ""
+          kind: AzureMachineProviderSpec
+ifndef::infra[]
+          location: <region> <4>
+endif::infra[]
+ifdef::infra[]
+          location: <region> <5>
+endif::infra[]
+          managedIdentity: <infrastructure_id>-identity <1>
+          metadata:
+            creationTimestamp: null
+          natRule: null
+          networkResourceGroup: ""
+          osDisk:
+            diskSizeGB: 128
+            managedDisk:
+              storageAccountType: Premium_LRS
+            osType: Linux
+          publicIP: false
+          publicLoadBalancer: ""
+          resourceGroup: <infrastructure_id>-rg <1>
+          sshPrivateKey: ""
+          sshPublicKey: ""
+          subnet: <infrastructure_id>-<role>-subnet <1> <2>
+          userDataSecret:
+            name: worker-user-data <2>
+          vmSize: Standard_DS4_v2
+          vnet: <infrastructure_id>-vnet <1>
+ifndef::infra[]
+          zone: "1" <5>
+endif::infra[]
+ifdef::infra[]
+          zone: "1" <7>
+endif::infra[]
+----
+<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI installed, you can obtain the infrastructure ID by running the following command:
++
+[source,terminal]
+----
+$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster
+----
++
+You can obtain the subnet by running the following command:
++
+[source,terminal]
+----
+$  oc -n openshift-machine-api \
+    -o jsonpath='{.spec.template.spec.providerSpec.value.subnet}{"\n"}' \
+    get machineset/<infrastructure_id>-worker-centralus1
+----
+You can obtain the vnet by running the following command:
++
+[source,terminal]
+----
+$  oc -n openshift-machine-api \
+    -o jsonpath='{.spec.template.spec.providerSpec.value.vnet}{"\n"}' \
+    get machineset/<infrastructure_id>-worker-centralus1
+----
+ifndef::infra[]
+<2> Specify the node label to add.
+<3> Specify the infrastructure ID, node label, and region.
+<4> Specify the region to place machines on.
+<5> Specify the zone within your region to place machines on. Be sure that your region supports the zone that you specify.
+<6> Specify the availability set for the cluster.
+endif::infra[]
+ifdef::infra[]
+<2> Specify the `<infra>` node label.
+<3> Specify the infrastructure ID, `<infra>` node label, and region.
+<4> Specify a taint to prevent user workloads from being scheduled on infra nodes.
+<5> Specify the region to place machines on.
+<6> Specify the availability set for the cluster.
+<7> Specify the zone within your region to place machines on. Be sure that your region supports the zone that you specify.
+endif::infra[]
+
+
+ifeval::["{context}" == "creating-infrastructure-machinesets"]
+:!infra:
+endif::[]
+ifeval::["{context}" == "cluster-tasks"]
+:!infra:
+endif::[]

modules/machineset-yaml-azure.adoc

@@ -12,7 +12,7 @@ ifeval::["{context}" == "post-install-cluster-tasks"]
 endif::[]
 
 [id="machineset-yaml-azure_{context}"]
-=  Sample YAML for a machine set custom resource on Azure
+= Sample YAML for a machine set custom resource on Azure
 
 This sample YAML defines a machine set that runs in the `1` Microsoft Azure zone in a region and creates nodes that are labeled with
 ifndef::infra[`node-role.kubernetes.io/<role>: ""`.]