Skip to main content

Components and Sizing Recommendations

Prerequisites

Ensure that following tools and resources are installed and available:
  • A running GKE cluster with at least 2 worker nodes. ( Best Practice: Use 2 nodes, with 1 node in each Availability Zone, to ensure high availability.)
  • VPC which host GKE cluster must have ACTIVE subnet with purpose REGIONAL_MANAGED_PROXY.
  • gcloud CLI
  • Kubectl
  • Helm (v3 or above)

Create a Portkey Account

  • Go to the Portkey website.
  • Sign up for a Portkey account.
  • Once logged in, locate and save your Organisation ID for future reference. You can find it in the browser URL: https://app.portkey.ai/organisation/<organisation_id>/
  • Contact the Portkey AI team and provide your Organisation ID and the email address used during signup.
  • The Portkey team will share the following information with you:
    • Docker credentials for the Gateway images (username and password).
    • License: Client Auth Key.

Setup Project Environment

Image Credentials Configuration

Configure Components

Based on the choice of components and their configuration update the values.yaml.

MCP Gateway (Optional)

By default, only the AI Gateway is enabled in the deployment. To enable the MCP Gateway, add the following configuration to values.yaml:
Note:
  • MCP_GATEWAY_BASE_URL must include the protocol prefix — either http:// or https://.
  • This value is not required for the initial deployment. After the first deployment, once the MCP Load Balancer is provisioned and a hostname is mapped to the MCP Service, set this value and redeploy.
Server Modes
  1. "" (empty or not provided): Deploys only the AI Gateway. This is the default configuration.
  2. "mcp": Deploys only the MCP Gateway.
  3. "all": Deploys both the AI Gateway and MCP Gateway.

Cache Store

The Portkey Gateway deployment includes a Redis instance pre-installed by default. You can either use this built-in Redis or connect to an external cache like Google Memorystore Redis or Valkey.

Built-in Redis

No additional permissions or network configurations are required.

Google Memorystore

To enable the gateway to work with a Memorystore cache, ensure that network access from GKE cluster on required port.
TLS (Optional) If TLS is enabled on your GCP Memorystore Redis instance, you must provide the self-signed certificate to the Gateway to enable SSL/TLS connections.
  1. Download the certificate file server-ca.pem from your GCP Memorystore Redis cluster.
  2. Create a Kubernetes secret to store the Memorystore certificate:
  3. Add the following configuration to values.yaml:

Log Store

Google Cloud Storage

  1. Create a GCS bucket for storing LLM access logs.
  2. Set up access to the log store. The Gateway supports the following methods for connecting to GCS bucket for log storage:
    • Workload Identity Federation
    • HMAC
    Depending on the chosen GCS access method, update values.yaml with the following configuration.
    To set up IAM-based authentication for Portkey Gateway to GCP bucket, follow the steps and add following configuration in values.yaml.
  3. (Optional) Configure log path format using LOG_STORE_FILE_PATH_FORMAT. See Log Object Path Format for details.

Data Service (Optional)

The Data Service is a component of the Portkey deployment responsible for batch processing, fine-tuning, and log exports. To enable Data Service, add the following configuration to the values.yaml file.

Network Configuration

Set Up External Access

To make the Gateway service accessible externally, you can set up either of the following:
  • GCS Application Load Balancer with Kubernetes Ingress
  • GCS Network Load Balancer with Kubernetes Service
Prerequisites
  • GKE cluster must have HTTP Load Balancing add-on enabled.
  • Load Balancers require an active subnet with purpose REGIONAL_MANAGED_PROXY. If you don’t have one, create it:

GCP Load Balancer Ingress

To create Application Load Balancer Ingress update the values.yaml file with following configuration:
Note: If SERVER_MODE is set to all (i.e., both AI Gateway and MCP Gateway are enabled), you must enable host-based routing by setting hostBased to true and provide the hostname on which the AI Gateway and MCP Gateway will be accessible. GCP Load Balancer Controller provides additional annotations (like TLS, custom health checks etc ) for managing Ingress Load Balancer. For a comprehensive list of available annotations, refer to the GCP Ingress Load Balancer.

GCP Load Balancer Service

To create Load Balancer update the values.yaml with following configuration:
GCP Load Balancer Controller provides additional annotations (like TLS, custom health checks etc ) for managing Service Load Balancer. For a comprehensive list of available annotations, refer to the GCP Service Load Balancer.

Deploying Portkey Gateway

Verify the deployment

To confirm that the deployment was successful, follow these steps:
  • Verify that all pods are running correctly.
Note: If pods are in a Pending, CrashLoopBackOff, or other error state, inspect the pod logs and events to diagnose potential issues.
  • Test Gateway by sending a cURL request.
    1. Port-forward the Gateway pod
    1. Once port forwarding is active, open a new terminal window or tab and send a test request by running:
    1. Test gateway service integration with Load Balancer.

Integrating Gateway with Control Plane

Outbound Connectivity (Data Plane to Control Plane) Portkey supports the following methods for integrating the Data Plane with the Control Plane for outbound connectivity:
  • GCP Private Service Connect
  • Over the Internet
