diff --git a/docs/advanced/settings.md b/docs/advanced/settings.md index 5a37e5fa61..d585b154db 100644 --- a/docs/advanced/settings.md +++ b/docs/advanced/settings.md @@ -191,9 +191,12 @@ Harvester sends a graceful shutdown signal to any VM that is stopped using the H **Definition**: HTTP proxy used to access external services, including downloading of images and backup to S3 services. +You must configure HTTP proxy settings when deploying a Harvester cluster in an [air-gapped]((../airgap.md)) environment. If you want to import an air-gapped Harvester cluster into a Rancher deployed in the external environment, you must configure additional HTTP proxy settings in Rancher before starting the import. + :::caution -Changing this setting might cause single-node clusters to temporarily become unavailable or inaccessible. +- Changing this setting might cause single-node clusters to temporarily become unavailable or inaccessible. +- Proxies can rewrite or remove critical headers such as `Host` or `Cache-Control`, which in turn can break API requests and the caching mechanism. Long-running operations such as backup restoration and downloading of large virtual images can also fail due to proxy-imposed timeouts on idle connections. Ensure that necessary authentication headers are preserved, exempt internal addresses using the `noProxy` option, and adjust proxy timeout settings for lengthy control-plane tasks. ::: @@ -584,6 +587,10 @@ The value is a JSON object literal that contains the following key-value pairs: - `repository`: Name of the repository that stores the support bundle image. - `tag`: Tag assigned to the support bundle image. - `imagePullPolicy`: Pull policy of the support bundle image. The supported values are `IfNotPresent`, `Always`, and `Never`. For more information, see [Image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy) in the Kubernetes documentation. +- The configured `httpProxy`, `httpsProxy`, and `noProxy` values are automatically injected into node-level processes, including Kubernetes components, the container runtime that pulls the operating system and virtual machine image containers, and other operating system utilities. +- The HTTP proxy settings are recognized by all control plane components, including the image downloader that fetches external virtual machine images, the backup-restore controller that communicates with S3 targets, the upgrade checker that polls Rancher’s release server, and the embedded Rancher agent. This behavior results in the following: + - Outbound requests to public endpoints are routed through the configured proxy. + - Traffic to internal VIPs, service domains, and CIDR ranges bypasses the configured proxy. **Notes**: diff --git a/docs/airgap.md b/docs/airgap.md index 9610bf6d13..013afd08c9 100644 --- a/docs/airgap.md +++ b/docs/airgap.md @@ -22,6 +22,14 @@ The Harvester ISO image contains all the packages to make it work in an air gapp In some environments, the connection to external services, from the servers or VMs, requires an HTTP(S) proxy. +## Connect an Air-Gapped Harvester Cluster to Rancher + +HTTP proxy settings must be configured based on where Rancher is deployed. + +- Rancher in the external environment: To allow Rancher to access the Harvester API endpoint, configure the proxy within Rancher using the following: + - Operating system environment variables + - `http-proxy` setting: Use the `httpProxy`, `httpsProxy`, and `noProxy` options. Ensure that the `noProxy` list includes the Harvester cluster VIP or API server IP, Harvester service domains such as `harvester-system.svc.cluster.local`, and any relevant CIDR ranges. Check more details in [settings](./advanced/settings.md#http-proxy) + ### Configure an HTTP Proxy During Installation You can configure the HTTP(S) proxy during the [ISO installation](./install/iso-install.md) as shown in picture below: