diff --git a/pods/configuration/expose-ports.mdx b/pods/configuration/expose-ports.mdx index 2de0acf22..632e6822c 100644 --- a/pods/configuration/expose-ports.mdx +++ b/pods/configuration/expose-ports.mdx @@ -70,6 +70,20 @@ 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 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, 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 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 @@ -140,6 +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 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. @@ -169,6 +184,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..f0ce57be8 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 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 - **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..2744909f0 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 + +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 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 ### API keys and secrets diff --git a/serverless/endpoints/endpoint-configurations.mdx b/serverless/endpoints/endpoint-configurations.mdx index 540cd6b01..9c4beee43 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 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, 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/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..f785b0b68 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, 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)**).