From 3b55e41c43614b46cf61115e51053317e27b2155 Mon Sep 17 00:00:00 2001 From: Richard Su Date: Thu, 21 Aug 2025 17:18:02 -0400 Subject: [PATCH 1/4] AGENT-1253: Interactive Installation using the Agent Based Installer for Disconnected Environments This enhancement proposes how to simplify cluster installations in a disconnected environment using a UI-driven approach leveraging the Agent Based and Assisted Installer technologies. A new image named agent-installer-ui will be added to the OpenShift release payload. --- ...installer-for-disconnected-environments.md | 261 ++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md diff --git a/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md new file mode 100644 index 0000000000..7de535b266 --- /dev/null +++ b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md @@ -0,0 +1,261 @@ +--- +title: interactive-installation-using-the-agent-based-installer-for-disconnected-environments +authors: + - "@rwsu" +reviewers: # Include a comment about what domain expertise a reviewer is expected to bring and what area of the enhancement you expect them to focus on. For example: - "@networkguru, for networking aspects, please look at IP bootstrapping aspect" + - "@andfasano" + - "@bfournie" + - "@pawanpinjarkar" + - "@danielerez" + - "@rawagner" +approvers: # A single approver is preferred, the role of the approver is to raise important questions, help ensure the enhancement receives reviews from all applicable areas/SMEs, and determine when consensus is achieved such that the EP can move forward to implementation. Having multiple approvers makes it difficult to determine who is responsible for the actual approval. + - "@zaneb" +api-approvers: # In case of new or modified APIs or API extensions (CRDs, aggregated apiservers, webhooks, finalizers). If there is no API change, use "None" + - None +creation-date: 2025-09-16 +last-updated: 2025-09-16 +tracking-link: # link to the tracking ticket (for example: Jira Feature or Epic ticket) that corresponds to this enhancement + - https://issues.redhat.com/browse/VIRTSTRAT-60 + - https://issues.redhat.com/browse/OCPSTRAT-1874 + - https://issues.redhat.com/browse/OCPSTRAT-1985 +see-also: + - "https://github.com/openshift/enhancements/pull/1821" +replaces: + - +superseded-by: + - +--- + +# Interactive Installation using the Agent Based Installer for Disconnected Environments + +## Summary + +This enhancement proposes the creation of a streamlined, interactive, and +UI-driven installation workflow leveraging the Agent Based Installer and the +Assisted Installer service targeted for disconnected environments. The goal +is to address the complexity of the current installation process, which can +be challenging for users who are not accustomed to command-line tools and +manual configuration files. By providing an opinionated, user-friendly UI, +this initiative aims to simplify cluster setup and reduce the potential for +errors. + +## Motivation + +The installation process for a new cluster can be complex, involving multiple +prerequisites and manual configuration steps that are challenging and +time-consuming for some users. Customers, especially those accustomed to +graphical interfaces, often struggle with writing YAML files and ensuring they +are configured correctly. This proposal seeks to deliver an improved user +experience by abstracting away this complexity behind a simple, guided UI. + +### User Stories + +* As an administrator, I want a simple, UI-driven workflow to install a +cluster, so I can easily set up a new environment without needing to write +or manage complex YAML configuration files. + +* As an administrator deploying a cluster, I want to configure all necessary +settings, such as networking and topology interactively through a UI, so that +I can avoid common configuration errors and reduce setup time. + +* As an administrator, I want the installer to help me pre-configure and +install essential operators during cluster setup, so the cluster is ready for +my workloads immediately after installation. + +### Goals + +* Provide a user-friendly, UI-driven installation experience in a disconnected +environment that leverages the existing Agent Based Installer and Assisted +Installer technologies. + +* Simplify the installation process to reduce complexity, especially for users +who prefer graphical interfaces. + +* Allow for the selection and pre-configuration of essential operators as part +of the installation workflow. + +### Non-Goals + +* This proposal does not aim to replace existing installation methods but to +provide a simplified alternative for specific user personas. + +* Post-installation cluster management and day-2 operations are out of scope +for this enhancement. + +* Securing the communication between the Assisted Installer UI, Assisted +Service, and client browsers will be addressed in future updates. + +## Proposal + +This enhancement proposes extending the functionality of the Agent Based +Installer to support a fully interactive, UI-based installation flow. The +core of this proposal is to create a guided workflow within the UI that +captures all necessary configuration details from the user, which are then +used by Assisted Service to orchestrate the cluster deployment. + +The UI will be deployed on the rendezvous host. The UI will inherit some of +the interface used by the cloud-based Assisted Installer. The UI will collect +crucial information to configure the cluster. The UI will provide host +verification to ensure the hardware inventory fulfill the cluster topology. +It will also check network connectivity between the hosts. The workflow will +also include a mechanism to select and bundle common operators, ensuring they +are installed and configured alongside the cluster itself. + +### Workflow Description + +**cluster creator** is a human user responsible for deploying a cluster. + +**UI** is the assisted-installer UI used to configure, initiate, and monitor +the cluster installation. It is hosted on the rendezvous host. + +**rendezvous host** is a host designated by the cluster creator using the +agent-tui during boot. The assisted-service and assisted-installer UI runs on +this host. It also serves as the bootstrap node. + +**agent TUI** A terminal user interface that is displayed on all hosts during +boot that allows a user to set the rendezvous host IP. + +**console UI** is the installed cluster's UI. + +1. The cluster creater begins by using the installer tooling to generate a +bootable ISO. + +2. The cluster creater boots the ISO on target cluster hosts. + +3. The cluster creator chooses one of the hosts to be the rendezvous host. + +4. All hosts boot into the agent TUI. On the rendezvous host, the cluster creater +designates it as such by setting that host's IP address as the rendezvous IP. +On the remaining hosts, the cluster create enters the rendezvous host's IP so +that the assisted installer agents knows where to contact assisted-service to +register itself. + +5. When the rendezvous host completes booting, the URL to the UI is displayed +on the console. + +6. On a separate machine the cluster creater opens up the browser to the +assisted-installer UI running on the rendezvous host. + +7. The cluster creator begins configuring the cluster through the UI. The +cluster creator is guided through a series of steps to configure the cluster +starting with cluster name, base domain, and pull secret. Optional operators +may be selected to be included in the installation. + +8. The UI then displays all the hosts that have registered with assisted service +detailing their hardware inventory and status. A role may be selected for each host +with the exception of the rendezvous host. Or it may be left as auto-assign. +When the required number of roles have registered and validated to have the +required resources and network connectivity, the cluster creator can navigate +to the next screen, networking. + +10. On the networking screen, the cluster creator selects the desired method of +network management (Cluster-Managed or User-Managed) and enters the machine +network, API IP, and ingress IP. A SSH public key may be entered to allow +troubleshooting after installation. Assisted-service validates the inputs and +displays warnings if there are any configuration issues. + +11. If there are no configuration issues, the cluster creator moves to the download +credentials screen and downloads files containing the kubeconfig and kubeadmin +password. + +12. Then the UI shows a confirmation screen showing the configuration that was +entered and a list of operators that will be enabled. The cluster creator +clicks on a button to begin the installation. + +13. The UI shows the installation progress. When the installation reaches the +point when the rendezvous host is rebooted and will join the cluster as a node, +the UI will display the URL to the cluster's console UI. + +14. The cluster creator then verifies the installation is complete by using the +console UI or the creator can use the kubeconfig that was downloaded and the +oc commands: "oc get clusterversion", "oc get co", and "oc get nodes" to verify +the cluster and operators have finished installing. + +### API Extensions + +There are no changes to APIs. + +### Topology Considerations + +Will function identically in all topologies. + +#### Hypershift / Hosted Control Planes + +There are no specific considerations for this feature regarding +Hypershift / Hosted Control Planes. + +#### Standalone Clusters + +There are no specific considerations for this feature regarding +Standalone Clusters. + +#### Single-node Deployments or MicroShift + +The same workflow applies to SNO. + +There is no specific considerations for this feature regarding +MicroShift. + +### Implementation Details/Notes/Constraints + +No additional details. + +### Risks and Mitigations + +Communications between the agent running on all nodes and assisted-service +running on the redenzvous host are currently unsecured. Authentication and +authorization will need to be added in the future. + +### Drawbacks + +None. + +## Alternatives (Not Implemented) + +None. + +## Test Plan + +The entire installation flow from creation of the boot ISO to initiating the +install through the assisted-installer UI and verifying the cluster and +additional operators have been installed will be included in a e2e test in +OpenShift CI. + +[dev-scripts](https://github.com/openshift-metal3/dev-scripts) will be +enhanced to test this scenario. + +## Graduation Criteria + +### Dev Preview -> Tech Preview + +- Ability to utilize the enhancement end to end +- End user documentation +- Sufficient test coverage +- Gather feedback from users rather than just developers +- Integration with the official Red Hat build and release pipeline + +### Tech Preview -> GA + +- Complete e2e testing for installation. +- User facing documentation created in [openshift-docs](https://github.com/openshift/openshift-docs/) + +### Removing a deprecated feature + +Not applicable. + +## Upgrade / Downgrade Strategy + +Not applicable. + +## Version Skew Strategy + +Not applicable. + +## Operational Aspects of API Extensions + +Not applicable. + +## Support Procedures + +Not applicable. + From 73bab74a9e04eefcf03236d6054e91695c68169d Mon Sep 17 00:00:00 2001 From: Richard Su Date: Mon, 22 Sep 2025 16:09:08 -0400 Subject: [PATCH 2/4] Add feedback from Andrea and Pawan. --- ...installer-for-disconnected-environments.md | 114 +++++++----------- 1 file changed, 45 insertions(+), 69 deletions(-) diff --git a/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md index 7de535b266..3654222402 100644 --- a/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md +++ b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md @@ -31,8 +31,8 @@ superseded-by: ## Summary This enhancement proposes the creation of a streamlined, interactive, and -UI-driven installation workflow leveraging the Agent Based Installer and the -Assisted Installer service targeted for disconnected environments. The goal +UI-driven installation workflow leveraging the Agent Based Installer (ABI) and +the Assisted Installer service targeted for disconnected environments. The goal is to address the complexity of the current installation process, which can be challenging for users who are not accustomed to command-line tools and manual configuration files. By providing an opinionated, user-friendly UI, @@ -89,87 +89,63 @@ Service, and client browsers will be addressed in future updates. This enhancement proposes extending the functionality of the Agent Based Installer to support a fully interactive, UI-based installation flow. The -core of this proposal is to create a guided workflow within the UI that -captures all necessary configuration details from the user, which are then -used by Assisted Service to orchestrate the cluster deployment. - -The UI will be deployed on the rendezvous host. The UI will inherit some of -the interface used by the cloud-based Assisted Installer. The UI will collect -crucial information to configure the cluster. The UI will provide host -verification to ensure the hardware inventory fulfill the cluster topology. -It will also check network connectivity between the hosts. The workflow will -also include a mechanism to select and bundle common operators, ensuring they -are installed and configured alongside the cluster itself. +core of this proposal is to reuse and adapt the already existing Saas UI and +tailor it for ABI use cases where a user can install no more than one cluster. +The UI captures all necessary configuration details from the user, which are +then used by Assisted Service to orchestrate the cluster deployment. The UI +can be used to start an installation from scratch or from a partially +configured environment. + +The UI will be deployed on the rendezvous host as a container using a new image +to be included in the release payload. A console message will provide users +with the UI's URL. The UI will collect crucial information to configure the +cluster and provide host verification to ensure the hardware inventory fulfill +the cluster topology. It will also check network connectivity between the hosts. +The workflow will also include a mechanism to select and bundle common +operators, ensuring they are installed and configured alongside the cluster +itself. ### Workflow Description -**cluster creator** is a human user responsible for deploying a cluster. - -**UI** is the assisted-installer UI used to configure, initiate, and monitor -the cluster installation. It is hosted on the rendezvous host. - -**rendezvous host** is a host designated by the cluster creator using the -agent-tui during boot. The assisted-service and assisted-installer UI runs on -this host. It also serves as the bootstrap node. +This workflow is activated when the sentinel file, /etc/assisted/interactive-ui, +is present in the Agent Based Installer ignition. -**agent TUI** A terminal user interface that is displayed on all hosts during -boot that allows a user to set the rendezvous host IP. +**cluster creator** is a human user responsible for deploying a cluster. -**console UI** is the installed cluster's UI. +**Assisted Installer UI** is UI used to configure, initiate, and monitor the +cluster installation. It is hosted on the rendezvous host. -1. The cluster creater begins by using the installer tooling to generate a -bootable ISO. +**rendezvous host** is a host on the cluster that serves the Assisted Service and +Assisted installer UI. It also serves as the bootstrap node before it reboots +during cluster installation to become a member of the cluster. -2. The cluster creater boots the ISO on target cluster hosts. +**OCP console** is the installed cluster's UI. -3. The cluster creator chooses one of the hosts to be the rendezvous host. +1. The cluster creator obtains or generates an ISO and boots it on target +cluster hosts. -4. All hosts boot into the agent TUI. On the rendezvous host, the cluster creater -designates it as such by setting that host's IP address as the rendezvous IP. -On the remaining hosts, the cluster create enters the rendezvous host's IP so -that the assisted installer agents knows where to contact assisted-service to -register itself. - -5. When the rendezvous host completes booting, the URL to the UI is displayed -on the console. - -6. On a separate machine the cluster creater opens up the browser to the -assisted-installer UI running on the rendezvous host. +2. The URL to the Assisted Installer UI running on a predefined port is +displayed on the console. -7. The cluster creator begins configuring the cluster through the UI. The -cluster creator is guided through a series of steps to configure the cluster -starting with cluster name, base domain, and pull secret. Optional operators -may be selected to be included in the installation. - -8. The UI then displays all the hosts that have registered with assisted service -detailing their hardware inventory and status. A role may be selected for each host -with the exception of the rendezvous host. Or it may be left as auto-assign. -When the required number of roles have registered and validated to have the -required resources and network connectivity, the cluster creator can navigate -to the next screen, networking. +3. On a separate machine the cluster creator opens up the browser to the +Assisted Installer UI running on the rendezvous host. -10. On the networking screen, the cluster creator selects the desired method of -network management (Cluster-Managed or User-Managed) and enters the machine -network, API IP, and ingress IP. A SSH public key may be entered to allow -troubleshooting after installation. Assisted-service validates the inputs and -displays warnings if there are any configuration issues. +4. The cluster creator begins configuring the cluster through the Assisted +Installer UI, by providing all the required details. -11. If there are no configuration issues, the cluster creator moves to the download -credentials screen and downloads files containing the kubeconfig and kubeadmin -password. +5. If there are no configuration issues, the cluster creator moves to the +download credentials screen and downloads files containing the kubeconfig and +kubeadmin password. -12. Then the UI shows a confirmation screen showing the configuration that was -entered and a list of operators that will be enabled. The cluster creator -clicks on a button to begin the installation. +6. Then the Assisted Installer UI shows a confirmation screen showing the +configuration that was entered and a list of operators that will be enabled. +The cluster creator clicks on a button to begin the installation. -13. The UI shows the installation progress. When the installation reaches the -point when the rendezvous host is rebooted and will join the cluster as a node, -the UI will display the URL to the cluster's console UI. +7. The Assisted Installer UI shows the installation progress. When the +installation reaches the point when the rendezvous host is rebooted and will +join the cluster as a node, the UI will display the URL to the OCP console. -14. The cluster creator then verifies the installation is complete by using the -console UI or the creator can use the kubeconfig that was downloaded and the -oc commands: "oc get clusterversion", "oc get co", and "oc get nodes" to verify -the cluster and operators have finished installing. +8. When ready, users may access the OCP console. ### API Extensions @@ -217,7 +193,7 @@ None. ## Test Plan The entire installation flow from creation of the boot ISO to initiating the -install through the assisted-installer UI and verifying the cluster and +install through the Assisted Installer UI and verifying the cluster and additional operators have been installed will be included in a e2e test in OpenShift CI. From e01d3cbecf658567cd5ac26c10e89586c81f9990 Mon Sep 17 00:00:00 2001 From: Richard Su Date: Thu, 25 Sep 2025 15:27:24 -0400 Subject: [PATCH 3/4] Removed operators from goal --- ...-the-agent-based-installer-for-disconnected-environments.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md index 3654222402..1f80811f29 100644 --- a/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md +++ b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md @@ -70,9 +70,6 @@ Installer technologies. * Simplify the installation process to reduce complexity, especially for users who prefer graphical interfaces. - -* Allow for the selection and pre-configuration of essential operators as part -of the installation workflow. ### Non-Goals From 8fd6a6821a469d5ae53810c44a753f4c46d61abc Mon Sep 17 00:00:00 2001 From: Richard Su Date: Thu, 9 Oct 2025 22:43:20 -0400 Subject: [PATCH 4/4] Add additional non goal --- ...-the-agent-based-installer-for-disconnected-environments.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md index 1f80811f29..47d7c60edc 100644 --- a/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md +++ b/enhancements/agent-installer/interactive-installation-using-the-agent-based-installer-for-disconnected-environments.md @@ -82,6 +82,9 @@ for this enhancement. * Securing the communication between the Assisted Installer UI, Assisted Service, and client browsers will be addressed in future updates. +* Adding UI support to the current ABI flow (starting with install-config and +then switching to UI post-boot) . + ## Proposal This enhancement proposes extending the functionality of the Agent Based