From fb19fdecb1d2aa879f5dd3c991d2a54cbae8f69e Mon Sep 17 00:00:00 2001 From: Avanish Yadav Date: Tue, 24 Mar 2026 01:13:00 +0530 Subject: [PATCH 1/2] Add Gateway Registration documentation - Introduced a new guide for registering self-hosted AI Gateways with the Portkey Control Plane. - Detailed the three-step registration process: Gateway Registration, Workspace Provisioning, and Environment Variable Configuration. - Included optional IP allowlisting for enhanced security and deployment options using Helm and Docker Compose. This documentation aims to assist users in effectively connecting their gateways to the Portkey ecosystem. --- .../gateway-registration.mdx | 256 ++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 self-hosting/hybrid-deployments/gateway-registration.mdx diff --git a/self-hosting/hybrid-deployments/gateway-registration.mdx b/self-hosting/hybrid-deployments/gateway-registration.mdx new file mode 100644 index 00000000..ec3cba75 --- /dev/null +++ b/self-hosting/hybrid-deployments/gateway-registration.mdx @@ -0,0 +1,256 @@ +--- +title: "Gateway Registration" +sidebarTitle: "Gateway Registration" +description: "Register your self-hosted AI Gateway with the Portkey Control Plane to enable configuration sync, analytics, and workspace access control." +--- + +## Overview + +Gateway Registration connects your self-hosted AI Gateway to the Portkey Control Plane. Once registered, the Data Plane can pull promt templates, routing configs,integrations, API keys etc. + +The registration flow has three steps: + +1. **Register Gateway** — provide a name, URL, and environment type +2. **Workspace Provisioning** — choose which workspaces can use this gateway +3. **Configure Environment Variables** — save the generated credentials and verify the connection + +--- + +## Step 1: Register Gateway + +Navigate to **Admin Settings → Gateway Registration** and click **Register New Gateway**. + +Fill in the following fields: + +| Field | Description | +|:------|:------------| +| **Gateway Name** | A human-readable label for this gateway (e.g., `dev-ateway`, `prod-gateway`). | +| **Gateway URL** | The publicly reachable HTTPS URL of your deployed gateway (e.g., `https://gateway.example.com`). The Control Plane uses this URL to verify the connection to gateway. | +| **Gateway Type** | Select if it is **Production** or **Non Production** gateway deployment. | + +### Optional: IP Allowlisting + +For additional security, you can restrict inbound traffic to your gateway ingress or firewall to only accept requests from the Portkey Control Plane. + +The Portkey Control Plane egress IPs are: `54.81.226.149`, `34.200.113.35` and `44.221.117.129` + + + IP allowlisting is optional but recommended for production environments. It ensures that only the Portkey Control Plane can initiate inbound connections to your gateway. + + +Click **Next** to continue. + +--- + +## Step 2: Workspace Provisioning + + + Workspace Provisioning is available on the **Hybrid Enterprise plan** only. + + +Choose which workspaces in your organisation will have access to this gateway. + + +### Workspace Access Options + + + + All current and future workspaces in your organisation can route traffic through this gateway. No further configuration is needed. + + + Only the workspaces you explicitly enable will have access to this gateway. + This is useful when you need separate gateways for different teams, business units, or compliance boundaries. + + + +Click **Next** to continue. + +--- + +## Step 3: Configure Environment Variables + +The Control Plane generates a unique set of credentials for your gateway. These credentials authenticate your gateway with the Control Plane and define which organisation it belongs to. + +The following environment variables are generated: + +| Variable | Description | +|:---------|:------------| +| `PORTKEY_CLIENT_AUTH` | Client authentication key used by the gateway to authenticate with the Control Plane. | +| `ORGANISATIONS_TO_SYNC` | The organisation ID(s) the gateway will sync configuration data for. | + + + **Save these environment variables now.** They will not be available again after you leave this screen. Use the **Download .env** button to save a copy locally. + + +### Verify Connection + +Once the environment variables are applied to your running gateway, click **Verify Connection** to confirm the gateway can reach the Control Plane. A successful verification will mark the gateway as **active**. + + + **Connection verification will fail if the gateway is not deployed yet.** Make sure your gateway is running and the environment variables above are set before clicking Verify Connection. See the [Deployment Options](#deployment-options) below if you haven't deployed yet. + + +Click **Done** to complete registration. + +--- + +## Gateway Overview + +After registration, you can manage your gateway from **Admin Settings → Gateway Registration → [Gateway Name]**. + +The overview page shows: + +- **Status badge** (`active` / `inactive`) — updated when you run Verify Connection +- **Gateway URL** — the endpoint registered during setup +- **IP Allowlisting** — the Portkey Control Plane IPs you can add to your firewall +- **Workspace Control tab** — edit workspace access permissions after registration + +--- + +## Deployment Options + +Select a deployment method below and follow the steps to get your gateway running. + + + + **Step 1: Create a `values.yaml` file** + + ```yaml + imageCredentials: + gatewayImage: + repository: "docker.io/portkeyai/gateway" + pullPolicy: Always + tag: "latest" + redisImage: + repository: "docker.io/redis" + pullPolicy: IfNotPresent + tag: "7.2-alpine" + environment: + create: true + secret: true + data: + SERVICE_NAME: dev-gateway # Specify a name for the service + PORTKEY_CLIENT_AUTH: + ORGANISATIONS_TO_SYNC: + ANALYTICS_STORE: control_plane + LOG_STORE: control_plane + service: + type: ClusterIP + port: 80 + containerPort: 8787 + ``` + + `ANALYTICS_STORE` must be set to `control_plane`. Custom `LOG_STORE` configuration is available on the **Hybrid Enterprise plan** only. + + **Step 2: Add the Portkey Helm repository** + + ```bash + helm repo add portkey-ai https://portkey-ai.github.io/helm + helm repo update + ``` + + **Step 3: Install the chart** + + ```bash + # Replace namespace with k8s in which gateway is to be deployed. + helm upgrade --install portkey-ai portkey-ai/gateway -f values.yaml \ + -n --create-namespace + ``` + + **Step 4: Access the gateway** + + For production, expose the gateway via a LoadBalancer or Ingress configured in your `values.yaml`. + + For local testing, use `kubectl port-forward` to access the gateway on your machine: + + ```bash + kubectl port-forward svc/portkey-ai-gateway 8787:80 -n + ``` + + The gateway will be available at `http://localhost:8787`. + + + Create a `docker-compose.yml` file: + + ```yaml + services: + gateway: + image: docker.io/portkeyai/gateway:latest + container_name: gateway + ports: + - "80:8787" + environment: + SERVICE_NAME: "dev-gateway" + PORTKEY_CLIENT_AUTH: "" + ORGANISATIONS_TO_SYNC: "" + CACHE_STORE: "redis" + REDIS_URL: "redis://redis:6379" + LOG_STORE: "control_plane" + ANALYTICS_STORE: "control_plane" + depends_on: + redis: + condition: service_healthy + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8787/v1/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 10s + restart: unless-stopped + redis: + image: docker.io/redis:7.2-alpine + container_name: redis + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 + restart: unless-stopped + ``` + + `ANALYTICS_STORE` must be set to `control_plane`. Custom `LOG_STORE` configuration is available on the **Hybrid Enterprise plan** only. + + + Start the gateway: + + ```bash + docker compose up -d + ``` + + **Access the gateway** + + The gateway is exposed on port `80` of the host machine. It is accessible at `http://` or your configured domain from any machine that can reach the host. + + To verify it is running: + + ```bash + curl http://localhost/v1/health + ``` + + + +--- + +## Connect to the Gateway + +Once your gateway is running and registered, verify it is reachable and routing requests correctly. + +```bash +curl 'https://gateway.example.com/v1/chat/completions' \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -H "x-portkey-provider: openai" \ + -H "x-portkey-api-key: " \ + -d '{ + "model": "gpt-4o-mini", + "messages": [{"role": "user", "content": "What is a fractal?"}] + }' +``` + +Replace the following before running: + +| Placeholder | Value | +|:------------|:------| +| `https://gateway.example.com` | The **Gateway URL** you registered in Step 1 | +| `$OPENAI_API_KEY` | Your OpenAI API key | +| `$PORTKEY_API_KEY` | Your Portkey API key, found in **Settings → API Keys** | From a301146334e592e031adde4cfe829c6c0dd40d6d Mon Sep 17 00:00:00 2001 From: Avanish Yadav Date: Tue, 24 Mar 2026 01:21:00 +0530 Subject: [PATCH 2/2] Add Gateway Registration documentation - Introduced a new guide for registering self-hosted AI Gateways with the Portkey Control Plane. - Detailed the three-step registration process: Gateway Registration, Workspace Provisioning, and Environment Variable Configuration. - Included optional IP allowlisting for enhanced security and deployment options using Helm and Docker Compose. This documentation aims to assist users in effectively connecting their gateways to the Portkey ecosystem. --- docs.json | 2 ++ self-hosting/hybrid-deployments/gateway-registration.mdx | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 4386fbd0..a125475d 100644 --- a/docs.json +++ b/docs.json @@ -275,6 +275,7 @@ "group": "Hybrid Deployments", "pages": [ "self-hosting/hybrid-deployments/architecture", + "self-hosting/hybrid-deployments/gateway-registration", { "group": "AWS", "pages": [ @@ -294,6 +295,7 @@ }, "self-hosting/cache-behavior", "self-hosting/prometheus-metrics", + { "group": "Air-Gapped Deployments", "pages": [ diff --git a/self-hosting/hybrid-deployments/gateway-registration.mdx b/self-hosting/hybrid-deployments/gateway-registration.mdx index ec3cba75..b29f2580 100644 --- a/self-hosting/hybrid-deployments/gateway-registration.mdx +++ b/self-hosting/hybrid-deployments/gateway-registration.mdx @@ -210,7 +210,7 @@ Select a deployment method below and follow the steps to get your gateway runnin `ANALYTICS_STORE` must be set to `control_plane`. Custom `LOG_STORE` configuration is available on the **Hybrid Enterprise plan** only. - + Start the gateway: ```bash @@ -253,4 +253,4 @@ Replace the following before running: |:------------|:------| | `https://gateway.example.com` | The **Gateway URL** you registered in Step 1 | | `$OPENAI_API_KEY` | Your OpenAI API key | -| `$PORTKEY_API_KEY` | Your Portkey API key, found in **Settings → API Keys** | +| `$PORTKEY_API_KEY` | Your Portkey API key |