From 7c091920c9bdb1dce09d58f99f6b7889ddafc156 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 21 Nov 2025 16:59:46 +0100 Subject: [PATCH] docs: improve README, update host/group vars, and prerequisites --- docs/prerequisites.md | 13 +- docs/set-variables-group-vars.md | 226 ++++++++++++++++--------------- docs/set-variables-host-vars.md | 25 ++-- 3 files changed, 135 insertions(+), 129 deletions(-) diff --git a/docs/prerequisites.md b/docs/prerequisites.md index 5485bda3..ec4a6006 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -18,23 +18,23 @@ * Once a RHEL server is installed natively on the LPAR, pre-existing or configured by this automation, (i.e. the KVM host), you can use that as the file server. * If you are not using a pre-existing KVM host(s) and need to create them using this automation, you must use an FTP server because the HMC does not support HTTP. * A user with sudo and SSH access on that server. -* A DVD ISO file of Red Hat Enterprise Linux (RHEL) 8 for s390x architecture mounted in an accessible folder (e.g. /home//rhel/ for FTP or /var/www/html/rhel for HTTP) +* A DVD ISO file of Red Hat Enterprise Linux (RHEL) 9 for s390x architecture mounted in an accessible folder (e.g. /home//rhel/ for FTP or /var/www/html/rhel for HTTP) * If you do not have RHEL for s390x yet, go to the Red Hat [Customer Portal](https://access.redhat.com/downloads/content) and download it. * Under 'Product Variant' use the drop-down menu to select 'Red Hat Enterprise Linux for IBM z Systems' - * Double-check it's for version 8 and for s390x architecture - * Then scroll down to Red Hat Enterprise Linux 8.x Binary DVD and click on the 'Download Now' button. + * Double-check it's for version 9 and for s390x architecture + * Then scroll down to Red Hat Enterprise Linux 9.x Binary DVD and click on the 'Download Now' button. * To pull the image directly from the command-line of your file server, copy the link for the 'Download Now' button and use `wget` to pull it down. ``` - wget "https://access.cdn.redhat.com/content/origin/files/sha256/13/13[...]40/rhel-8.7-s390x-dvd.iso?user=6[...]e" + wget "https://access.cdn.redhat.com/content/origin/files/sha256/13/13[...]40/rhel-9.4-s390x-dvd.iso?user=6[...]e" ``` * Don't forget to mount it too: * FTP: ``` - mount /home//rhel + mount /home//rhel ``` * or HTTP: ``` - mount /var/www/html/rhel + mount /var/www/html/rhel ``` * A folder created to store config files (e.g. /home/user/ocp-config for FTP or /var/www/html/ocp-config for http) * For FTP: @@ -92,3 +92,4 @@ In addition make sure that python3 is installed on the jumphost otherwise ansibl ``` yum install python3 ``` + diff --git a/docs/set-variables-group-vars.md b/docs/set-variables-group-vars.md index c657d79e..818530ba 100644 --- a/docs/set-variables-group-vars.md +++ b/docs/set-variables-group-vars.md @@ -10,95 +10,97 @@ ## 1 - Controller **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**installation_type** | Can be of type kvm or lpar. Some packages will be ignored for installation in case of non lpar based installation. | kvm -**controller_sudo_pass** | The password to the machine running Ansible (localhost). This will only be used for two things. To ensure you've installed the pre-requisite packages if you're on Linux, and to add the login URL to your /etc/hosts file. | Pas$w0rd! +**installation_type** | Can be of type kvm or lpar. Some packages will be ignored for installation in case of non lpar based installation. | `kvm` +**controller_sudo_pass** | (Optional) The password to the machine running Ansible (localhost). This will only be used for two things. To ensure you've installed the pre-requisite packages if you're on Linux, and to add the login URL to your /etc/hosts file. Keep empty to use default pass | `'ch4ngeMe!'` ## 2 - LPAR(s) **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.z.high_availability** | Is this cluster spread across three LPARs? If yes, mark True. If not (just in one LPAR), mark False | True -**env.z.ip_forward** | This variable specifies if ip forwarding is enabled or not if NAT network is selected. If ip_forwarding is set to 0, the installed OCP cluster will not be able to access external services because using NAT keep the nodes isolated. This parameter will be set via sysctl on the KVM host. The change of the value is instantly active. This setting will be configured during 3_setup_kvm playbook. If NAT will be configured after 3_setup_kvm playbook, the setup needs to be done manually before bastion is being created, configured or reconfigured by running the 3_setup_kvm playbook with parameter: --tags cfg_ip_forward | 1 -**env.z.lpar1.create** | To have Ansible create an LPAR and install RHEL on it for the KVM host, mark True. If using a pre-existing LPAR with RHEL already installed, mark False. | True -**env.z.lpar1.hostname** | The hostname of the KVM host. | kvm-host-01 -**env.z.lpar1.ip** | The IPv4 address of the KVM host. | 192.168.10.1 -**env.z.lpar1.user** | Username for Linux admin on KVM host 1. Recommended to run as a non-root user with sudo access. | admin -**env.z.lpar1.pass** | The password for the user that will be created or exists on the KVM host. | ch4ngeMe! -**env.z.lpar2.create** | To create a second LPAR and install RHEL on it to act as another KVM host, mark True. If using pre-existing LPAR(s) with RHEL already installed, mark False. | True -**env.z.lpar2.hostname** | (Optional) The hostname of the second KVM host. | kvm-host-02 -**env.z.lpar2.ip** | (Optional) The IPv4 address of the second KVM host. | 192.168.10.2 -**env.z.lpar2.user** | Username for Linux admin on KVM host 2. Recommended to run as a non-root user with sudo access. | admin -**env.z.lpar2.pass** | (Optional) The password for the admin user on the second KVM host. | ch4ngeMe! -**env.z.lpar3.create** | To create a third LPAR and install RHEL on it to act as another KVM host, mark True. If using pre-existing LPAR(s) with RHEL already installed, mark False. | True -**env.z.lpar3.hostname** | (Optional) The hostname of the third KVM host. | kvm-host-03 -**env.z.lpar3.ip** | (Optional) The IPv4 address of the third KVM host. | 192.168.10.3 -**env.z.lpar3.user** | Username for Linux admin on KVM host 3. Recommended to run as a non-root user with sudo access. | admin -**env.z.lpar3.pass** | (Optional) The password for the admin user on the third KVM host. | ch4ngeMe! +**env.z.high_availability** | Is this cluster spread across three LPARs? If yes, mark True. If not (just in one LPAR), mark False | `True` *(preferred: False)* +**env.z.ip_forward** | This variable specifies whether IP forwarding is enabled when a NAT network is used. If ip_forwarding is set to 0, the installed OCP cluster cannot access external services because NAT keeps the nodes isolated. This parameter is set using sysctl on the KVM host, and the change takes effect immediately. The 3_setup_kvm playbook configures this setting. If NAT is enabled after running the 3_setup_kvm playbook, you must set it manually before the bastion is created, configured, or reconfigured, or re-run the playbook with the parameter: --tags cfg_ip_forward. | `1` +**env.z.lpar1.create** | To have Ansible create an LPAR and install RHEL on it for the KVM host, mark True. If using a pre-existing LPAR with RHEL already installed, mark False. | `True` *(preferred: False)* +**env.z.lpar1.hostname** | The hostname of the KVM host. To get it, run: `hostname` | `''` +**env.z.lpar1.ip** | The IPv4 address of the KVM host. To get it, run: `hostname -i` or `ip addr show` | `''` +**env.z.lpar1.user** | Username for Linux admin on KVM host 1. Recommended to run as a non-root user with sudo access. | `'admin'` +**env.z.lpar1.pass** | The password for the user that will be created or exists on the KVM host. | `'ch4ngeMe!'` +**env.z.lpar2.create** | To create a second LPAR and install RHEL on it to act as another KVM host, mark True. If using pre-existing LPAR(s) with RHEL already installed, mark False. | `True` *(preferred: False)* +**env.z.lpar2.hostname** | (Optional) The hostname of the second KVM host. To get it, run: `hostname` | `''` +**env.z.lpar2.ip** | (Optional) The IPv4 address of the second KVM host. To get it, run: `hostname -i` or `ip addr show` | `''` +**env.z.lpar2.user** | Username for Linux admin on KVM host 2. Recommended to run as a non-root user with sudo access. | `'admin'` +**env.z.lpar2.pass** | (Optional) The password for the admin user on the second KVM host. | `'ch4ngeMe!'` +**env.z.lpar3.create** | To create a third LPAR and install RHEL on it to act as another KVM host, mark True. If using pre-existing LPAR(s) with RHEL already installed, mark False. | `True` *(preferred: False)* +**env.z.lpar3.hostname** | (Optional) The hostname of the third KVM host. To get it, run: `hostname` | `''` +**env.z.lpar3.ip** | (Optional) The IPv4 address of the third KVM host. To get it, run: `hostname -i` or `ip addr show` | `''` +**env.z.lpar3.user** | Username for Linux admin on KVM host 3. Recommended to run as a non-root user with sudo access. | `'admin'` +**env.z.lpar3.pass** | (Optional) The password for the admin user on the third KVM host. | `'ch4ngeMe!'` ## 3 - File Server **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.file_server.ip** | IPv4 address for the file server that will be used to pass config files and iso to KVM host LPAR(s) and bastion VM during their first boot. | 192.168.10.201 -**env.file_server.port** | The port on which the file server is listening. Will be embedded into all download urls. Defaults to protocol default port. Keep empty `''` to use default port | 10000 -**env.file_server.user** | Username to connect to the file server. Must have sudo and SSH access. | user1 -**env.file_server.pass** | Password to connect to the file server as above user. | user1pa$s! -**env.file_server.protocol** | Protocol used to serve the files, either 'ftp' or 'http' | http -**env.file_server.iso_os_variant** | The os variant for the bastion kvm to be created | rhel8.8 -**env.file_server.iso_mount_dir** | Directory path relative to the HTTP/FTP accessible directory where RHEL ISO is mounted. For example, if the FTP root is at /home/user1 and the ISO is mounted at /home/user1/RHEL/8.7 then this variable would be RHEL/8.7 - no slash before or after. | RHEL/8.7 -**env.file_server.cfgs_dir** | Directory path relative to to the HTTP/FTP accessible directory where configuration files can be stored. For example, if FTP root is /home/user1 and you would like to store the configs at /home/user1/ocpz-config then this variable would be ocpz-config. No slash before or after. | ocpz-config +**env.file_server.ip** | IPv4 address for the file server that will be used to pass config files and iso to KVM host LPAR(s) and bastion VM during their first boot. | `'172.23.10.1'` +**env.file_server.port** | The port on which the file server is listening. Will be embedded into all download urls. Defaults to protocol default port. Keep empty `''` to use default port | `10000` +**env.file_server.user** | Username to connect to the file server. Must have sudo and SSH access. Keep empty `''` to use default user | `'user1'` +**env.file_server.pass** | Password to connect to the file server as above user. Keep empty `''` to use default password | `'user1pa$s!'` +**env.file_server.protocol** | Protocol used to serve the files, either 'ftp' or 'http' | `'http'` +**env.file_server.iso_os_variant** | The os variant for the bastion kvm to be created | `'rhel9.4'` +**env.file_server.iso_mount_dir** | Directory path relative to the HTTP/FTP accessible directory where RHEL ISO is mounted. For example, if the FTP root is at /home/user1 and the ISO is mounted at /home/user1/RHEL/9.4 then this variable would be RHEL/8.7 - no slash before or after. | `'redhat/s390x/RHEL9.4/DVD'` +**env.file_server.cfgs_dir** | Directory path relative to to the HTTP/FTP accessible directory where configuration files can be stored. For example, if FTP root is /home/user1 and you would like to store the configs at /home/user1/ocpz-config then this variable would be ocpz-config. No slash before or after. | `'ocpz-config'` ## 4 - Red Hat Info **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.redhat.username** | Red Hat username with a valid license or free trial to Red Hat OpenShift Container Platform (RHOCP), which comes with necessary licenses for Red Hat Enterprise Linux (RHEL) and Red Hat CoreOS (RHCOS). | redhat.user -**env.redhat.password** | Password to Red Hat above user's account. Used to auto-attach necessary subscriptions to KVM Host, bastion VM, and pull live images for OpenShift. | rEdHatPa$s! -**env.redhat.manage_subscription** | True or False. Would you like to subscribe the server with Red Hat? | True -**env.redhat.pull_secret** | Pull secret for OpenShift, comes from Red Hat's [Hybrid Cloud Console](https://console.redhat.com/openshift/install/ibmz/user-provisioned). Make sure to enclose in 'single quotes'. | '{"auths":{"cloud.openshift.com":{"auth":"b3Blb...4yQQ==","email":"redhat.user@gmail.com"}}}' +**env.redhat.username** | Red Hat username with a valid license or free trial to Red Hat OpenShift Container Platform (RHOCP), which comes with necessary licenses for Red Hat Enterprise Linux (RHEL) and Red Hat CoreOS (RHCOS). | `'redhat.user'` +**env.redhat.password** | Password to Red Hat above user's account. Used to auto-attach necessary subscriptions to KVM Host, bastion VM, and pull live images for OpenShift. | `'rEdHatPa$s!'` +**env.redhat.manage_subscription** | True or False. Would you like to subscribe the server with Red Hat? | `True` +**env.redhat.pull_secret** | Pull secret for OpenShift, comes from Red Hat's [Hybrid Cloud Console](https://console.redhat.com/openshift/install/ibmz/user-provisioned). Make sure to enclose in 'single quotes'. | `'{"auths":{"cloud.openshift.com":{"auth":"b3Blb...4yQQ==","email":"redhat.user@gmail.com"}}}'` ## 5 - Bastion **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.bastion.create** | True or False. Would you like to create a bastion KVM guest to host essential infrastructure services like DNS, load balancer, firewall, etc? Can de-select certain services with the env.bastion.options variables below. | True -**env.bastion.vm_name** | Name of the bastion VM. Arbitrary value. | bastion -**env.bastion.resources.disk_size** | How much of the storage pool would you like to allocate to the bastion (in Gigabytes)? Recommended 30 or more. | 30 -**env.bastion.resources.ram** | How much memory would you like to allocate the bastion (in megabytes)? Recommended 4096 or more | 4096 -**env.bastion.resources.swap** | How much swap storage would you like to allocate the bastion (in megabytes)? Recommended 4096 or more. | 4096 -**env.bastion.resources.vcpu** | How many virtual CPUs would you like to allocate to the bastion? Recommended 4 or more. | 4 -**env.bastion.resources.vcpu_model_option** | Configure the CPU model and CPU features exposed to the guest | --cpu host -**env.bastion.networking.ip** | IPv4 address for the bastion. | 192.168.10.3 -**env.bastion.networking.internal_ip** | Private IPv4 address for bastion required when installing LPAR cluster with HiperSocket. Currently supports only when bastion is on LPAR or on zVM host. Incase of zVM bastion enable the HiperSocket prior to the playbook run with vmcp commands on the bastion. Alternative Option would be setting up the bridge port on OSA or RoCE. | 10.42.16.1 -**env.bastion.networking.ipv6** | IPv6 address for the bastion if use_ipv6 variable is 'True'. | fd00::3 -**env.bastion.networking.mac** | MAC address for the bastion if use_dhcp variable is 'True'. | 52:54:00:18:1A:2B -**env.bastion.networking.hostname** | Hostname of the bastion. Will be combined with env.bastion.networking.base_domain to create a Fully Qualified Domain Name (FQDN). | ocpz-bastion -**env.bastion.networking.base_domain** | Base domain that, when combined with the hostname, creates a fully-qualified domain name (FQDN) for the bastion? | ihost.com -**env.bastion.networking.subnetmask** | Subnet of the bastion. | 255.255.255.0 -**env.bastion.networking.gateway** | IPv4 of he bastion's gateway server. | 192.168.10.0 -**env.bastion.networking.ipv6_gateway** | IPv6 of he bastion's gateway server. | fd00::1 -**env.bastion.networking.ipv6_prefix** | IPv6 prefix. | 64 -**env.bastion.networking.nameserver1** | IPv4 address of the server that resolves the bastion's hostname. | 192.168.10.200 -**env.bastion.networking.nameserver2** | (Optional) A second IPv4 address that resolves the bastion's hostname. | 192.168.10.201 -**env.bastion.networking.forwarder** | What IPv4 address will be used to make external DNS calls for the bastion? Can use 1.1.1.1 or 8.8.8.8 as defaults. | 8.8.8.8 -**env.bastion.networking.interface** | Name of the networking interface on the bastion from Linux's perspective. Most likely enc1. | enc1 -**env.bastion.access.user** | What would you like the admin's username to be on the bastion? If root, make pass and root_pass vars the same. | admin -**env.bastion.access.pass** | The password to the bastion's admin user. If using root, make pass and root_pass vars the same. | cH4ngeM3! -**env.bastion.access.root_pass** | The root password for the bastion. If using root, make pass and root_pass vars the same. | R0OtPa$s! -**env.bastion.options.dns** | Would you like the bastion to host the DNS information for the cluster? True or False. If false, resolution must come from elsewhere in your environment. Make sure to add IP addresses for KVM hosts, bastion, bootstrap, control, compute nodes, AND api, api-int and *.apps as described [here](https://docs.openshift.com/container-platform/4.8/installing/installing_bare_metal/installing-bare-metal-network-customizations.html) in section "User-provisioned DNS Requirements" Table 5. If True this will be done for you in the dns and check_dns roles. | True -**env.bastion.options.loadbalancer.on_bastion** | Would you like the bastion to host the load balancer (HAProxy) for the cluster? True or False (boolean). If false, this service must be provided elsewhere in your environment, and public and private IP of the load balancer must be provided in the following two variables. | True -**env.bastion.options.loadbalancer.public_ip** | (Only required if env.bastion.options.loadbalancer.on_bastion is True). The public IPv4 address for your environment's loadbalancer. api, apps, *.apps must use this. | 192.168.10.50 -**env.bastion.options.loadbalancer.private_ip** | (Only required if env.bastion.options.loadbalancer.on_bastion is True). The private IPv4 address for your environment's loadbalancer. api-int must use this. | 10.24.17.12 +**env.bastion.create** | True or False. Would you like to create a bastion KVM guest to host essential infrastructure services like DNS, load balancer, firewall, etc? Can de-select certain services with the env.bastion.options variables below. | `True` +**env.bastion.vm_name** | Name of the bastion VM. Arbitrary value. | `'bastion'` +**env.bastion.resources.disk_size** | How much of the storage pool would you like to allocate to the bastion (in Gigabytes)? Recommended 30 or more. | `120` +**env.bastion.resources.ram** | How much memory would you like to allocate the bastion (in megabytes)? Recommended 4096 or more | `4096` +**env.bastion.resources.swap** | How much swap storage would you like to allocate the bastion (in megabytes)? Recommended 4096 or more. | `4096` +**env.bastion.resources.vcpu** | How many virtual CPUs would you like to allocate to the bastion? Recommended 4 or more. | `4` +**env.bastion.resources.vcpu_model_option** | Configure the CPU model and CPU features exposed to the guest | `"--cpu host"` +**env.bastion.networking.ip** | IPv4 address for the bastion. | `192.168.122.20` +**env.bastion.networking.internal_ip** | (Optional) Private IPv4 address for bastion required when installing LPAR cluster with HiperSocket. Currently supports only when bastion is on LPAR or on zVM host. Incase of zVM bastion enable the HiperSocket prior to the playbook run with vmcp commands on the bastion. Alternative Option would be setting up the bridge port on OSA or RoCE. | `10.42.16.1` +**env.bastion.networking.ipv6** | IPv6 address for the bastion if use_ipv6 variable is 'True'. Keep empty `''` to use default ipv6 | `'fd00::3'` +**env.bastion.networking.mac** | MAC address for the bastion if use_dhcp variable is 'True'. (Generate using: `printf 'fa:1d:67:%02d:%02d:%02d\n' $((RANDOM%100)) $((RANDOM%100)) $((RANDOM%100))`) | `'fa:1d:67:35:13:20'` +**env.bastion.networking.hostname** | Hostname of the bastion. Will be combined with env.bastion.networking.base_domain to create a Fully Qualified Domain Name (FQDN). | `'bastion'` +**env.bastion.networking.base_domain** | Base domain that, when combined with the hostname, creates a fully-qualified domain name (FQDN) for the bastion? | `example.com` +**env.bastion.networking.subnetmask** | Subnet of the bastion. | `'255.255.255.0'` +**env.bastion.networking.gateway** | IPv4 of he bastion's gateway server, (get it using ip a) | `'192.168.122.1'` +**env.bastion.networking.ipv6_gateway** | IPv6 of he bastion's gateway server. Keep empty `''` to use default ipv6_gateway | `'fd00::1'` +**env.bastion.networking.ipv6_prefix** | IPv6 prefix. Keep empty `''` to use default ipv6_prefix | `'64'` +**env.bastion.networking.nameserver1** | IPv4 address of the server that resolves the bastion's hostname. use the same IP as the bastion) | `'192.168.122.20'` +**env.bastion.networking.nameserver2** | (Optional) A second IPv4 address that resolves the bastion's hostname. | `'192.168.10.201'` +**env.bastion.networking.forwarder** | What IPv4 address will be used to make external DNS calls for the bastion? Can use 1.1.1.1 or 8.8.8.8 or 172.23.0.1 as defaults. | `'172.23.0.1'` +**env.bastion.networking.interface** | Name of the networking interface on the bastion from Linux's perspective. Most likely enc1. | `'enc1'` +**env.bastion.access.user** | What would you like the admin's username to be on the bastion? If root, make pass and root_pass vars the same. | `'admin'` +**env.bastion.access.pass** | The password to the bastion's admin user. If using root, make pass and root_pass vars the same. | `'cH4ngeM3!'` +**env.bastion.access.root_pass** | The root password for the bastion. If using root, make pass and root_pass vars the same. | `'cH4ngeM3!'` +**env.bastion.options.dns** | Would you like the bastion to host the DNS information for the cluster? True or False. If false, resolution must come from elsewhere in your environment. Make sure to add IP addresses for KVM hosts, bastion, bootstrap, control, compute nodes, AND api, api-int and *.apps as described [here](https://docs.openshift.com/container-platform/4.8/installing/installing_bare_metal/installing-bare-metal-network-customizations.html) in section "User-provisioned DNS Requirements" Table 5. If True this will be done for you in the dns and check_dns roles. | `True` +**env.bastion.options.loadbalancer.on_bastion** | Would you like the bastion to host the load balancer (HAProxy) for the cluster? True or False (boolean). If false, this service must be provided elsewhere in your environment, and public and private IP of the load balancer must be provided in the following two variables. | `True` +**env.bastion.options.loadbalancer.public_ip** | (Optional) (Only required if env.bastion.options.loadbalancer.on_bastion is True). The public IPv4 address for your environment's loadbalancer. api, apps, *.apps must use this. | 192.168.10.50 +**env.bastion.options.loadbalancer.private_ip** | (Optional) (Only required if env.bastion.options.loadbalancer.on_bastion is True). The private IPv4 address for your environment's loadbalancer. api-int must use this. | 10.24.17.12 ## 6 - Cluster Networking **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.cluster.networking.metadata_name** | Name to describe the cluster as a whole, can be anything if DNS will be hosted on the bastion. If DNS is not on the bastion, must match your DNS configuration. Will be combined with the base_domain and hostnames to create Fully Qualified Domain Names (FQDN). | ocpz -**env.cluster.networking.base_domain** | The site name, where is the cluster being hosted? This will be combined with the metadata_name and hostnames to create FQDNs. | host.com -**env.bastion.networking.ipv6_gateway** | IPv6 of he bastion's gateway server. | fd00::1 -**env.bastion.networking.ipv6_prefix** | IPv6 prefix. | 64 -**env.cluster.networking.nameserver1** | IPv4 address that the cluster get its hostname resolution from. If env.bastion.options.dns is True, this should be the IP address of the bastion. | 192.168.10.200 -**env.cluster.networking.nameserver2** | (Optional) A second IPv4 address will the cluster get its hostname resolution from? If env.bastion.options.dns is True, this should be left commented out. | 192.168.10.201 -**env.cluster.networking.forwarder** | What IPv4 address will be used to make external DNS calls for the cluster? Can use 1.1.1.1 or 8.8.8.8 as defaults. | 8.8.8.8 -**env.cluster.networking.interface** | Name of the networking interface on the bastion from Linux's perspective. Most likely enc1. | enc1 +**env.cluster.networking.metadata_name** | Name to describe the cluster as a whole, can be anything if DNS will be hosted on the bastion. If DNS is not on the bastion, must match your DNS configuration. Will be combined with the base_domain and hostnames to create Fully Qualified Domain Names (FQDN). | `agent` +**env.cluster.networking.base_domain** | The site name, where is the cluster being hosted? This will be combined with the metadata_name and hostnames to create FQDNs. | `example.com` +**env.cluster.networking.subnetmask** | Subnet of the bastion. | `'255.255.255.0'` +**env.cluster.networking.gateway** | IPv4 of he bastion's gateway server, (get it using ip a) | `'192.168.122.1'` +**env.bastion.networking.ipv6_gateway** | IPv6 of he bastion's gateway server. Keep empty `''` to use default ipv6_gateway| `'fd00::1'` +**env.bastion.networking.ipv6_prefix** | IPv6 prefix. Keep empty `''` to use default ipv6_prefix| `'64'` +**env.cluster.networking.nameserver1** | IPv4 address that the cluster get its hostname resolution from. If env.bastion.options.dns is True, this should be the IP address of the bastion. | `'192.168.122.20'` +**env.cluster.networking.nameserver2** | (Optional) A second IPv4 address will the cluster get its hostname resolution from? If env.bastion.options.dns is True, this should be left commented out. | `'192.168.122.201'` +**env.cluster.networking.forwarder** | What IPv4 address will be used to make external DNS calls for the cluster? Can use 1.1.1.1 or 8.8.8.8 or 172.23.0.1 as defaults. | `'172.23.0.1'` +**env.cluster.networking.interface** | Name of the networking interface on the bastion from Linux's perspective. Most likely enc1. | `'enc1'` -## 7 - Bootstrap Node +## 7 - (Optional) Bootstrap Node **Variable Name** | **Description** | **Example** :--- | :--- | :--- **env.cluster.nodes.bootstrap.disk_size** | How much disk space do you want to allocate to the bootstrap node (in Gigabytes)? Bootstrap node is temporary and will be brought down automatically when its job completes. 120 or more recommended. | 120 @@ -114,30 +116,30 @@ ## 8 - Control Nodes **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.cluster.nodes.control.disk_size** | How much disk space do you want to allocate to each control node (in Gigabytes)? 120 or more recommended. | 120 -**env.cluster.nodes.control.ram** | How much memory would you like to allocate to the each control node (in megabytes)? Recommended 16384 or more. | 16384 -**env.cluster.nodes.control.vcpu** | How many virtual CPUs would you like to allocate to each control node? Recommended 4 or more. | 4 -**env.cluster.nodes.control.vcpu_model_option** | Configure the CPU model and CPU features exposed to the guest | --cpu host -**env.cluster.nodes.control.vm_name** | Name of the control node VMs. Arbitrary values. Usually no more or less than 3 are used. Must match the total number of IP addresses and hostnames for control nodes. Use provided list format. | control-1control-2control-3 -**env.cluster.nodes.control.ip** | IPv4 address of the control nodes. Use provided list formatting. | 192.168.10.5192.168.10.6192.168.10.7 -**env.cluster.nodes.control.ipv6** | IPv6 address for the control nodes. Use iprovided list formatting (if use_ipv6 variable is 'True'). | fd00::5fd00::6fd00::7 -**env.cluster.nodes.control.mac** | MAC address for the control node if use_dhcp variable is 'True'. | 52:54:00:18:1A:2B -**env.cluster.nodes.control.hostname** | Hostnames for control nodes. Must match the total number of IP addresses for control nodes (usually 3). If DNS is hosted on the bastion, this can be anything. If DNS is hosted elsewhere, this must match DNS definition. This will be combined with the metadata_name and base_domain to create a Fully Qualififed Domain Name (FQDN). | control-01control-02control-03 +**env.cluster.nodes.control.disk_size** | How much disk space do you want to allocate to each control node (in Gigabytes)? 120 or more recommended. | `120` +**env.cluster.nodes.control.ram** | How much memory would you like to allocate to the each control node (in megabytes)? Recommended 16384 or more. | `16384` +**env.cluster.nodes.control.vcpu** | How many virtual CPUs would you like to allocate to each control node? Recommended 4 or more. | `4` +**env.cluster.nodes.control.vcpu_model_option** | Configure the CPU model and CPU features exposed to the guest | `"--cpu host"` +**env.cluster.nodes.control.vm_name** | Name of the control node VMs. Arbitrary values. Usually no more or less than 3 are used. Must match the total number of IP addresses and hostnames for control nodes. Use provided list format. | `'control-1','control-2','control-3'` +**env.cluster.nodes.control.ip** | IPv4 address of the control nodes. Use provided list formatting. | `'192.168.122.21','192.168.122.22','192.168.122.23'` +**env.cluster.nodes.control.ipv6** | IPv6 address for the control nodes. Use iprovided list formatting (if use_ipv6 variable is 'True'). Keep empty `''` to use default ipv6 | `'fd00::5','fd00::6','fd00::7'` +**env.cluster.nodes.control.mac** | MAC address for the control node if use_dhcp variable is 'True'. | `'fa:1d:67:35:13:31','fa:1d:67:35:13:32','fa:1d:67:35:13:33'` +**env.cluster.nodes.control.hostname** | Hostnames for control nodes. Must match the total number of IP addresses for control nodes (usually 3). If DNS is hosted on the bastion, this can be anything. If DNS is hosted elsewhere, this must match DNS definition. This will be combined with the metadata_name and base_domain to create a Fully Qualififed Domain Name (FQDN). | `'control-1','control-2','control-3'` ## 9 - Compute Nodes **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.cluster.nodes.compute.disk_size** | How much disk space do you want to allocate to each compute node (in Gigabytes)? 120 or more recommended. | 120 -**env.cluster.nodes.compute.ram** | How much memory would you like to allocate to the each compute node (in megabytes)? Recommended 16384 or more. | 16384 -**env.cluster.nodes.compute.vcpu** | How many virtual CPUs would you like to allocate to each compute node? Recommended 2 or more. | 2 -**env.cluster.nodes.compute.vcpu_model_option** | Configure the CPU model and CPU features exposed to the guest | --cpu host -**env.cluster.nodes.compute.vm_name** | Name of the compute node VMs. Arbitrary values. This list can be expanded to any number of nodes, minimum 2. Must match the total number of IP addresses and hostnames for compute nodes. Use provided list format. | compute-1compute-2 -**env.cluster.nodes.compute.ip** | IPv4 address of the compute nodes. Must match the total number of VM names and hostnames for compute nodes. Use provided list formatting. | 192.168.10.8192.168.10.9 -**env.cluster.nodes.control.ipv6** | IPv6 address for the compute nodes. Use iprovided list formatting (if use_ipv6 variable is 'True'). | fd00::8fd00::9 -**env.cluster.nodes.compute.mac** | MAC address for the compute node if use_dhcp variable is 'True'. | 52:54:00:18:1A:2B -**env.cluster.nodes.compute.hostname** | Hostnames for compute nodes. Must match the total number of IP addresses and VM names for compute nodes. If DNS is hosted on the bastion, this can be anything. If DNS is hosted elsewhere, this must match DNS definition. This will be combined with the metadata_name and base_domain to create a Fully Qualififed Domain Name (FQDN). | compute-01compute-02 +**env.cluster.nodes.compute.disk_size** | How much disk space do you want to allocate to each compute node (in Gigabytes)? 120 or more recommended. | `120` +**env.cluster.nodes.compute.ram** | How much memory would you like to allocate to the each compute node (in megabytes)? Recommended 16384 or more. | `16384` +**env.cluster.nodes.compute.vcpu** | How many virtual CPUs would you like to allocate to each compute node? Recommended 2 or more. | `2` +**env.cluster.nodes.compute.vcpu_model_option** | Configure the CPU model and CPU features exposed to the guest | `"--cpu host"` +**env.cluster.nodes.compute.vm_name** | Name of the compute node VMs. Arbitrary values. This list can be expanded to any number of nodes, minimum 2. Must match the total number of IP addresses and hostnames for compute nodes. Use provided list format. | `'compute-1','compute-2'` +**env.cluster.nodes.compute.ip** | IPv4 address of the compute nodes. Must match the total number of VM names and hostnames for compute nodes. Use provided list formatting. | `'192.168.122.24','192.168.122.25'` +**env.cluster.nodes.control.ipv6** | IPv6 address for the compute nodes. Use iprovided list formatting (if use_ipv6 variable is 'True'). Keep empty `''` to use default ipv6 | `'fd00::8','fd00::9'` +**env.cluster.nodes.compute.mac** | MAC address for the compute node if use_dhcp variable is 'True'. | `'fa:1d:67:35:13:34','fa:1d:67:35:13:35'` +**env.cluster.nodes.compute.hostname** | Hostnames for compute nodes. Must match the total number of IP addresses and VM names for compute nodes. If DNS is hosted on the bastion, this can be anything. If DNS is hosted elsewhere, this must match DNS definition. This will be combined with the metadata_name and base_domain to create a Fully Qualififed Domain Name (FQDN). | `'compute-1','compute-2'` -## 10 - Infra Nodes +## 10 - (Optional) Infra Nodes **Variable Name** | **Description** | **Example** :--- | :--- | :--- **env.cluster.nodes.infra.disk_size** | (Optional) Set up compute nodes that are made for infrastructure workloads (ingress, monitoring, logging)? How much disk space do you want to allocate to each infra node (in Gigabytes)? 120 or more recommended. | 120 @@ -149,26 +151,27 @@ **env.cluster.nodes.infra.ipv6** | (Optional) IPv6 address of the infra nodes. iThis list can be expanded to any number of nodes, minimum 2. Use provided list formatting (if use_ipv6 variable is 'True'). | fd00::10fd00::11 **env.cluster.nodes.infra.hostname** | (Optional) Hostnames for infra nodes. Must match the total number of IP addresses for infra nodes. If DNS is hosted on the bastion, this can be anything. If DNS is hosted elsewhere, this must match DNS definition. This will be combined with the metadata_name and base_domain to create a Fully Qualififed Domain Name (FQDN). | infra-01infra-02 -## 11 - (Optional) Misc +## 11 - Misc **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**env.language** | What language would you like Red Hat Enterprise Linux to use? In UTF-8 language code. Available languages and their corresponding codes can be found [here](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/5/html-single/international_language_support_guide/index), in the "Locale" column of Table 2.1. | en_US.UTF-8 -**env.timezone** | Which timezone would you like Red Hat Enterprise Linux to use? A list of available timezone options can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | America/New_York -**env.keyboard** | Which keyboard layout would you like Red Hat Enterprise Linux to use? | us -**env.ansible_key_name** | (Optional) Name of the SSH key that Ansible will use to connect to hosts. | ansible-ocpz -**env.ocp_key_name** | Comment to describe the SSH key used for OCP. Arbitrary value. | OCPZ-01 key -**env.vnet_name** | (Optional) Name of the bridged virtual network that will be created on the KVM host if network mode is not set to NAT. In case of NAT network mode the name of the NAT network definition used to create the nodes(usually it is 'default'). If NAT is being used and a jumphost is needed, the parameters network_mode, jumphost.name, jumphost.user and jumphost.pass must be specified, too. For default (NAT) network verify that the configured IP ranges does not interfere with the IPs defined for the controle and compute nodes. Modify the default network (dhcp range setting) to prevent issues with VMs using dhcp and OCP nodes having fixed IPs. Default is create a bridge network.| macvtap-net -**env.network_mode** | (Optional) In case the network mode will be NAT and the installation will be executed from remote (e.g. your laptop), a jumphost needs to be defined to let the installation access the bastion host. If macvtap for networking is being used this variable should be empty. | NAT -**env.use_ipv6** | If ipv6 addresses should be assigned to the controle and compute nodes, this variable should be true (default) and the matching ipv6 settings should be specified. | True -**env.use_dhcp** | If dhcp service should be used to get an IP address, this variable should be true and the matching mac address must be specified. | False -**env.jumphost.name** | (Optional) If env.network.mode is set to 'NAT' the name of the jumphost (e.g. the name of KVM host if used as jumphost) should be specified. | kvm-host-01 -**env.jumphost.ip** | (Optional) The ip of the jumphost. | 192.168.10.1 -**env.jumphost.user** | (Optional) The user name to login to the jumphost. | admin -**env.jumphost.pass** | (Optional) The password for user to login to the jumphost. | ch4ngeMe! -**env.jumphost.path_to_keypair** | (Optional) The absolute path to the public key file on the jumphost to be copied to the bastion. | /home/admin/.ssh/id_rsa.pub -**env.ipsec_enabled** | (Optional) If IPSEC network configuration has to be enabled, this flag should be set to true | +**env.language** | What language would you like Red Hat Enterprise Linux to use? In UTF-8 language code. Available languages and their corresponding codes can be found [here](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/5/html-single/international_language_support_guide/index), in the "Locale" column of Table 2.1. | `en_US.UTF-8` +**env.timezone** | Which timezone would you like Red Hat Enterprise Linux to use? A list of available timezone options can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | `America/New_York` +**env.keyboard** | Which keyboard layout would you like Red Hat Enterprise Linux to use? | `us` +**env.ansible_key_name** | (Optional) Name of the SSH key that Ansible will use to connect to hosts. | `ansible-ocpz` +**env.ocp_key_name** | Comment to describe the SSH key used for OCP. Arbitrary value. | `OpenShift key` +**env.vnet_name** | (Optional) Name of the bridged virtual network that will be created on the KVM host if network mode is not set to NAT. In case of NAT network mode the name of the NAT network definition used to create the nodes(usually it is 'default'). If NAT is being used and a jumphost is needed, the parameters network_mode, jumphost.name, jumphost.user and jumphost.pass must be specified, too. For default (NAT) network verify that the configured IP ranges does not interfere with the IPs defined for the controle and compute nodes. Modify the default network (dhcp range setting) to prevent issues with VMs using dhcp and OCP nodes having fixed IPs. Default is create a bridge network.| `macvtap-net` *(preferred: default)* +**env.network_mode** | In case the network mode will be NAT and the installation will be executed from remote (e.g. your laptop), a jumphost needs to be defined to let the installation access the bastion host. If macvtap for networking is being used this variable should be empty. | `NAT` +**env.use_ipv6** | If ipv6 addresses should be assigned to the controle and compute nodes, this variable should be true (default) and the matching ipv6 settings should be specified. | `True` +**env.use_dhcp** | If dhcp service should be used to get an IP address, this variable should be true and the matching mac address must be specified. | `False` +**setup_openvpn** | Enable or disable OpenVPN setup on the bastion. Set to True to configure OpenVPN, False to skip it. | `False` +**env.jumphost.name** | If env.network.mode is set to 'NAT' the name of the jumphost (e.g. the name of KVM host if used as jumphost) should be specified. To get it, run: `hostname` | `''` +**env.jumphost.ip** | The ip of the jumphost. To get it, run: `hostname -i` or `ip addr show` | `''` +**env.jumphost.user** | The user name to login to the jumphost. | `'admin'` +**env.jumphost.pass** | The password for user to login to the jumphost. | `'ch4ngeMe!'` +**env.jumphost.path_to_keypair** | The absolute path to the public key file on the jumphost to be copied to the bastion. | `'~/.ssh/id_rsa.pub'` +**env.ipsec_enabled** | (Optional) If IPSEC network configuration has to be enabled, this flag should be set to true | -## 12 - OCP and RHCOS (CoreOS) +## 12 - (Optional) OCP and RHCOS (CoreOS) * These parameters are responsible which version of OCP, RHCOS and os variant AOP is using. The default value is 'latest' for s390x architecture. I you want to install a different version or a different architecture you need to specify specify the following parameters in all.yaml file: **Variable Name** | **Description** | **Example/Default** @@ -196,15 +199,15 @@ **day2_compute_node.host_user** | KVM host user which is used to create the VM | root **day2_compute_node.host_arch** | KVM host architecture. | s390x -## 14 - (Optional) Agent Based Installer +## 14 - Agent Based Installer **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**abi.flag** | This is the flag, Will be used to identify during execution. Few checks in the playbook will be depend on this (default value will be False) | True -**abi.ansible_workdir** | This will be work directory name, it will keep required data that need to be present during or after execution | ansible_workdir -**abi.ocp_installer_version** | Version will contain value of openshift-installer binary version user desired to be used | '4.15.8' -**abi.ocp_installer_base_url** | This is the base url of openshift installer binary it will remain same as static value, User Do not need to give value until user wants to change the mirror | 'https://mirror.openshift.com/pub/openshift-v4/' -**abi.architecture** | The installer binary supports two architecture options: multi and s390x. Users are required to specify the appropriate architecture value based on their deployment environment. | 'multi/s390x' -**abi.boot_method** | Specifies the boot type for Agent-based Installation (ABI). Users must choose either iso or pxe based on the deployment method. Note: iso boot is supported only on KVM platforms. | 'iso/pxe' +**abi.flag** | This is the flag, Will be used to identify during execution. Few checks in the playbook will be depend on this (default value will be False) | `True` +**abi.ansible_workdir** | This will be work directory name, it will keep required data that need to be present during or after execution | `'ansible_workdir'` +**abi.ocp_installer_version** | Version will contain value of openshift-installer binary version user desired to be used | `'4.19.19'` +**abi.ocp_installer_base_url** | This is the base url of openshift installer binary it will remain same as static value, User Do not need to give value until user wants to change the mirror | `'https://mirror.openshift.com/pub/openshift-v4/'` +**abi.architecture** | The installer binary supports two architecture options: multi and s390x. Users are required to specify the appropriate architecture value based on their deployment environment. | `'multi/s390x'` +**abi.boot_method** | Specifies the boot type for Agent-based Installation (ABI). Users must choose either iso or pxe based on the deployment method. Note: iso boot is supported only on KVM platforms. | `'iso/pxe'` ## OpenShift Settings * The parameters bellow have a hierachical structure and need to be added to all.yaml in given format. For example if you want to change the hyperthreading (disable) than you need to specify the following value in all.yaml file: @@ -403,3 +406,4 @@ **zvm.interface.ip** | IP addresses for to be used for zVM nodes | 192.168.10.1 **zvm.nodes.dasd.disk_id** | Disk id for dasd disk to be used for zVM node | 4404 **zvm.nodes.lun** | Disk details of fcp disk to be used for zVM node | 840a + diff --git a/docs/set-variables-host-vars.md b/docs/set-variables-host-vars.md index abe35ae4..aebaa9d8 100644 --- a/docs/set-variables-host-vars.md +++ b/docs/set-variables-host-vars.md @@ -13,20 +13,20 @@ ## 1 - KVM Host **Variable Name** | **Description** | **Example** :--- | :--- | :--- -**networking.hostname** | The hostname of the LPAR with RHEL installed natively (the KVM host). | kvm-host-01 -**networking.ip** | The IPv4 address of the LPAR with RHEL installed natively (the KVM host). | 192.168.10.2 -**networking.internal_ip** | The internal IPv4 address of the LPAR required when booting the LPAR with HiperSocket card. Currently supports only when bastion is on LPAR or on zVM host. Incase of zVM bastion enable the HiperSocket card prior to the playbook run with vmcp commands on the bastion. Alternative Option would be setting up the bridge port on OSA or RoCE.| 10.42.6.2 -**networking.mode** | Type of network card | osa/roce/hipersocket -**networking.ipv6** | IPv6 address for the bastion if use_ipv6 variable is 'True'. | fd00::3 -**networking.subnetmask** | The subnet that the LPAR resides in within your network. | 255.255.255.0 -**networking.gateway** | The IPv4 address of the gateway to the network where the KVM host resides. | 192.168.10.0 -**networking.ipv6_gateway** | IPv6 of he bastion's gateway server. | fd00::1 -**networking.ipv6_prefix** | IPv6 prefix. | 64 -**networking.nameserver1** | The IPv4 address from which the KVM host gets its hostname resolved. | 192.168.10.200 +**networking.hostname** | The hostname of the LPAR with RHEL installed natively (the KVM host). To get it, run: `hostname`| `` +**networking.ip** | The IPv4 address of the LPAR with RHEL installed natively (the KVM host). To get it, run: `hostname -i` or `ip addr show` | `''` +**networking.internal_ip** | (Optional) The internal IPv4 address of the LPAR required when booting the LPAR with HiperSocket card. Currently supports only when bastion is on LPAR or on zVM host. Incase of zVM bastion enable the HiperSocket card prior to the playbook run with vmcp commands on the bastion. Alternative Option would be setting up the bridge port on OSA or RoCE.| 10.42.6.2 +**networking.mode** | (Optional) Type of network card | osa/roce/hipersocket +**networking.ipv6** | IPv6 address for the bastion if use_ipv6 variable is 'True'. Keep empty `''` to use default ipv6 | `'fd00::3'` +**networking.subnetmask** | The subnet that the LPAR resides in within your network. | `255.255.255.0` +**networking.gateway** | The IPv4 address of the gateway to the network where the KVM host resides, (get it using ip a) | `192.168.122.1` +**networking.ipv6_gateway** | IPv6 of he bastion's gateway server. Keep empty `''` to use default ipv6 gateway | `'fd00::1'` +**networking.ipv6_prefix** | IPv6 prefix. Keep empty `''` to use default ipv6 gateway | `'64'` +**networking.nameserver1** | The IPv4 address from which the KVM host gets its hostname resolved. | `192.168.122.20` **networking.nameserver2** | (Optional) A second IPv4 address from which the KVM host can get its hostname resolved. Used for high availability. | 192.168.10.201 -**networking.device1** | The network interface card from Linux's perspective. Usually enc and then a number that comes from the dev_num of the network adapter. | enc100 +**networking.device1** | The network interface card from Linux's perspective. Usually enc and then a number that comes from the dev_num of the network adapter. | `enc100` **networking.device2** | (Optional) Another Linux network interface card. Usually enc and then a number that comes from the dev_num of the second network adapter. | enc1 -**storage.pool_path** | The absolute path to a directory on your KVM host that will be used to store qcow2 images for the cluster and other installation artifacts. A sub-directory will be created here that matches your clsuter's metadata name that will act as the cluster's libvirt storage pool directory. Note: all directories present in this path will be made executable for the 'qemu' group, as is required. | /home/kvm_admin/VirtualMachines +**storage.pool_path** | The absolute path to a directory on your KVM host that will be used to store qcow2 images for the cluster and other installation artifacts. A sub-directory will be created here that matches your clsuter's metadata name that will act as the cluster's libvirt storage pool directory. Note: all directories present in this path will be made executable for the 'qemu' group, as is required. | `/home/kvm_admin/VirtualMachines` ## Important Note * You can skip the rest of the variables on this page IF you are using existing LPAR(s) that has RHEL already installed. @@ -100,3 +100,4 @@ **lpar.livedisk.wwpn** | (Required if livedisktype is scsi) World-wide port number when livedisktype is SCSI. | 500507630a1b50a4 **lpar.livedisk.devicenr** | (Optional) the device no of the live disk | c6h1 **lpar.livedisk.livedisk_root_pass** | (Optional) root password for the livedisk | p@ssword +