From 20e51f8f91e2061d1e7b272ca90f806c408af21e Mon Sep 17 00:00:00 2001 From: ambertra Date: Fri, 2 May 2025 14:40:21 -0700 Subject: [PATCH 1/4] Update index.rst --- .../on_prem_get_started/index.rst | 320 ++++++++++++++++-- 1 file changed, 295 insertions(+), 25 deletions(-) diff --git a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst index a5dbbc0a..285a3564 100644 --- a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst +++ b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst @@ -1,25 +1,295 @@ -Get Started -=============== -This section contains the foundational steps like prerequisites, system requirement, installations, and configurations to deploy Edge Orchestrator on-prem. -Following are the sections: - -- :doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/system_requirements_on_prem_orch` -- :doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_certs` -- :doc:`/shared/shared_gs_preinstall` -- :doc:`/shared/shared_traefik_rate_limit` -- :doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_install` -- :doc:`/shared/shared_gs_iam` -- :doc:`/shared/shared_mt_overview` -- :doc:`/shared/shared_next_steps` - -.. toctree:: - :hidden: - - system_requirements_on_prem_orch - on_prem_certs - ../../../shared/shared_gs_preinstall - ../../../shared/shared_traefik_rate_limit - on_prem_install - ../../../shared/shared_gs_iam - ../../../shared/shared_mt_overview - ../../../shared/shared_next_steps +Prerequisites +============= + +Set up the following system and hardware configuration before installing +Edge Orchestrator: + + +System Requirements +------------------- + +Domain +------ + +A domain is required for the Edge Orchestrator installation. Purchase a domain +name from a domain registrar if you do not have one. The domain must be a +valid domain name that is resolvable by public DNS servers and you must be +able to create DNS records for the domain name. + +The domain name must be unique and not used by any other service in the +network. The domain name must be a fully qualified domain name (FQDN) and not +an IP address. + + + +Edge Orchestrator Network Topology +---------------------------------- + +.. warning:: + Ensure that there are no incorrect configurations while setting up your DNS server for Edge Orchestrator. Incorrect configurations can lead to deployment failures. Specifically, the RKE2 server might start using the 8.8.8.8 server for DNS resolution, if no other DNS server is properly configured. + + 1. Avoid configuring `/etc/resolv.conf` and `/run/systemd/resolve/resolv.conf` to point exclusively to loopback or multicast nameservers. This can cause issues during deployment. + + 2. Ensure that the `service_cidr` subnet specified in the installation guide does not overlap with any existing subnets in your infrastructure. For example, if the k8s `service_cidr` includes the IP `10.43.0.10`, ensure this IP is not used as a DNS server in the OS or for any critical network communications in your environment. + +.. image:: ../images/on-prem-install-topology-config.png + :alt: The network topology for Edge Orchestrator + :width: 500px + :align: center + + +Edge Orchestrator Network Topology with Corporate Proxy +-------------------------------------------------------- + +.. image:: ../images/on-prem-install-topology-config-with-corporate-proxy.png + :alt: The network topology for Edge Orchestrator + :width: 500px + :align: center + +Edge Orchestrator for Edge Nodes without Direct Internet Access +---------------------------------------------------------------- + +.. image:: ../images/on-prem-install-topology-config-with-squid-proxy.png + :alt: The network topology for Edge Orchestrator + :width: 500px + :align: center + +Lenovo\* Open Cloud Automation (LOC-A) Network Topology (Optional) +------------------------------------------------------------------ + +When integrating the Lenovo\* Open Cloud Automation (LOC-A) software, you can use networking settings of your choice. + +In general, Edge Orchestrator and LOC-A can share the same subnet but this might not be desirable for the Baseboard Management Controller (BMC) of the edge devices (or not entirely possible). The following figure shows a simple network topology: + +.. image:: ../images/on-prem-loca-install-topology-config.png + :alt: The network topology for Edge Orchestrator and LOC-A + :width: 500px + :align: center + +In addition to upstream connectivity, Edge Orchestrator requires connectivity to LOC-A; while the edge node requires connectivity to Edge Orchestrator. LOC-A also has its own network environment requirements to ensure proper communication between the LOC-A Portal and the edge nodes. For details on LOC-A and networking settings, see the `Lenovo ISG Support Plan - LOC-A (Lenovo Open Cloud Automation) `_. + +This Edge Orchestrator version is compatible with LOC-A version 3.2. + +.. note:: + Other configurations are possible, for example, having a separate network for BMC and OS management. + +Firewall Configuration +---------------------- + +The following table lists the network endpoints for Edge Orchestrator and edge nodes. You can use this to configure the firewall rules appropriate for your network environment. + +* ArgoCD Admin UI at ``argo.{domain}``. Intel recommends that you restrict the incoming traffic to a subset of known source IPs because this is an administrator interface. +* BIOS Onboarding accesses ``tinkerbell-nginx.{domain}``. +* You can access all other services from edge nodes agents, UI, and APIs of Edge Orchestrator. + +.. list-table:: Network Endpoints for Edge Orchestrator and Edge Nodes + :header-rows: 1 + + * - Source + - Destination + - Protocol + - Port number + - Description + * - Edge Orchestrator UI and API + - {domain} + - TCP + - 443 + - Web UI + * - Edge Orchestrator UI and API + - web-ui.{domain} + - TCP + - 443 + - Web UI + * - Edge Orchestrator API + - api.{domain} + - TCP + - 443 + - Tenancy API + * - Edge Orchestrator UI and API + - metadata.{domain} + - TCP + - 443 + - Web UI + * - Edge Orchestrator UI and API + - app-orch.{domain} + - TCP + - 443 + - Application orchestration + * - Edge Orchestrator UI and API + - app-service-proxy.{domain} + - TCP + - 443 + - Application orchestration + * - Edge Orchestrator UI and API + - ws-app-service-proxy.{domain} + - TCP + - 443 + - Application orchestration + * - Edge Orchestrator UI and API + - gitea.{domain} + - TCP + - 443 + - Application orchestration + * - Edge Orchestrator UI and API + - vnc.{domain} + - TCP + - 443 + - Application orchestration + * - Edge Orchestrator UI and API + - cluster-orch.{domain} + - TCP + - 443 + - Cluster orchestration + * - Edge Orchestrator UI and API + - iaas.{domain} + - TCP + - 443 + - Edge infrastructure management + * - Edge Orchestrator UI and API + - infra.{domain} + - TCP + - 443 + - Edge infrastructure management + * - Edge Orchestrator UI and API + - onboarding.{domain} + - TCP + - 443 + - Edge infrastructure management + * - Edge Orchestrator UI and API + - update.{domain} + - TCP + - 443 + - Edge infrastructure management + * - Edge Orchestrator UI and API + - keycloak.{domain} + - TCP + - 443 + - Identity and Access Management + * - Edge Orchestrator UI and API + - log-query.{domain} + - TCP + - 443 + - Observability + * - Edge Orchestrator UI and API + - observability-admin.{domain} + - TCP + - 443 + - Observability + * - Edge Orchestrator UI and API + - observability-ui.{domain} + - TCP + - 443 + - Observability + * - Edge Orchestrator UI and API + - telemetry.{domain} + - TCP + - 443 + - Observability + * - Edge Orchestrator UI and API + - rancher.{domain} + - TCP + - 443 + - Rancher's Fleet UI + * - Edge Orchestrator UI and API + - registry.{domain} + - TCP + - 443 + - Harbor\* UI + * - Edge Orchestrator UI and API + - vault.{domain} + - TCP + - 443 + - Vault\* UI + * - Edge node + - cluster-orch-node.{domain} + - TCP + - 443 + - Cluster orchestration + * - Edge node + - infra-node.{domain} + - TCP + - 443 + - Edge infrastructure management + * - Edge node + - onboarding-node.{domain} + - TCP + - 443 + - Edge infrastructure management + * - Edge node + - release.{domain} + - TCP + - 443 + - Release service token + * - Edge node + - metrics-node.{domain} + - TCP + - 443 + - Observability + * - Edge node + - telemetry-node.{domain} + - TCP + - 443 + - Observability + * - Edge node + - logs-node.{domain} + - TCP + - 443 + - Observability + * - Edge node + - tinkerbell-server.{domain} + - TCP + - 443 + - Onboarding + * - Edge node + - update-node.{domain} + - TCP + - 443 + - Edge infrastructure management + * - Edge node + - tinkerbell-nginx.{domain} + - TCP + - 443 + - BIOS onboarding + * - Edge Orchestrator admin + - argo.{domain} + - TCP + - 443 + - ArgoCD UI + +LOC-A Firewall Configuration (Optional) +--------------------------------------- + +When integrating the LOC-A and Edge Orchestrator, you will need an additional entry if you deploy LOC-A on the same network that is served by the same DNS. + +.. list-table:: Network Endpoints for Lenovo Open Cloud Automation (LOC-A) + :header-rows: 1 + + * - Source + - Destination + - Protocol + - Port number + - Description + * - LOC-A Web UI and API + - loca.{domain} + - TCP + - 443 + - Web UI and REST API + +Squid Proxy Firewall Configuration (Optional) +--------------------------------------------- + +When deploying Edge Orchestrator with Squid proxy, you will need an additional firewall entry to allow the edge node to reach the Squid proxy. Intel recommends that only the edge node subnet is allowed to access the Squid proxy endpoint. + +.. list-table:: Network Endpoints for Squid Proxy. + :header-rows: 1 + + * - Source + - Destination + - Protocol + - Port Number + - Description + * - Edge node + - {IP of Traefik endpoint in Edge Orchestrator} + - TCP + - 8080 + - Squid proxy From 47ba5d761307b4c3d6fb8a30b109e38aa431cb84 Mon Sep 17 00:00:00 2001 From: Charles Chan Date: Fri, 2 May 2025 15:47:44 -0700 Subject: [PATCH 2/4] fix: broken network topology link, update on-prem page title to be consistent with cloud --- .../on_prem_get_started/index.rst | 25 +++++++++++++++++-- .../on_prem_get_started/on_prem_install.rst | 2 +- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst index 285a3564..54b65e00 100644 --- a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst +++ b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst @@ -1,5 +1,5 @@ -Prerequisites -============= +Get Started with Edge Orchestrator +================================== Set up the following system and hardware configuration before installing Edge Orchestrator: @@ -293,3 +293,24 @@ When deploying Edge Orchestrator with Squid proxy, you will need an additional f - TCP - 8080 - Squid proxy + +:doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/system_requirements_on_prem_orch` +:doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_certs` +:doc:`/shared/shared_gs_preinstall` +:doc:`/shared/shared_traefik_rate_limit` +:doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_install` +:doc:`/shared/shared_gs_iam` +:doc:`/shared/shared_mt_overview` +:doc:`/shared/shared_next_steps` + +.. toctree:: + :hidden: + + system_requirements_on_prem_orch + on_prem_certs + ../../../shared/shared_gs_preinstall + ../../../shared/shared_traefik_rate_limit + on_prem_install + ../../../shared/shared_gs_iam + ../../../shared/shared_mt_overview + ../../../shared/shared_next_steps \ No newline at end of file diff --git a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_install.rst b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_install.rst index 6e9677be..aeed46d4 100644 --- a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_install.rst +++ b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_install.rst @@ -236,7 +236,7 @@ The installer script prompts for configuration input during installation. Load Balancer for Argo CD UI, Traefik application proxy, and NGINX web server as follows. These IPs must be in the same subnet (for example, `10.0.0.1/24`) of the Edge Orchestrator Node, see - `Edge Orchestrator Network Topology <./on_prem_prereq.html#edge-orchestrator-network-topology>`__. + `Edge Orchestrator Network Topology <./index.html#edge-orchestrator-network-topology>`__. For an example of the topology. From 7f49c60432483bebe7f7583cf36a060dc0734ec1 Mon Sep 17 00:00:00 2001 From: Charles Chan Date: Fri, 2 May 2025 15:49:54 -0700 Subject: [PATCH 3/4] chore: clean up toc --- .../on_prem_get_started/index.rst | 21 ------------------- 1 file changed, 21 deletions(-) diff --git a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst index 54b65e00..476074a0 100644 --- a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst +++ b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst @@ -293,24 +293,3 @@ When deploying Edge Orchestrator with Squid proxy, you will need an additional f - TCP - 8080 - Squid proxy - -:doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/system_requirements_on_prem_orch` -:doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_certs` -:doc:`/shared/shared_gs_preinstall` -:doc:`/shared/shared_traefik_rate_limit` -:doc:`/deployment_guide/on_prem_deployment/on_prem_get_started/on_prem_install` -:doc:`/shared/shared_gs_iam` -:doc:`/shared/shared_mt_overview` -:doc:`/shared/shared_next_steps` - -.. toctree:: - :hidden: - - system_requirements_on_prem_orch - on_prem_certs - ../../../shared/shared_gs_preinstall - ../../../shared/shared_traefik_rate_limit - on_prem_install - ../../../shared/shared_gs_iam - ../../../shared/shared_mt_overview - ../../../shared/shared_next_steps \ No newline at end of file From 2e6477a366b4eaac24d8dfbfbb0a999022c16af0 Mon Sep 17 00:00:00 2001 From: achamuah <106507758+achamuah@users.noreply.github.com> Date: Tue, 6 May 2025 16:05:45 +0530 Subject: [PATCH 4/4] Update index.rst --- .../on_prem_get_started/index.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst index 476074a0..0ff269e9 100644 --- a/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst +++ b/docs/deployment_guide/on_prem_deployment/on_prem_get_started/index.rst @@ -293,3 +293,16 @@ When deploying Edge Orchestrator with Squid proxy, you will need an additional f - TCP - 8080 - Squid proxy + + +.. toctree:: + :hidden: + + system_requirements_on_prem_orch + on_prem_certs + ../../../shared/shared_gs_preinstall + ../../../shared/shared_traefik_rate_limit + on_prem_install + ../../../shared/shared_gs_iam + ../../../shared/shared_mt_overview + ../../../shared/shared_next_steps