Ensure Outbound Network Access By default, Kubernetes allows full outbound access, but if your cluster has NetworkPolicies that restrict egress, configure them to allow outbound traffic. Example NetworkPolicy for Outbound Access:
This allows the gateway to access LLMs hosted both within your VPC and externally. This also enables connection for the sync service to the Portkey Control Plane.

GCP Private Service Connect

Establishes a secure, private connection between the Control Plane and Data Plane within the GCP network. Steps to establish GCP Private Service Connect connectivity:
  1. (Optional) Create a subnet in region us-east4 if you don’t already have one.
  1. Create an IP address for the PSC endpoint.
  1. Contact the Portkey team, share your GCP Project ID, and request private connectivity.
  2. Once your project has been whitelisted and Portkey has shared the SERVICE_ATTACHMENT_URI, create the forwarding rule for the Control Plane’s private endpoint.
  1. (Optional) If your GKE cluster is in a different region from us-east4, enable global access on the PSC endpoint.
  1. Fetch Connection ID of PSC endpoint and share it with the Portkey for connection approval.
  1. Once Portkey confirms approval, verify the connection status:
  1. Fetch Private IP of PSC endpoint.
  1. Create a Private DNS Zone for DNS resolution of Control Plane PSC endpoint.
  1. Create a DNS record to point to Portkey PSC endpoint IP.
  1. If connection status changes to ACCEPTED, update the values.yaml file with the following environment variables.
  1. Re-deploy the gateway.
  2. Check the Gateway pod logs to verify that no errors related to connection timeout or DNS resolution appear.

Over the Internet

Ensure Gateway has access to following endpoints over the internet.
  • https://api.portkey.ai
  • https://albus.portkey.ai

Inbound Connectivity (Control Plane to Data Plane)

  • GCP Private Service Connect
  • IP Whitelisting

GCP Private Service Connect

Establishes a secure, private connection between the Control Plane and Data Plane within the GCP network. Prerequisites:
  • Portkey Gateway must be exposed via either:
    • Regional internal Application Load Balancer, or
    • Regional internal proxy Network Load Balancer
  • A Private DNS Zone assocated to GKE VPC network and A record pointing to internal Load Balancer’s Private IP.
  • PSC requires an active subnet with purpose PRIVATE_SERVICE_CONNECT. If you don’t have one, create it:
Steps to establish GCP Private Service Connect connectivity:
  1. Go to Private Service Connect > Published services and click Publish service.
  2. Under Target details, select the Load Balancer option:
    • If you exposed the Gateway using Ingress in values.yaml, select Regional internal Application Load Balancer.
    • Otherwise, select Regional internal proxy Network Load Balancer.
  3. Select the Portkey Gateway’s Load Balancer and the forwarding rule associated with it.
  4. Under Service details:
    • Provide a name for the service (e.g., <org_name>-gateway-psc).
    • Select the subnet that was created for PSC.
  5. Under Connections preference, select Accept connections for selected projects and add project pk-production-project to the accepted projects list.
  6. Once the PSC service is created, copy the Service attachment and share it with the Portkey team so they can initiate a connection request. In addition to that also share AI Gateway URL (e.g., https://gateway.example.com).
  7. Once the connection is initiated from the Control Plane, go to your PSC Published Service and approve the connection request.
  8. To verify connectivity from the Control Plane to the Data Plane, send a test request to the Gateway and check if you can view the full log details on the Portkey app after clicking a log entry.

IP Whitelisting

Allows control plane to access the Data Plane over the internet by restricting inbound traffic to specific IP address of Control Plane. This method requires the Data Plane to have a publicly accessible endpoint. To whitelist, add an inbound rule to the VPC Firewall allowing connections from the Portkey Control Plane’s IPs (54.81.226.149, 34.200.113.35, 44.221.117.129) on Load Balancer listner port. To integrate the Control Plane with the Data Plane, contact the Portkey team and provide the Public Endpoint of the Data Plane.

Verifying Gateway Integration with the Control Plane

  • Send a test request to Gateway using curl.
  • Go to Portkey website -> Logs.
  • Verify that the test request appears in the logs and that you can view its full details by selecting the log entry.

Uninstalling Portkey Gateway

Setting up IAM Permission

To enable the Portkey Gateway to access GCS bucket for log storage and, optionally, Vertex AI for model invocation, specific permissions are required. Follow the steps below to configure permissions based on your chosen access method.
  1. Create a Google Service Account.
  2. Create an IAM Policy binding to bind GSA to Gateway’s KSA.
  3. Grant the required permissions to the GSA for accessing the GCS bucket. You can either assign the roles/storage.objectAdmin role to the GSA, or create a custom role with only the necessary permissions, such as storage.objects.create and storage.objects.get, and attach that role instead.

    GCS Bucket

    Same Project Access
    Cross Project Access
  4. (Optional) To allow the Gateway to access Vertex AI models, grant the roles/aiplatform.user role to the GSA.

    Vertex AI

    Same Project Access
    Cross Project Access
Last modified on April 8, 2026