Components and Sizing Recommendations
Prerequisites
Ensure that following tools and resources are installed and available:
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
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
"" (empty or not provided): Deploys only the AI Gateway. This is the default configuration.
"mcp": Deploys only the MCP Gateway.
"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 Amazon ElastiCache for Redis OSS or Valkey.
Built-in Redis
No additional permissions or network configurations are required.
Amazon ElastiCache
To enable the gateway to work with an ElastiCache cache, ensure that inbound rule is configured in ElastiCache’s Security Group allowing access from EKS cluster on required port.
Note: If cluster mode is enabled in ElastiCache then use Configuration Endpoint otherwise use Primary Endpoint.
For more information on ElastiCache endpoints, refer to the AWS resources.
Log Store
Amazon S3
-
Create an Amazon S3 bucket for storing LLM access logs.
-
Set up access to the log store. The Gateway supports the following methods for connecting to S3 bucket for log storage:
- IAM Roles for Service Accounts (IRSA)
- EKS Pod Identity
Depending on the chosen S3 access method, update values.yaml with the following configuration.
-
(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:
- AWS Application Load Balancer with Kubernetes
Ingress
- AWS Network Load Balancer with Kubernetes
Service
Prerequisites
- VPC and subnet tagging requirements
- Installed and running AWS Load Balancer Controller. For Load Balancer Controller installation details, refer to the AWS documentation.
AWS Application Load Balancer
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.
Load Balancer Controller provides additional annotations (like TLS, custom health checks etc ) for managing ALB. For a comprehensive list of available annotations, refer to the AWS Load Balancer Controller documentation.
AWS Network Load Balancer
To create Network Balancer update the values.yaml with following configuration:
Note: service.containerPort must be same as environment.data.PORT.
Load Balancer Controller provides additional annotations (like TLS, custom health checks etc ) for managing NLB. For a comprehensive list of available annotations, refer to the AWS Load Balancer Controller documentation.
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.
- Port-forward the Gateway pod
- Once port forwarding is active, open a new terminal window or tab and send a test request by running:
- 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:
- AWS PrivateLink
- 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.
AWS PrivateLink
Establishes a secure, private connection between the Control Plane and Data Plane within the AWS network.
Steps to establish AWS PrivateLink connectivity:
- Contact Portkey and provide AWS account ARN so it can be whitelisted in Portkey’s Control Plane.
- Once you get confirmation from Portkey that your AWS account is whitelisted, go to the VPC Console.
- Select the AWS Region where the Portkey Gateway is deployed.
- Navigate to the Endpoints section in the VPC console.
- Click on Create endpoint and enter the required details.
- Select the
PrivateLink Ready partner services category and, under Service settings, provide the following details.
- For Service name, enter
com.amazonaws.vpce.us-east-1.vpce-svc-0c2c1c323d9f56d95
- (Optional) If the Gateway is deployed in a region other than
us-east-1, select Enable Cross Region endpoint, choose the us-east-1 region, and click the Verify service button.
- Under Network settings
- Select the VPC and subnets (at least two in different AZs for high availability) where the endpoint should be created. Ideally, this should be the same VPC where the Gateway is deployed.
- Select the security group to associate with the endpoint. The security group must allow inbound connections on port 443 from the Gateway.
- After all details are filled in, click on Create endpoint.
- Wait for the Status to change to
Available.
- Once the status changes to
Available, click on Actions > Modify private DNS name > Select Enable for this endpoint.
- Update the
values.yaml file with following config.
- Re-deploy the gateway.
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)
- AWS PrivateLink
- IP Whitelisting
AWS PrivateLink
Establishes a secure, private connection between the Control Plane and Data Plane within the AWS network.
Steps to establish AWS PrivateLink connectivity:
To use AWS PrivateLink, you must create an AWS Network Load Balancer (NLB)—either internal or internet-facing—to expose the Gateway outside the EKS cluster.
For detailed instructions on creating and integrating an NLB, please refer to the Networking Configuration
Create Endpoint Service
- Navigate to the AWS VPC Console.
- In the top-right corner of the AWS Console, select the region where the Portkey Gateway is deployed.
- Provide the following details -
- Name of endpoint service
- Select Network Load Balancer to associate with Endpoint.
- Choose region in which endpoint service will be available.
- Select whether acceptance is required or not for requested connections.
- Choose whether to enable private DNS name - If enabled provide the Private DNS Name.
- Select IPv4 under Supported IP address types.
- Click Create.
(Optional) Verify ownership of Private DNS name
This step needs to be performed if you are using Private DNS Name.
Open created Endpoint Service > click on Actions > select Verify domain ownership for private DNS name > Create the recommended record in your DNS server > Click Verify.
Authorize Portkey’s Control Plane to initiate connection requests
- Open to Endpoint Service > click on Actions > select Allow principals, and enter the Control Plane’s ARN(
arn:aws:iam::299329113195:root).
Reach out to portkey team and share the following details -
- Service name
- DNS names
- Private DNS name
- Region selected while creating Endpoint Service.
- Port number on which Load Balancer is listening for connections.
- Wait for the Portkey team to initiate a connection request from the control plane’s AWS account to your Gateway AWS account. Navigate to the Endpoint connections section and once the request appears, approve it.
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 Load Balancer’s security group allowing connections from the Portkey Control Plane’s IPs (54.81.226.149, 34.200.113.35, 44.221.117.129) on NLB listener 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 Amazon S3 for log storage and, optionally, Amazon Bedrock for model invocation, specific permissions are required.
Follow the steps below to configure permissions based on your chosen access method.
- Create an IAM trust policy to provide Gateway access to IAM Role.
- Create an IAM Role to associate with Gateway’s service account.
Note: Record the IAM role ARN for future reference, as it will be required when configuring the Gateway’s service account in values.yaml.
- Attach an IAM policy to the role to grant access to the S3 log store and, optionally, Amazon Bedrock.
Amazon S3(Optional) Amazon Bedrock
- (Optional) If the EKS Pod Identity Agent is not already installed on your cluster, install it before proceeding. For detailed, step-by-step instructions, refer to the following AWS documentation.
- Create an IAM trust policy to provide Gateway access to IAM Role.
- Create an IAM Role to associate with Gateway’s service account.
- Create a Pod Identity association that allows the Gateway’s service account to assume the specified IAM role using EKS Pod Identity.
- Attach an IAM policy to the role to grant access to the S3 log store and, optionally, Amazon Bedrock.
Amazon S3(Optional) Amazon Bedrock
Examples
Built-in Redis
The following sample values.yaml below shows how to configure the built-in Redis cache and Amazon S3 log store using IRSA.
Last modified on April 8, 2026