OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Installing with the Assisted Installer

Preinstallation considerations

Before installing OpenShift Container Platform with the Assisted Installer, you must consider the following configuration choices:

  • Which base domain to use

  • Which OpenShift Container Platform product version to install

  • Whether to install a full cluster or single-node OpenShift

  • Whether to use a DHCP server or a static network configuration

  • Whether to use IPv4 or dual-stack networking

  • Whether to install OpenShift Virtualization

  • Whether to install Red Hat OpenShift Data Foundation

  • Whether to integrate with vSphere when installing on vSphere

Setting the cluster details

To create a cluster with the Assisted Installer web user interface, use the following procedure.

Procedure

  1. Log in to the RedHat Hybrid Cloud Console.

  2. In the menu, click OpenShift.

  3. Click Create cluster.

  4. Click the Datacenter tab.

  5. Under the Assisted Installer section, select Create cluster.

  6. Enter a name for the cluster in the Cluster name field.

  7. Enter a base domain for the cluster in the Base domain field. All subdomains for the cluster will use this base domain.

    The base domain must be a valid DNS name. You must not have a wild card domain set up for the base domain.

  8. Select the version of OpenShift Container Platform to install.

  9. Optional: Select Install single node Openshift (SNO) if you want to install OpenShift Container Platform on a single node.

  10. Optional: The Assisted Installer already has the pull secret associated to your account. If you want to use a different pull secret, select Edit pull secret.

  11. Optional: Assisted Installer defaults to using x86_64 CPU architecture. If you are installing OpenShift Container Platform on 64-bit ARM CPUs, select Use arm64 CPU architecture. Keep in mind, some features are not available with ARM64 CPU architecture.

  12. Optional: If you are using a static IP configuration for the cluster nodes instead of DHCP reservations, select Static network configuration.

  13. Optional: If you want to enable encryption of the installation disks, select Enable encryption of installation disks. For multi-node clusters, you can choose to encrypt the control plane and worker node installation disks separately.

You cannot change the base domain, the SNO checkbox, the CPU architecture, the host’s network configuration, or the disk-encryption after installation begins.

Optional: Configuring host network interfaces

The Assisted Installer supports IPv4 networking and dual stack networking. The Assisted Installer also supports configuring host network interfaces with the NMState library, a declarative network manager API for hosts. You can use NMState to deploy hosts with static IP addressing, bonds, VLANs and other advanced networking features. If you chose to configure host network interfaces, you must set network-wide configurations. Then, you must create a host-specific configuration for each host and generate the discovery ISO with the host-specific settings.

Procedure

  1. Select the internet protocol version. Valid options are IPv4 and Dual stack.

  2. If the cluster hosts are on a shared VLAN, enter the VLAN ID.

  3. Enter the network-wide IP addresses. If you selected Dual stack networking, you must enter both IPv4 and IPv6 addresses.

    1. Enter the cluster network’s IP address range in CIDR notation.

    2. Enter the default gateway IP address.

    3. Enter the DNS server IP address.

  4. Enter the host-specific configuration.

    1. If you are only setting a static IP address that uses a single network interface, use the form view to enter the IP address and the MAC address for the host.

    2. If you are using multiple interfaces, bonding, or other advanced networking features, use the YAML view and enter the desired network state for the host using NMState syntax.

    3. Add the MAC address and interface name for each interface used in your network configuration.

Additional resources

Adding hosts to the cluster

You must add one or more hosts to the cluster. Adding a host to the cluster involves generating a discovery ISO. The discovery ISO runs Red Hat Enterprise Linux CoreOS (RHCOS) in-memory with an agent. Perform the following procedure for each host on the cluster.

Procedure

  1. Click the Add hosts button and select the installation media.

    1. Select Minimal image file: Provision with virtual media to download a smaller image that will fetch the data needed to boot. The nodes must have virtual media capability. This is the recommended method.

    2. Select Full image file: Provision with physical media to download the larger full image.

  2. Add an SSH public key so that you can connect to the cluster nodes as the core user. Having a login to the cluster nodes can provide you with debugging information during the installation.

  3. Optional: If the cluster hosts are behind a firewall that requires the use of a proxy, select Configure cluster-wide proxy settings. Enter the username, password, IP address and port for the HTTP and HTTPS URLs of the proxy server.

  4. Click Generate Discovery ISO.

  5. Download the discovery ISO.

