Sync with client documentation

assumptionsandg · assumptionsandg · commit 8176522cf785 · 2024-09-09T11:36:13.000+01:00
diff --git a/doc/source/configuration/ironic.rst b/doc/source/configuration/ironic.rst
@@ -116,13 +116,13 @@ configuring the baremetal-compute inventory.
     disk: 480
     vcpus: 256
     extra_specs:
-    "resources:CUSTOM_<YOUR_BAREMETAL_RESOURCE_CLASS>": 1
-    "resources:VCPU": 0
-    "resources:MEMORY_MB": 0
-    "resources:DISK_GB": 0
+      "resources:CUSTOM_<YOUR_BAREMETAL_RESOURCE_CLASS>": 1
+      "resources:VCPU": 0
+      "resources:MEMORY_MB": 0
+      "resources:DISK_GB": 0
 
-Enabling conntrack
-==================
+Enabling conntrack (ML2/OVS only)
+=================================
 
 Conntrack_helper will be required when UEFI booting on a cloud with ML2/OVS
 and using the iptables firewall_driver, otherwise TFTP traffic is dropped due
@@ -173,52 +173,81 @@ CLI
 Baremetal inventory
 ===================
 
-To begin enrolling nodes you will need to define them in the hosts file.
-
-.. code-block:: ini
-
-  [r1]
-  hv1 ipmi_address=10.1.28.16
-  hv2 ipmi_address=10.1.28.17
-  …
-
-  [baremetal-compute:children]
-  r1
-
-The baremetal nodes will also require some extra variables to be defined
-in the group_vars for your rack, these should include the BMC credentials
-and the Ironic driver you wish to use.
+The baremetal inventory is constructed with three different group types.
+The first group is the default baremetal compute group for Kayobe called
+[baremetal-compute] and will contain all baremetal nodes including tenant
+and hypervisor nodes. This group acts as a parent for all baremetal nodes
+and config that can be shared between all baremetal nodes will be defined
+here.
+
+We will need to create a Kayobe group_vars file for the baremetal-compute
+group that contains all the variables we want to define for the group. We
+can put all these variables in the inventory in
+‘inventory/group_vars/baremetal-compute/ironic-vars’ The ironic_driver_info
+template dict contains all variables to be templated into the driver_info
+property in Ironic. This includes the BMC address, username, password,
+IPA configuration etc. We also currently define the ironic_driver here as
+all nodes currently use the Redfish driver.
 
 .. code-block:: yaml
 
     ironic_driver: redfish
 
     ironic_driver_info:
-        redfish_system_id: "{{ ironic_redfish_system_id }}"
-        redfish_address: "{{ ironic_redfish_address }}"
-        redfish_username: "{{ ironic_redfish_username }}"
-        redfish_password: "{{ ironic_redfish_password }}"
-        redfish_verify_ca: "{{ ironic_redfish_verify_ca }}"
-        ipmi_address: "{{ ipmi_address }}"
+      redfish_system_id: "{{ ironic_redfish_system_id }}"
+      redfish_address: "{{ ironic_redfish_address }}"
+      redfish_username: "{{ ironic_redfish_username }}"
+      redfish_password: "{{ ironic_redfish_password }}"
+      redfish_verify_ca: "{{ ironic_redfish_verify_ca }}"
+      ipmi_address: "{{ ipmi_address }}"
 
     ironic_properties:
-        capabilities: "{{ ironic_capabilities }}"
+      capabilities: "{{ ironic_capabilities }}"
 
-    ironic_resource_class: "example_resouce_class"
-    ironic_redfish_system_id: "/redfish/v1/Systems/System.Embedded.1"
-    ironic_redfish_verify_ca: "{{ inspector_rule_var_redfish_verify_ca }}"
     ironic_redfish_address: "{{ ipmi_address }}"
     ironic_redfish_username: "{{ inspector_redfish_username }}"
     ironic_redfish_password: "{{ inspector_redfish_password }}"
     ironic_capabilities: "boot_option:local,boot_mode:uefi"
 
-The typical layout for baremetal nodes are separated by racks, for instance
-in rack 1 we have the following configuration set up where the BMC addresses
-are defined for all nodes, and Redfish information such as username, passwords
-and the system ID are defined for the rack as a whole.
+The second group type will be the hardware type that a baremetal node belongs
+to, These variables will be in the inventory too in ‘inventory/group_vars/
+baremetal-<YOUR_BAREMETAL_HARDWARE_TYPE>’
+
+Specific variables to the hardware type include the resource_class which is
+used to associate the hardware type to the flavour in Nova we defined earlier
+in Openstack Config.
+
+.. code-block:: yaml
+
+    ironic_resource_class: "example_resource_class"
+    ironic_redfish_system_id: "example_system_id"
+    ironic_redfish_verify_ca: "{{ inspector_rule_var_redfish_verify_ca }}"
+
+The third group type will be the rack where the node is installed. This is the
+group in which the rack specific networking configuration is defined here and
+where the BMC address is entered as a host variable for each baremetal node.
+Nodes can now be entered directly into the hosts file as part of this group.
+
+.. code-block:: ini
+
+    [rack1]
+    hv001 ipmi_address=10.1.28.16
+    hv002 ipmi_address=10.1.28.17
+    …
+
+This rack group contains the baremetal hosts but will also need to be
+associated with the baremetal-compute and baremetal-sr645 groups in order for
+those variables to be associated with the rack group.
+	
+.. code-block:: ini
 
-You can add more racks to the deployment by replicating the rack 1 example and
-adding that as an entry to the baremetal-compute group.
+	[baremetal-<YOUR_BAREMETAL_HARDWARE_TYPE>:children]
+	rack1
+	…
+
+	[baremetal-compute:children]
+	rack1
+	…
 
 Node enrollment
 ===============
@@ -230,85 +259,194 @@ invoking the Kayobe commmand
 
   (kayobe) $ kayobe baremetal compute register
 
-Following registration, the baremetal nodes can be inspected and made
-available for provisioning by Nova via the Kayobe commands
+All nodes that were not defined in Ironic previously should’ve been enrolled
+following this playbook and should now be in ‘manageable’ state if Ironic was
+able to reach the BMC of the node. We will need to inspect the baremetal nodes
+to gather information about their hardware to prepare for deployment. Kayobe
+provides an inspection workflow and can be run using:
 
 .. code-block:: console
 
   (kayobe) $ kayobe baremetal compute inspect
+
+Inspection would require PXE booting the nodes into IPA. If the nodes were able
+to PXE boot properly they would now be in ‘manageable’ state again. If an error
+developed during PXE booting, the nodes will now be in ‘inspect failed’ state
+and issues preventing the node from booting or returning introspection data
+will need to be resolved before continuing. If the nodes did inspect properly,
+they can be cleaned and made available to Nova by running the provide workflow.
+
+.. code-block:: console
+
   (kayobe) $ kayobe baremetal compute provide
 
 Baremetal hypervisors
 =====================
 
-To deploy baremetal hypervisor nodes it will be neccessary to split out
-the nodes you wish to use as hypervisors and add it to the Kayobe compute
-group to ensure the hypervisor is configured as a compute node during
-host configure.
+Nodes that will not be dedicated as baremetal tenant nodes can be converted
+into hypervisors as required. StackHPC Kayobe configuration provides a workflow
+to provision baremetal tenants with the purpose of converted these nodes to
+hypervisors. To begin the process of converting nodes we will need to define a
+child group of the rack which will contain baremetal nodes dedicated to compute
+hosts.
 
 .. code-block:: ini
 
-    [r1]
-    hv1 ipmi_address=10.1.28.16
+	[rack1]
+  hv001 ipmi_address=10.1.28.16
+  hv002 ipmi_address=10.1.28.17
+  …
 
-    [r1-hyp]
-    hv2 ipmi_address=10.1.28.17
+	[rack1-compute]
+  hv003 ipmi_address=10.1.28.18
+  hv004 ipmi_address=10.1.28.19
+  …
 
-    [r1:children]
-    r1-hyp
+	[rack1:children]
+	rack1-compute
 
-    [compute:children]
-    r1-hyp
+	[compute:children]
+	rack1-compute
 
-    [baremetal-compute:children]
-    r1
+The rack1-compute group as shown above is also associated with the Kayobe
+compute group in order for Kayobe to run the compute Kolla workflows on these
+nodes during service deployment.
 
-The hypervisor nodes will also need to define hypervisor specific variables
-such as the image to be used, network to provision on and the availability zone.
-These can be defined under group_vars.
+You will also need to setup the Kayobe network configuration for the rack1
+group. In networks.yml you should create an admin network for the rack1 group,
+this should consist of the correct CIDR for the rack being deployed.
+The configuration should resemble below in networks.yml:
 
 .. code-block:: yaml
 
-    hypervisor_image: "37825714-27da-48e0-8887-d609349e703b"
-    key_name: "testing"
-    availability_zone: "nova"
-    baremetal_flavor: "baremetal-A"
-    baremetal_network: "rack-net"
-    auth:
-      auth_url: "{{ lookup('env', 'OS_AUTH_URL') }}"
-      username: "{{ lookup('env', 'OS_USERNAME') }}"
-      password: "{{ lookup('env', 'OS_PASSWORD') }}"
-      project_name: "{{ lookup('env', 'OS_PROJECT_NAME') }}"
+	physical_rack1_admin_oc_net_cidr: “172.16.208.128/27”
+	physical_rack1_admin_oc_net_gateway: “172.16.208.129”
+	physical_rack1_admin_net_defroute: true
 
-To begin deploying these nodes as instances you will need to run the Ansible
-playbook deploy-baremetal-instance.yml.
+You will also need to configure a neutron network for racks to deploy instances
+on, we can configure this in openstack-config as before. We will need to define
+this network and associate a subnet for it for each rack we want to enroll in
+Ironic.
+
+.. code-block:: yaml
+
+	openstack_network_rack:
+  name: "rack-net"
+  project: "admin"
+  provider_network_type: "vlan"
+  provider_physical_network: "provider"
+  provider_segmentation_id: 450
+  shared: false
+  external: false
+  subnets:
+	- "{{ openstack_subnet_rack1 }}"
+
+  openstack_subnet_rack1:
+    name: "rack1-subnet"
+    project: "admin"
+    cidr: "172.16.208.128/27"
+    enable_dhcp: false
+    gateway_ip: "172.16.208.129"
+    allocation_pool_start: "172.16.208.130"
+    allocation_pool_end: "172.16.208.130"
+
+The subnet configuration largely resembles the Kayobe network configuration,
+however we do not need to define an allocation pool or enable dhcp as we will
+be associating neutron ports with our hypervisor instances per IP address to
+ensure they match up properly.
+
+Now we should ensure the network interfaces are properly configured for the
+rack1-compute group, the interfaces should include the kayobe admin network
+for rack1 and the kayobe internal API network and be defined in the group_vars.
+
+.. code-block:: yaml
+
+ network_interfaces:
+  - "internal_net"
+  - "physical_rack1_admin_oc_net"
+
+  admin_oc_net_name: "physical_rack1_admin_oc_net"
+
+  physical_rack1_admin_oc_net_bridge_ports:
+    - eth0
+  physical_rack1_admin_oc_net_interface: br0
+
+  internal_net_interface: "br0.{{ internal_net_vlan }}"
+
+We should also ensure some variables are configured properly for our group,
+such as the hypervisor image. These variables can be defined anywhere in
+group_vars, we can place them in the ironic-vars file we used before for
+baremetal node registration.
+
+.. code-block:: yaml
+
+	hypervisor_image: "<image_uuid>"
+	key_name: "<key_name>"
+	availability_zone: "nova"
+	baremetal_flavor: "<ironic_flavor_name>"
+	baremetal_network: "rack-net"
+	auth:
+    auth_url: "{{ lookup('env', 'OS_AUTH_URL') }}"
+    username: "{{ lookup('env', 'OS_USERNAME') }}"
+    password: "{{ lookup('env', 'OS_PASSWORD') }}"
+    project_name: "{{ lookup('env', 'OS_PROJECT_NAME') }}"
+
+With these variables defined we can now begin deploying the baremetal nodes as
+instances, to begin we invoke the deploy-baremetal-hypervisor ansible playbook.
 
 .. code-block:: console
 
-  (kayobe) $ kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/deploy-baremetal-instance.yml
+	kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/deploy-baremetal-hypervisor.yml
+
+This playbook will update the Kayobe network allocations with the the admin
+network addresses associated with that rack for each baremetal server, e.g.
+in the case of rack 1 this will appear in network-allocations.yml as 
+
+.. code-block:: yaml
+
+  physical_rack1_admin_oc_net_ips:
+    hv003: 172.16.208.133
+    hv004: 172.16.208.134
+
+Once the network allocations have been updated, the playbook will then create a
+Neutron port configured with the address of the baremetal node admin network.
+The baremetal hypervisors will then be imaged and deployed associated with that
+Neutron port. You should ensure that all nodes are correctly associated with
+the right baremetal instance, you can do this by running a baremetal node show
+on any given hypervisor node and comparing the server uuid to the metadata on
+the Nova instance.
 
-This playbook will update network allocations with the new baremetal hypervisor
-IP addresses, create a Neutron port corresponding to the address and deploy
-an image on the baremetal instance.
+Once the nodes are deployed, we can use Kayobe to configure them as compute
+hosts, running kayobe overcloud host configure on these nodes will ensure that
+all networking, package and various other host configurations are setup
+
+.. code-block:: console
+
+  kayobe overcloud host configure --limit baremetal-<YOUR_BAREMETAL_HARDWARE_TYPE>
+
+Following host configuration we can begin deploying OpenStack services to the
+baremetal hypervisors by invoking kayobe overcloud service deploy. Nova
+services will be deployed to the baremetal hosts.
+
+.. code-block:: console
 
-When the playbook has finished and the rack is successfully imaged, they can be
-configured with ``kayobe overcloud host configure`` and kolla compute services
-can be deployed with ``kayobe overcloud service deploy``.
+  kayobe overcloud service deploy --kolla-limit baremetal-<YOUR_BAREMETAL_HARDWARE_TYPE>
 
 Un-enrolling hypervisors
 ========================
 
-To convert baremetal hypervisors into regular baremetal compute instances you will need
-to drain the hypervisor of all running compute instances, you should first invoke the
-nova-compute-disable playbook to ensure all Nova services on the baremetal node are disabled
-and compute instances will not be allocated to this node.
+To convert baremetal hypervisors into regular baremetal compute instances you
+will need to drain the hypervisor of all running compute instances, you should
+first invoke the nova-compute-disable playbook to ensure all Nova services on
+the baremetal node are disabled and compute instances will not be allocated to
+this node.
 
 .. code-block:: console
 
   (kayobe) $ kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/nova-compute-disable.yml
 
-Now the Nova services are disabled you should also ensure any existing compute instances
-are moved elsewhere by invoking the nova-compute-drain playbook
+Now the Nova services are disabled you should also ensure any existing compute
+instances are moved elsewhere by invoking the nova-compute-drain playbook
 
 .. code-block:: console
 
