From 67226d918c0c7437ffc3fe4e85e4c4c9ff56529e Mon Sep 17 00:00:00 2001 From: itsjdubois Date: Thu, 10 Sep 2026 10:44:23 -0400 Subject: [PATCH 1/3] docs: document RUNPOD_ALLOW_IP IP allowlisting Add customer-facing documentation for the RUNPOD_ALLOW_IP environment variable, which restricts inbound access by source IP for Pods (HTTP proxy) and Serverless endpoints. Behavior verified in production on 2026-09-09. - Pods > Expose ports: new "Restrict access by IP address" section, TCP bypass note, security and troubleshooting entries. - Pods > Environment variables: "Runpod-reserved variables" table. - Serverless > Endpoint settings: new "IP allowlist" section. - Serverless > Environment variables: "Runpod-reserved variables" table. - Serverless > Send API requests: 403 row in the error table. - Serverless > Load balancing overview: RUNPOD_ALLOW_IP env row. Co-Authored-By: Claude Fable 5.1 --- pods/configuration/expose-ports.mdx | 22 +++++++++++++++++++ pods/templates/environment-variables.mdx | 8 +++++++ .../development/environment-variables.mdx | 8 +++++++ .../endpoints/endpoint-configurations.mdx | 12 ++++++++++ serverless/endpoints/send-requests.mdx | 1 + serverless/load-balancing/overview.mdx | 1 + 6 files changed, 52 insertions(+) diff --git a/pods/configuration/expose-ports.mdx b/pods/configuration/expose-ports.mdx index 2de0acf22..8db4a69f9 100644 --- a/pods/configuration/expose-ports.mdx +++ b/pods/configuration/expose-ports.mdx @@ -70,6 +70,22 @@ Design your application with these constraints in mind. For long-running operati - Breaking large operations into smaller chunks. - Returning immediate responses with job IDs for later retrieval. +### Restrict access by IP address + +By default, anyone who knows your Pod's proxy URL can reach your service. To limit access to specific source IP addresses, set the `RUNPOD_ALLOW_IP` environment variable on your Pod to a comma-separated list of IP addresses or CIDR ranges: + +```bash +RUNPOD_ALLOW_IP=203.0.113.7,198.51.100.0/24 +``` + +The proxy checks the source IP of each request against this list before forwarding it to your Pod. Requests from addresses that aren't on the list receive a `400 Bad Request` response with an empty body. If the variable is empty or unset, all IP addresses are allowed. + +You can set `RUNPOD_ALLOW_IP` in a template or on an existing Pod under **Environment Variables**. See [Environment variables](/pods/templates/environment-variables#runpod-reserved-variables) for details. + + +`RUNPOD_ALLOW_IP` only applies to ports exposed through the HTTP proxy. It does not restrict [TCP ports exposed via public IP](#tcp-access-via-public-ip), including SSH. To restrict access on TCP ports, configure a firewall inside your container or add authentication to your application. + + ## TCP access via public IP @@ -82,6 +98,10 @@ For services requiring direct TCP connections, lower latency, or protocols other In your Pod or template configuration, follow the same steps as for [HTTP ports](#configure-external-http-ports), but add ports to the **Expose TCP Ports** field. This enables direct TCP forwarding with a public IP address. + +The `RUNPOD_ALLOW_IP` variable does not apply to TCP ports. Traffic to a public IP and port reaches your container directly, so any IP restriction must be enforced inside your container or application. + + ### Find your connection details After your Pod starts, check the **Connect** menu to find your assigned public IP and external port mapping under **Direct TCP Ports**. For example: @@ -140,6 +160,7 @@ When exposing ports from your Pods, follow these guidelines for security and rel ### Security considerations - **Implement authentication**: Both HTTP proxy and TCP access make your services publicly accessible. Always implement proper authentication and authorization in your applications. +- **Restrict access by IP**: For HTTP proxy ports, set [`RUNPOD_ALLOW_IP`](#restrict-access-by-ip-address) to limit access to known IP addresses or ranges. This does not cover TCP ports. - **Use HTTPS for sensitive data**: While the proxy automatically provides HTTPS, TCP connections do not. Implement TLS in your application when handling sensitive data over TCP. - **Validate input**: Public endpoints are targets for malicious traffic. Implement robust input validation and rate limiting. @@ -169,6 +190,7 @@ Different types of applications benefit from different exposure methods: Try these fixes if you're having issues with port exposure: - **Service not accessible via proxy**: Ensure your service binds to `0.0.0.0` (all interfaces) not just `localhost` or `127.0.0.1`. +- **400 Bad Request with an empty body from the proxy URL**: Your IP address isn't in the Pod's [`RUNPOD_ALLOW_IP`](#restrict-access-by-ip-address) list. Add your address or remove the variable. - **524 timeout errors**: If your service takes longer than 100 seconds to respond, consider using TCP or restructuring your application for faster responses. - **Connection refused**: Verify your service is running and listening on the correct port inside the Pod. - **Port already in use**: Check that no other services in your Pod are using the same port. diff --git a/pods/templates/environment-variables.mdx b/pods/templates/environment-variables.mdx index 20a2e07e7..9f81c8c8d 100644 --- a/pods/templates/environment-variables.mdx +++ b/pods/templates/environment-variables.mdx @@ -91,6 +91,14 @@ Runpod automatically sets these environment variables: | `CUDA_VERSION` | Installed CUDA version. | | `PYTORCH_VERSION` | Installed PyTorch version. | +## Runpod-reserved variables + +Runpod reads these variables if you set them. They change how Runpod handles your Pod rather than configuring your application: + +| Variable | Description | +| --- | --- | +| `RUNPOD_ALLOW_IP` | Comma-separated list of IP addresses or CIDR ranges allowed to reach your Pod's HTTP proxy ports (for example, `203.0.113.7,198.51.100.0/24`). Requests from other addresses receive a `400` response. Does not apply to TCP ports. See [Restrict access by IP address](/pods/configuration/expose-ports#restrict-access-by-ip-address). | + ## Best practices - **Use secrets for sensitive data**: Never hardcode API keys or passwords. Use [Runpod secrets](/pods/templates/secrets). diff --git a/serverless/development/environment-variables.mdx b/serverless/development/environment-variables.mdx index 8722cdc9b..468cd66d2 100644 --- a/serverless/development/environment-variables.mdx +++ b/serverless/development/environment-variables.mdx @@ -73,6 +73,14 @@ Runtime variables are useful for: - Values that change frequently. - Sensitive information that shouldn't be in your image. +## Runpod-reserved variables + +Some variable names are reserved. Runpod reads them to change how it handles your endpoint, in addition to passing them to your workers: + +| Variable | Description | +| --- | --- | +| `RUNPOD_ALLOW_IP` | Comma-separated list of IP addresses or CIDR ranges allowed to send requests to your endpoint (for example, `203.0.113.7,198.51.100.0/24`). Requests from other addresses receive a `403` response before API key validation. See [IP allowlist](/serverless/endpoints/endpoint-configurations#ip-allowlist). | + ## Common use cases ### API keys and secrets diff --git a/serverless/endpoints/endpoint-configurations.mdx b/serverless/endpoints/endpoint-configurations.mdx index 540cd6b01..6005df1e4 100644 --- a/serverless/endpoints/endpoint-configurations.mdx +++ b/serverless/endpoints/endpoint-configurations.mdx @@ -142,3 +142,15 @@ Ensures workers run on with compatible drivers. Select your ### Expose HTTP/TCP ports Exposes the worker's public IP and port for direct external communication. Required for persistent connections like WebSockets. + +### IP allowlist + +To restrict which source IP addresses can send requests to your endpoint, add a `RUNPOD_ALLOW_IP` environment variable to your endpoint with a comma-separated list of IP addresses or CIDR ranges: + +```bash +RUNPOD_ALLOW_IP=203.0.113.7,198.51.100.0/24 +``` + +Runpod checks the source IP of every request before validating the API key. Requests from addresses that aren't on the list receive a `403 Forbidden` response with the message `ip address not allowed`. This applies to every endpoint operation (`/run`, `/runsync`, `/status`, `/health`, and so on) and to both queue-based and load balancing endpoints. Changes take effect within a few seconds and don't restart your workers. If the variable is empty or unset, all IP addresses are allowed. + +To set the variable, open your endpoint in the [Runpod console](https://console.runpod.io/serverless), go to the **Settings** tab, and add it under **Environment Variables**. See [Environment variables](/serverless/development/environment-variables#runpod-reserved-variables) for details. diff --git a/serverless/endpoints/send-requests.mdx b/serverless/endpoints/send-requests.mdx index 7ff04208b..e4ef5d7ae 100644 --- a/serverless/endpoints/send-requests.mdx +++ b/serverless/endpoints/send-requests.mdx @@ -212,6 +212,7 @@ Common errors and solutions: |-------------|-----------------------|---------------------------------------------------| | 400 | Bad Request | Check your request format and parameters | | 401 | Unauthorized | Verify your API key is correct and has permission | +| 403 | Forbidden | Your IP address isn't in the endpoint's [IP allowlist](/serverless/endpoints/endpoint-configurations#ip-allowlist) | | 404 | Not Found | Check your endpoint ID | | 429 | Too Many Requests | Implement backoff and retry logic | | 500 | Internal Server Error | Check endpoint logs; worker may have crashed | diff --git a/serverless/load-balancing/overview.mdx b/serverless/load-balancing/overview.mdx index c75f76a2b..aad4e4277 100644 --- a/serverless/load-balancing/overview.mdx +++ b/serverless/load-balancing/overview.mdx @@ -119,6 +119,7 @@ When calculating endpoint metrics, Runpod calculates the cold start time for loa | `PORT` | `80` | Main application server port | | `PORT_HEALTH` | Same as `PORT` | Health check endpoint port | | `HEALTH_CHECK_PATH` | `/ping` | Path the load balancer polls to check worker health | +| `RUNPOD_ALLOW_IP` | Unset (allow all) | Comma-separated IP addresses or CIDR ranges allowed to send requests to the endpoint. See [IP allowlist](/serverless/endpoints/endpoint-configurations#ip-allowlist) | If using a custom port, add it to your endpoint's environment variables and expose it in container configuration (under **Expose HTTP Ports (Max 10)**). From 91f28a8954de34ffbc575b65e7f818159cfe3757 Mon Sep 17 00:00:00 2001 From: itsjdubois Date: Thu, 10 Sep 2026 10:50:50 -0400 Subject: [PATCH 2/3] docs: reduce callout density in expose-ports Fold the RUNPOD_ALLOW_IP TCP caveat into prose and drop the duplicate note in the TCP section. Four callouts in thirty lines was too noisy. Co-Authored-By: Claude Fable 5.1 --- pods/configuration/expose-ports.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/pods/configuration/expose-ports.mdx b/pods/configuration/expose-ports.mdx index 8db4a69f9..6a1c4bb6c 100644 --- a/pods/configuration/expose-ports.mdx +++ b/pods/configuration/expose-ports.mdx @@ -82,9 +82,7 @@ The proxy checks the source IP of each request against this list before forwardi You can set `RUNPOD_ALLOW_IP` in a template or on an existing Pod under **Environment Variables**. See [Environment variables](/pods/templates/environment-variables#runpod-reserved-variables) for details. - `RUNPOD_ALLOW_IP` only applies to ports exposed through the HTTP proxy. It does not restrict [TCP ports exposed via public IP](#tcp-access-via-public-ip), including SSH. To restrict access on TCP ports, configure a firewall inside your container or add authentication to your application. - ## TCP access via public IP @@ -98,10 +96,6 @@ For services requiring direct TCP connections, lower latency, or protocols other In your Pod or template configuration, follow the same steps as for [HTTP ports](#configure-external-http-ports), but add ports to the **Expose TCP Ports** field. This enables direct TCP forwarding with a public IP address. - -The `RUNPOD_ALLOW_IP` variable does not apply to TCP ports. Traffic to a public IP and port reaches your container directly, so any IP restriction must be enforced inside your container or application. - - ### Find your connection details After your Pod starts, check the **Connect** menu to find your assigned public IP and external port mapping under **Direct TCP Ports**. For example: From 8c0b77a95555a154cb0bdbfea7b67b0623f6dfc2 Mon Sep 17 00:00:00 2001 From: itsjdubois Date: Thu, 10 Sep 2026 10:56:35 -0400 Subject: [PATCH 3/3] docs: fix Vale style hits in RUNPOD_ALLOW_IP text Expand nothing, contract 'does not', drop passive voice and parentheticals, and say 'IP address ranges' instead of 'CIDR ranges' so the new paragraphs introduce zero Vale alerts relative to main. File-level readability scores were pre-existing and improve slightly. Co-Authored-By: Claude Fable 5.1 --- pods/configuration/expose-ports.mdx | 8 ++++---- pods/templates/environment-variables.mdx | 2 +- serverless/development/environment-variables.mdx | 4 ++-- serverless/endpoints/endpoint-configurations.mdx | 4 ++-- serverless/load-balancing/overview.mdx | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/pods/configuration/expose-ports.mdx b/pods/configuration/expose-ports.mdx index 6a1c4bb6c..632e6822c 100644 --- a/pods/configuration/expose-ports.mdx +++ b/pods/configuration/expose-ports.mdx @@ -72,17 +72,17 @@ Design your application with these constraints in mind. For long-running operati ### Restrict access by IP address -By default, anyone who knows your Pod's proxy URL can reach your service. To limit access to specific source IP addresses, set the `RUNPOD_ALLOW_IP` environment variable on your Pod to a comma-separated list of IP addresses or CIDR ranges: +By default, anyone who knows your Pod's proxy URL can reach your service. To limit access to specific source IP addresses, set the `RUNPOD_ALLOW_IP` environment variable on your Pod to a comma-separated list of IP addresses or IP address ranges: ```bash RUNPOD_ALLOW_IP=203.0.113.7,198.51.100.0/24 ``` -The proxy checks the source IP of each request against this list before forwarding it to your Pod. Requests from addresses that aren't on the list receive a `400 Bad Request` response with an empty body. If the variable is empty or unset, all IP addresses are allowed. +The proxy checks the source IP of each request against this list before forwarding it to your Pod. Requests from addresses that aren't on the list receive a `400 Bad Request` response with an empty body. If the variable is empty or unset, the proxy allows all IP addresses. You can set `RUNPOD_ALLOW_IP` in a template or on an existing Pod under **Environment Variables**. See [Environment variables](/pods/templates/environment-variables#runpod-reserved-variables) for details. -`RUNPOD_ALLOW_IP` only applies to ports exposed through the HTTP proxy. It does not restrict [TCP ports exposed via public IP](#tcp-access-via-public-ip), including SSH. To restrict access on TCP ports, configure a firewall inside your container or add authentication to your application. +`RUNPOD_ALLOW_IP` only applies to ports exposed through the HTTP proxy. It doesn't restrict [TCP ports exposed via public IP](#tcp-access-via-public-ip), including SSH. To restrict access on TCP ports, configure a firewall inside your container or add authentication to your application. ## TCP access via public IP @@ -154,7 +154,7 @@ When exposing ports from your Pods, follow these guidelines for security and rel ### Security considerations - **Implement authentication**: Both HTTP proxy and TCP access make your services publicly accessible. Always implement proper authentication and authorization in your applications. -- **Restrict access by IP**: For HTTP proxy ports, set [`RUNPOD_ALLOW_IP`](#restrict-access-by-ip-address) to limit access to known IP addresses or ranges. This does not cover TCP ports. +- **Restrict access by IP**: For HTTP proxy ports, set [`RUNPOD_ALLOW_IP`](#restrict-access-by-ip-address) to limit access to known IP addresses or ranges. This doesn't cover TCP ports. - **Use HTTPS for sensitive data**: While the proxy automatically provides HTTPS, TCP connections do not. Implement TLS in your application when handling sensitive data over TCP. - **Validate input**: Public endpoints are targets for malicious traffic. Implement robust input validation and rate limiting. diff --git a/pods/templates/environment-variables.mdx b/pods/templates/environment-variables.mdx index 9f81c8c8d..f0ce57be8 100644 --- a/pods/templates/environment-variables.mdx +++ b/pods/templates/environment-variables.mdx @@ -97,7 +97,7 @@ Runpod reads these variables if you set them. They change how Runpod handles you | Variable | Description | | --- | --- | -| `RUNPOD_ALLOW_IP` | Comma-separated list of IP addresses or CIDR ranges allowed to reach your Pod's HTTP proxy ports (for example, `203.0.113.7,198.51.100.0/24`). Requests from other addresses receive a `400` response. Does not apply to TCP ports. See [Restrict access by IP address](/pods/configuration/expose-ports#restrict-access-by-ip-address). | +| `RUNPOD_ALLOW_IP` | Comma-separated list of IP addresses or IP address ranges allowed to reach your Pod's HTTP proxy ports, such as `203.0.113.7,198.51.100.0/24`. Requests from other addresses receive a `400` response. Doesn't apply to TCP ports. See [Restrict access by IP address](/pods/configuration/expose-ports#restrict-access-by-ip-address). | ## Best practices diff --git a/serverless/development/environment-variables.mdx b/serverless/development/environment-variables.mdx index 468cd66d2..2744909f0 100644 --- a/serverless/development/environment-variables.mdx +++ b/serverless/development/environment-variables.mdx @@ -75,11 +75,11 @@ Runtime variables are useful for: ## Runpod-reserved variables -Some variable names are reserved. Runpod reads them to change how it handles your endpoint, in addition to passing them to your workers: +Runpod reserves some variable names. It reads them to change how it handles your endpoint, in addition to passing them to your workers: | Variable | Description | | --- | --- | -| `RUNPOD_ALLOW_IP` | Comma-separated list of IP addresses or CIDR ranges allowed to send requests to your endpoint (for example, `203.0.113.7,198.51.100.0/24`). Requests from other addresses receive a `403` response before API key validation. See [IP allowlist](/serverless/endpoints/endpoint-configurations#ip-allowlist). | +| `RUNPOD_ALLOW_IP` | Comma-separated list of IP addresses or IP address ranges allowed to send requests to your endpoint, such as `203.0.113.7,198.51.100.0/24`. Requests from other addresses receive a `403` response before API key validation. See [IP allowlist](/serverless/endpoints/endpoint-configurations#ip-allowlist). | ## Common use cases diff --git a/serverless/endpoints/endpoint-configurations.mdx b/serverless/endpoints/endpoint-configurations.mdx index 6005df1e4..9c4beee43 100644 --- a/serverless/endpoints/endpoint-configurations.mdx +++ b/serverless/endpoints/endpoint-configurations.mdx @@ -145,12 +145,12 @@ Exposes the worker's public IP and port for direct external communication. Requi ### IP allowlist -To restrict which source IP addresses can send requests to your endpoint, add a `RUNPOD_ALLOW_IP` environment variable to your endpoint with a comma-separated list of IP addresses or CIDR ranges: +To restrict which source IP addresses can send requests to your endpoint, add a `RUNPOD_ALLOW_IP` environment variable to your endpoint with a comma-separated list of IP addresses or IP address ranges: ```bash RUNPOD_ALLOW_IP=203.0.113.7,198.51.100.0/24 ``` -Runpod checks the source IP of every request before validating the API key. Requests from addresses that aren't on the list receive a `403 Forbidden` response with the message `ip address not allowed`. This applies to every endpoint operation (`/run`, `/runsync`, `/status`, `/health`, and so on) and to both queue-based and load balancing endpoints. Changes take effect within a few seconds and don't restart your workers. If the variable is empty or unset, all IP addresses are allowed. +Runpod checks the source IP of every request before validating the API key. Requests from addresses that aren't on the list receive a `403 Forbidden` response with the message `ip address not allowed`. This applies to every endpoint operation, including `/run`, `/runsync`, `/status`, and `/health`, and to both queue-based and load balancing endpoints. Changes take effect within a few seconds and don't restart your workers. If the variable is empty or unset, Runpod allows all IP addresses. To set the variable, open your endpoint in the [Runpod console](https://console.runpod.io/serverless), go to the **Settings** tab, and add it under **Environment Variables**. See [Environment variables](/serverless/development/environment-variables#runpod-reserved-variables) for details. diff --git a/serverless/load-balancing/overview.mdx b/serverless/load-balancing/overview.mdx index aad4e4277..f785b0b68 100644 --- a/serverless/load-balancing/overview.mdx +++ b/serverless/load-balancing/overview.mdx @@ -119,7 +119,7 @@ When calculating endpoint metrics, Runpod calculates the cold start time for loa | `PORT` | `80` | Main application server port | | `PORT_HEALTH` | Same as `PORT` | Health check endpoint port | | `HEALTH_CHECK_PATH` | `/ping` | Path the load balancer polls to check worker health | -| `RUNPOD_ALLOW_IP` | Unset (allow all) | Comma-separated IP addresses or CIDR ranges allowed to send requests to the endpoint. See [IP allowlist](/serverless/endpoints/endpoint-configurations#ip-allowlist) | +| `RUNPOD_ALLOW_IP` | Unset, allows all | Comma-separated IP addresses or IP address ranges allowed to send requests to the endpoint. See [IP allowlist](/serverless/endpoints/endpoint-configurations#ip-allowlist) | If using a custom port, add it to your endpoint's environment variables and expose it in container configuration (under **Expose HTTP Ports (Max 10)**).