Creating an ISO image on a USB drive

You can install software using a USB drive that contains an ISO image. Starting the server with the USB drive prepares the server for the software installation.

Procedure

  1. On the administration host, insert a USB drive into a USB port.

  2. Create an ISO image on the USB drive, for example:

    # dd if=<path_to_iso> of=<path_to_usb> status=progress

    where:

    <path_to_iso>

    is the relative path to the downloaded ISO file, for example, rhcos-live.iso.

    <path_to_usb>

    is the location of the connected USB drive, for example, /dev/sdb.

    After the ISO is copied to the USB drive, you can use the USB drive to install software on the server.

Booting with a USB drive

To register nodes with the Assisted Installer using a bootable USB drive, use the following procedure.

Procedure

  1. Attach the RHCOS discovery ISO to the target host.

  2. Configure the boot drive order in the server BIOS settings to boot from the attached discovery ISO, and then reboot the server.

  3. On the administration host, return to the browser. Wait for the host to appear in the list of discovered hosts.

Booting from an HTTP-hosted ISO image using the Redfish API

You can provision hosts in your network using ISOs that you install using the Redfish Baseboard Management Controller (BMC) API.

Prerequisites

  1. Download the installation Red Hat Enterprise Linux CoreOS (RHCOS) ISO.

Procedure

  1. Copy the ISO file to an HTTP server accessible in your network.

  2. Boot the host from the hosted ISO file, for example:

    1. Call the redfish API to set the hosted ISO as the VirtualMedia boot media by running the following command:

      $ curl -k -u <bmc_username>:<bmc_password> -d '{"Image":"<hosted_iso_file>", "Inserted": true}' -H "Content-Type: application/json" -X POST <host_bmc_address>/redfish/v1/Managers/iDRAC.Embedded.1/VirtualMedia/CD/Actions/VirtualMedia.InsertMedia

      Where:

      <bmc_username>:<bmc_password>

      Is the username and password for the target host BMC.

      <hosted_iso_file>

      Is the URL for the hosted installation ISO, for example: http://webserver.example.com/rhcos-live-minimal.iso. The ISO must be accessible from the target host machine.

      <host_bmc_address>

      Is the BMC IP address of the target host machine.

    2. Set the host to boot from the VirtualMedia device by running the following command:

      $ curl -k -u <bmc_username>:<bmc_password> -X PATCH -H 'Content-Type: application/json' -d '{"Boot": {"BootSourceOverrideTarget": "Cd", "BootSourceOverrideMode": "UEFI", "BootSourceOverrideEnabled": "Once"}}' <host_bmc_address>/redfish/v1/Systems/System.Embedded.1

    3. Reboot the host:

      $ curl -k -u <bmc_username>:<bmc_password> -d '{"ResetType": "ForceRestart"}' -H 'Content-type: application/json' -X POST <host_bmc_address>/redfish/v1/Systems/System.Embedded.1/Actions/ComputerSystem.Reset

    4. Optional: If the host is powered off, you can boot it using the {"ResetType": "On"} switch. Run the following command:

      $ curl -k -u <bmc_username>:<bmc_password> -d '{"ResetType": "On"}' -H 'Content-type: application/json' -X POST <host_bmc_address>/redfish/v1/Systems/System.Embedded.1/Actions/ComputerSystem.Reset
Additional resources

Configuring hosts

After booting the hosts with the discovery ISO, the hosts will appear in the table at the bottom of the page. You can configure the hostname, role, and installation disk for each host.

Procedure

  1. Select a host.

  2. From the Actions list, select Change hostname. You must ensure each host has a valid and unique hostname. If necessary, enter a new name for the host and click Change.

  3. For multi-host clusters, in the Role column next to the host name, you can click on the menu to change the role of the host.

    If you do not select a role, the Assisted Installer will assign the role automatically. The minimum hardware requirements for control plane nodes exceed that of worker nodes. If you assign a role to a host, ensure that you assign the control plane role to hosts that meet the minimum hardware requirements.

  4. To the left of the checkbox next to a host name, click to expand the host details. If you have multiple disk drives, you can select a different disk drive to act as the installation disk.

  5. Repeat this procedure for each host.

Once all cluster hosts appear with a status of Ready, proceed to the next step.

Configuring networking

Before installing OpenShift Container Platform, you must configure the cluster network.

Procedure

  1. In the Networking page, select one of the following if it is not already selected for you:

    • Cluster-Managed Networking: Selecting cluster-managed networking means that the Assisted Installer will configure a standard network topology, including keepalived and Virtual Router Redundancy Protocol (VRRP) for managing the API and Ingress VIP addresses.

    • User-Managed Networking: Selecting user-managed networking allows you to deploy OpenShift Container Platform with a non-standard network topology. For example, if you want to deploy with an external load balancer instead of keepalived and VRRP, or if you intend to deploy the cluster nodes across many distinct L2 network segments.

  2. For cluster-managed networking, configure the following settings:

    1. Define the Machine network. You can use the default network or select a subnet.

    2. Define an API virtual IP. An API virtual IP provides an endpoint for all users to interact with, and configure the platform.

    3. Define an Ingress virtual IP. An Ingress virtual IP provides an endpoint for application traffic flowing from outside the cluster.

  3. For user-managed networking, configure the following settings:

    1. Select your Networking stack type:

      • IPv4: Select this type when your hosts are only using IPv4.

      • Dual-stack: You can select dual-stack when your hosts are using IPv4 together with IPv6.

    2. Define the Machine network. You can use the default network or select a subnet.

    3. Define an API virtual IP. An API virtual IP provides an endpoint for all users to interact with, and configure the platform.

    4. Define an Ingress virtual IP. An Ingress virtual IP provides an endpoint for application traffic flowing from outside the cluster.

    5. Optional: You can select Allocate IPs via DHCP server to automatically allocate the API IP and Ingress IP using the DHCP server.

  4. Optional: Select Use advanced networking to configure the following advanced networking properties:

    • Cluster network CIDR: Define an IP address block from which Pod IP addresses are allocated.

    • Cluster network host prefix: Define a subnet prefix length to assign to each node.

    • Service network CIDR: Define an IP address to use for service IP addresses.

    • Network type: Select either Software-Defined Networking (SDN) for standard networking or Open Virtual Networking (OVN) for telco features.

Installing the cluster

After you have completed the configuration and all the nodes are Ready, you can begin installation. The installation process takes a considerable amount of time, and you can monitor the installation from the Assisted Installer web console. Nodes will reboot during the installation, and they will initialize after installation.

Procedure

  • Press Begin installation.

    1. Click on the link in the Status column of the Host Inventory list to see the installation status of a particular host.

Completing the installation

After the cluster is installed and initialized, the Assisted Installer indicates that the installation is finished. The Assisted Installer provides the console URL, the kubeadmin username and password, and the kubeconfig file. Additionally, the Assisted Installer provides cluster details including the OpenShift Container Platform version, base domain, CPU architecture, API and Ingress IP addresses, and the cluster and service network IP addresses.

Prerequisites

  • You have installed the oc CLI tool.

Procedure

  1. Make a copy of the kubeadmin username and password.

  2. Download the kubeconfig file and copy it to the auth directory under your working directory:

    $ mkdir -p <working_directory>/auth
    $ cp kubeadmin <working_directory>/auth

    The kubeconfig file is available for download for 24 hours after completing the installation.

  3. Add the kubeconfig file to your environment:

    $ export KUBECONFIG=<your working directory>/auth/kubeconfig

  4. Login with the oc CLI tool:

    $ oc login -u kubeadmin -p <password>

    Replace <password> with the password of the kubeadmin user.

  5. Click on the web console URL or click Launch OpenShift Console to open the console.

  6. Enter the kubeadmin username and password. Follow the instructions in the OpenShift Container Platform console to configure an identity provider and configure alert receivers.

  7. Add a bookmark of the OpenShift Container Platform console.

Additional resources