From 956133bf457dacba8a16243c717690f8e67d2ffb Mon Sep 17 00:00:00 2001 From: Jon Koops Date: Tue, 17 Mar 2026 18:13:00 +0100 Subject: [PATCH] docs: recommend Node.js built-in proxy support for corporate proxies (#33006) Node.js 22.21.0+ natively supports HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables via NODE_USE_ENV_PROXY, eliminating the need for undici and global-agent workarounds. This also works with node-fetch and cross-fetch since they delegate to node:http/node:https without overriding the HTTP agent. Add a new corporate proxy tutorial under docs/ with the recommended approach and update the legacy guide in contrib/ to point to it. Update proxy references in the deployment, keeping-backstage-updated, and TechDocs CLI docs to mention NODE_USE_ENV_PROXY. Signed-off-by: Jon Koops --- .../help-im-behind-a-corporate-proxy.md | 5 ++- docs/deployment/index.md | 4 +-- docs/features/techdocs/cli.md | 7 ++-- .../keeping-backstage-updated.md | 13 +++++--- .../create-app/keeping-backstage-updated.md | 13 +++++--- docs/tutorials/corporate-proxy.md | 33 +++++++++++++++++++ 6 files changed, 59 insertions(+), 16 deletions(-) create mode 100644 docs/tutorials/corporate-proxy.md diff --git a/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md b/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md index 4852443ecf..4a7e0ad233 100644 --- a/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md +++ b/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md @@ -1,4 +1,7 @@ -# Running the backend behind a Corporate Proxy +# Legacy: Running the backend behind a Corporate Proxy + +> [!NOTE] +> On Node.js 22.21.0 or later, you can use Node.js's built-in proxy support instead of the workarounds described here. See the [recommended proxy setup guide](../../../docs/tutorials/corporate-proxy.md) for details. This article helps you get your backend installation up and running making calls through corporate proxies. diff --git a/docs/deployment/index.md b/docs/deployment/index.md index 76c8c12932..a5f3c9ac7a 100644 --- a/docs/deployment/index.md +++ b/docs/deployment/index.md @@ -32,6 +32,4 @@ This method is covered in [Building a Docker image](docker.md) and There are many ways to deploy Backstage! You can find more examples in the community contributed guides found [here](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/). -If you need to run Backstage behind a corporate proxy, this -[contributed guide](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md) -may help. +If you need to run Backstage behind a corporate proxy, see the [corporate proxy guide](../tutorials/corporate-proxy.md). diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index f6be53cb55..fa3d9148e2 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -208,10 +208,13 @@ Options: #### Publishing from behind a proxy -For users attempting to publish TechDocs content behind a proxy, the TechDocs CLI leverages `global-agent` to navigate the proxy to successfully connect to that location. To enable `global-agent`, the following variables need to be set prior to running the techdocs-cli command: +On Node.js 22.21.0+, set `NODE_USE_ENV_PROXY=1` along with `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` to route TechDocs publishing through a proxy. See the [corporate proxy guide](../../tutorials/corporate-proxy.md) for details. + +On older Node.js versions, the TechDocs CLI leverages `global-agent` to navigate the proxy. To enable `global-agent`, the following variables need to be set prior to running the techdocs-cli command: ```bash -export GLOBAL_AGENT_HTTPS_PROXY=${HTTP_PROXY} +export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} +export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} ``` diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index c93c5200f6..a55f872f53 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -151,12 +151,14 @@ down the number of duplicate packages. ## Proxy -The Backstage CLI uses [global-agent](https://www.npmjs.com/package/global-agent) and `undici` to configure HTTP/HTTPS proxy settings using environment variables. This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access. +On Node.js 22.21.0+, the Backstage CLI respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables when `NODE_USE_ENV_PROXY=1` is set. See the [corporate proxy guide](../tutorials/corporate-proxy.md) for full details. + +On older Node.js versions, the CLI falls back to [global-agent](https://www.npmjs.com/package/global-agent) and `undici` for proxy support, which require their own environment variables (prefixed with `GLOBAL_AGENT_`). This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access. Additionally, yarn needs a proxy too (sometimes), when in environments with restricted internet access. It uses different settings than the other modules. If you decide to use the backstage yarn plugin [mentioned above](#plugin), you will need to set additional proxy values. If you will always need proxy settings in all environments and situations, you can add `httpProxy` and `httpsProxy` values to [the yarnrc.yml file](https://yarnpkg.com/configuration/yarnrc). If some environments need it (say a developer workstation) but other environments do not (perhaps a CI build server running on AWS), then you may not want to update the yarnrc.yml file but just set environment variables `YARN_HTTP_PROXY` and `YARN_HTTPS_PROXY` in the environments/situations where you need to proxy. -**If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the `versions:bump` command**. If you do not plan to use the backstage yarn plugin, it seems like the global agent proxy settings alone are sufficient. +**If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the `versions:bump` command**. If you do not plan to use the backstage yarn plugin, it seems like the proxy settings alone are sufficient. ### Example Configuration @@ -164,9 +166,10 @@ If you will always need proxy settings in all environments and situations, you c export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=https://secure-proxy.company.com:8080 export NO_PROXY=localhost,internal.company.com -export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} -export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} -export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} +export NODE_USE_ENV_PROXY=1 # Node.js 22.21.0+ +export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} # Node.js < 22.21.0 +export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} # Node.js < 22.21.0 +export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} # Node.js < 22.21.0 export YARN_HTTP_PROXY=${HTTP_PROXY} # optional export YARN_HTTPS_PROXY=${HTTPS_PROXY} # optional ``` diff --git a/docs/golden-path/create-app/keeping-backstage-updated.md b/docs/golden-path/create-app/keeping-backstage-updated.md index de7d99b2b8..2692381737 100644 --- a/docs/golden-path/create-app/keeping-backstage-updated.md +++ b/docs/golden-path/create-app/keeping-backstage-updated.md @@ -141,12 +141,14 @@ down the number of duplicate packages. ## Proxy -The Backstage CLI uses [global-agent](https://www.npmjs.com/package/global-agent) and `undici` to configure HTTP/HTTPS proxy settings using environment variables. This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access. +On Node.js 22.21.0+, the Backstage CLI respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables when `NODE_USE_ENV_PROXY=1` is set. See the [corporate proxy guide](../../tutorials/corporate-proxy.md) for full details. + +On older Node.js versions, the CLI falls back to [global-agent](https://www.npmjs.com/package/global-agent) and `undici` for proxy support, which require their own environment variables (prefixed with `GLOBAL_AGENT_`). This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access. Additionally, `yarn` needs a proxy too (sometimes), when in environments with restricted internet access. It uses different settings than the other modules. If you decide to use the backstage yarn plugin [mentioned above](#plugin), you will need to set additional proxy values. If you will always need proxy settings in all environments and situations, you can add `httpProxy` and `httpsProxy` values to [the yarnrc.yml file](https://yarnpkg.com/configuration/yarnrc). If some environments need it (say a developer workstation) but other environments do not (perhaps a CI build server running on AWS), then you may not want to update the yarnrc.yml file but just set environment variables `YARN_HTTP_PROXY` and `YARN_HTTPS_PROXY` in the environments/situations where you need to proxy. -**If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the `versions:bump` command**. If you do not plan to use the backstage yarn plugin, it seems like the global agent proxy settings alone are sufficient. +**If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the `versions:bump` command**. If you do not plan to use the backstage yarn plugin, it seems like the proxy settings alone are sufficient. ### Example Configuration @@ -154,9 +156,10 @@ If you will always need proxy settings in all environments and situations, you c export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=https://secure-proxy.company.com:8080 export NO_PROXY=localhost,internal.company.com -export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} -export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} -export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} +export NODE_USE_ENV_PROXY=1 # Node.js 22.21.0+ +export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} # Node.js < 22.21.0 +export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} # Node.js < 22.21.0 +export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} # Node.js < 22.21.0 export YARN_HTTP_PROXY=${HTTP_PROXY} # optional export YARN_HTTPS_PROXY=${HTTPS_PROXY} # optional ``` diff --git a/docs/tutorials/corporate-proxy.md b/docs/tutorials/corporate-proxy.md new file mode 100644 index 0000000000..e4346e4f94 --- /dev/null +++ b/docs/tutorials/corporate-proxy.md @@ -0,0 +1,33 @@ +--- +id: corporate-proxy +title: Running Backstage behind a Corporate Proxy +description: Guide on how to configure Backstage to work behind a corporate proxy using Node.js built-in proxy support. +--- + +# Running Backstage behind a Corporate Proxy + +Sometimes you have to run Backstage with no direct access to the public internet, except through a corporate proxy. The backend is most likely where you'll run into proxy issues, as it isn't helped by your browser or OS proxy settings. + +## Using Node.js built-in proxy support + +Starting with Node.js 22.21.0 and 24.5.0, Node.js has built-in support for proxy environment variables. When enabled, native `fetch()`, `node:http`, and `node:https` all respect the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables without any additional packages. See the [Node.js enterprise network configuration docs](https://nodejs.org/en/learn/http/enterprise-network-configuration#proxy-configuration) for full details. + +To enable the built-in proxy support, set the `NODE_USE_ENV_PROXY` environment variable along with your proxy settings: + +```sh +export HTTP_PROXY=http://username:password@proxy.example.net:8888 +export HTTPS_PROXY=http://username:password@proxy.example.net:8888 +export NO_PROXY=localhost,127.0.0.1,.internal.company.com +export NODE_USE_ENV_PROXY=1 +yarn start +``` + +### Compatibility with third-party fetch libraries + +Per [ADR014](../architecture-decisions/adr014-use-fetch.md), Backstage backend code should use native `fetch()`, which works with Node.js's proxy out of the box. Some core packages and many [community plugins](https://github.com/backstage/community-plugins/) still use `node-fetch` (see [ADR013](../architecture-decisions/adr013-use-node-fetch.md)) or `cross-fetch` (for isomorphic packages). Both libraries delegate to `node:http`/`node:https` internally and do **not** set a custom HTTP agent by default, which means Node.js's proxy works for them as well. + +The exception is code that explicitly passes a custom `agent` to its fetch calls (e.g. the Kubernetes plugins, which use `new https.Agent(...)` for TLS client certificates). In those cases, the custom agent takes precedence and the built-in proxy is bypassed. This is generally the desired behavior, since those agents are configured for direct connections to specific endpoints like cluster APIs. + +## Legacy approach + +If you are on a Node.js version older than 22.21.0, you can use third-party packages to add proxy support. See the [legacy proxy setup guide](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md) for instructions using `undici`, `global-agent`, and `proxy-agent`.