diff --git a/doc/source/configuration/ironic.rst b/doc/source/configuration/ironic.rst new file mode 100644 index 0000000000..5d8f259215 --- /dev/null +++ b/doc/source/configuration/ironic.rst @@ -0,0 +1,232 @@ +====== +Ironic +====== + +Ironic networking +================= + +Ironic will require the workload provisioning and cleaning networks to be +configured in ``networks.yml`` + +The workload provisioning network will require an allocation pool for +Ironic inspection and for Neutron, an example configuration is shown +below. + +.. code-block:: yaml + + # Workload provisioning network IP information. + provision_wl_net_cidr: "172.0.0.0/16" + provision_wl_net_allocation_pool_start: "172.0.0.4" + provision_wl_net_allocation_pool_end: "172.0.0.6" + provision_wl_net_inspection_allocation_pool_start: "172.0.1.4" + provision_wl_net_inspection_allocation_pool_end: "172.0.1.250" + provision_wl_net_neutron_allocation_pool_start: "172.0.2.4" + provision_wl_net_neutron_allocation_pool_end: "172.0.2.250" + provision_wl_net_neutron_gateway: "172.0.1.1" + +The cleaning network will also require a Neutron allocation pool. + +.. code-block:: yaml + + # Cleaning network IP information. + cleaning_net_cidr: "172.1.0.0/16" + cleaning_net_allocation_pool_start: "172.1.0.4" + cleaning_net_allocation_pool_end: "172.1.0.6" + cleaning_net_neutron_allocation_pool_start: "172.1.2.4" + cleaning_net_neutron_allocation_pool_end: "172.1.2.250" + cleaning_net_neutron_gateway: "172.1.0.1" + +OpenStack Config +================ + +Overcloud Ironic will require a router to exist between the internal API +network and the provision workload network, a way to achieve this is by +using `OpenStack Config ` +to define the internal API network in Neutron and set up a router with +a gateway. + +It not necessary to define the provision and cleaning networks in this +configuration as they will be generated during + +.. code-block:: console + + kayobe overcloud post configure + +The openstack config file could resemble the network, subnet and router +configuration shown below: + +.. code-block:: yaml + + networks: + - "{{ openstack_network_intenral }}" + openstack_network_internal: + name: "internal-net" + project: "admin" + provider_network_type: "vlan" + provider_physical_network: "physnet1" + provider_segmentation_id: 458 + shared: false + external: true + + subnets: + - "{{ openstack_subnet_internal }}" + openstack_subnet_internal: + name: "internal-net" + project: "admin" + cidr: "10.10.3.0/24" + enable_dhcp: true + allocation_pool_start: "10.10.3.3" + allocation_pool_end: "10.10.3.3" + + openstack_routers: + - "{{ openstack_router_ironic }}" + + openstack_router_ironic: + - name: ironic + project: admin + interfaces: + - net: "provision-net" + subnet: "provision-net" + portip: "172.0.1.1" + - net: "cleaning-net" + subnet: "cleaning-net" + portip: "172.1.0.1" + network: internal-net + +To provision baremetal nodes in Nova you will also require setting a flavour +speciifc to that type of baremetal host. You will need to replace the custom +resource ``resources:CUSTOM_`` placeholder with +the resource class of your baremetal hosts, you will also need this later when +configuring the baremetal-compute inventory. + +.. code-block:: yaml + + openstack_flavors: + - "{{ openstack_flavor_baremetal_A }}" + # Bare metal compute node. + openstack_flavor_baremetal_A: + name: "baremetal-A" + ram: 1048576 + disk: 480 + vcpus: 256 + extra_specs: + "resources:CUSTOM_": 1 + "resources:VCPU": 0 + "resources:MEMORY_MB": 0 + "resources:DISK_GB": 0 + +Enabling conntrack +================== + +UEFI booting requires conntrack_helper to be configured on the Ironic neutron +router, this is due to TFTP traffic being dropped due to being UDP. You will +need to define some extension drivers in ``neutron.yml`` to ensure conntrack is +enabled in neutron server. + +.. code-block:: yaml + + kolla_neutron_ml2_extension_drivers: + port_security + conntrack_helper + dns_domain_ports + +The neutron l3 agent also requires conntrack to be set as an extension in +``kolla/config/neutron/l3_agent.ini`` + +.. code-block:: ini + + [agent] + extensions = conntrack_helper + +It is also required to load the conntrack kernel module ``nf_nat_tftp``, +``nf_conntrack`` and ``nf_conntrack_tftp`` on network nodes. You can load these +modules using modprobe or define these in /etc/module-load. + +The Ironic neutron router will also need to be configured to use +conntrack_helper. + +.. code-block:: json + + "conntrack_helpers": { + "protocol": "udp", + "port": 69, + "helper": "tftp" + } + +Currently it's not possible to add this helper via the OpenStack CLI, to add +this to the Ironic router you will need to make a request to the API directly, +for example via cURL. + +.. code-block:: console + + curl -g -i -X POST \ + http://:9696/v2.0/routers//conntrack_helpers \ + -H "Accept: application/json" \ + -H "User-Agent: openstacksdk/2.0.0 keystoneauth1/5.4.0 python-requests/2.31.0 CPython/3.9.18" \ + -H "X-Auth-Token: " \ + -d '{ "conntrack_helper": {"helper": "tftp", "protocol": "udp", "port": 69 } }' + +TFTP server +=========== + +By default the Ironic TFTP server (ironic_pxe container) will call the UEFI +boot file ``ipxe-x86_64.efi`` instead of ``ipxe.efi`` meaning no boot file will +be sent during the PXE boot process in the default configuration. + +As of now this is solved by using a hack workaround by changing the boot file +in the ``ironic_pxe`` container. To do this you will need to enter the +container and rename the file manually. + +.. code-block:: console + + docker exec ironic_pxe “mv /tftpboot/ipxe-x86_64.efi /tftpboot/ipxe.efi” + +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 + … + + [r1:vars] + ironic_driver=redfish + resource_class= + redfish_system_id= + redfish_verify_ca= + redfish_username= + redfish_password= + + [baremetal-compute:children] + r1 + +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. + +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. + +Node enrollment +=============== + +When nodes are defined in the inventory you can begin enrolling them by +invoking the Kayobe commmand (Note that only the Redfish driver is supported +by this command) + +.. code-block:: console + + kayobe baremetal compute register + +Following registration, the baremetal nodes can be inspected and made +available for provisioning by Nova via the Kayobe commands + +.. code-block:: console + + kayobe baremetal compute inspect + kayobe baremetal compute provide