Deploy the Passport Proxy | Passport from Postman

This page walks you through deploying the Passport Proxy in your Kubernetes environment. By the end, you’ll have a running proxy that intercepts and logs API traffic and is ready to register with Passport Cloud.

The proxy image and Helm chart are served from the Passport registry at oci-registry-proxy.postman-beta.tech. You’ll pull them using a credential generated in your team’s Registry settings, configure a values file for your environment, and deploy using Helm.

This deployment process is only supported from macOS and Linux.

Prerequisites

Before you begin, make sure you have the following:

macOS or Linux
Docker, Kubernetes, and Helm installed and configured
A registry credential (see Generate a registry credential)

Generate a registry credential

A Passport Admin generates a single registry credential for the team in the Passport app. The credential’s value is shown only once, when it’s created.

To generate a registry credential, do the following:

In the Passport app, click Org Settings in the header.
Select Registry.
Click Generate credential.
Copy the credential value and export it as an environment variable:
```
export PASSPORT_REGISTRY_KEY="<your-credential>"
```

Store this credential securely. It won’t be shown again after you leave the page.

Pull the Docker image

printf '%s' "$PASSPORT_REGISTRY_KEY" | docker login oci-registry-proxy.postman-beta.tech \
  --username passport --password-stdin
docker pull oci-registry-proxy.postman-beta.tech/passport/passport-proxy:latest

Note the image name and tag for later. You’ll need them when configuring values.yaml.

To let Kubernetes pull the image directly from the Passport registry instead of mirroring it to your own, create a pull secret:

kubectl create secret docker-registry passport-registry \
  --docker-server=oci-registry-proxy.postman-beta.tech \
  --docker-username=passport \
  --docker-password="$PASSPORT_REGISTRY_KEY"

Then reference passport-registry from your values.yaml.

Pull the Helm chart and export default values

Log Helm in to the same registry and write the chart’s default values to a file you can edit:

printf '%s' "$PASSPORT_REGISTRY_KEY" | helm registry login oci-registry-proxy.postman-beta.tech \
  --username passport --password-stdin
helm show values oci://oci-registry-proxy.postman-beta.tech/passport/chart \
  --version 0.4.0 > values.yaml

Configure values.yaml

Edit the values.yaml file from the previous step for your environment. At minimum, configure the following:

Container image and registry
Kubernetes and networking configuration
Storage and S3 (required for the Proxy Console)
Vault permission keys (HashiCorp Vault or AWS Secrets Manager)
Credentials and secrets
Hostnames and endpoints

Deploy the Proxy

To install the chart with your configured values file, use the following command:

helm install --generate-name \
  oci://oci-registry-proxy.postman-beta.tech/passport/chart \
  --version 0.4.0 -f values.yaml

After installation, note the following values. You’ll need them when registering the proxy in Passport.

Item	Value
Proxy	`<proxy_url>:8443`
Management Host	`<management_url>`
Console	`<management_url>/console`
Console credentials	Configured in `values.yaml`
Public key	Generated during installation

Rotate or revoke the registry credential

A Passport Admin can rotate or revoke the registry credential from the Registry tab in the Passport app at any time.

To rotate the credential, do the following:

In the Passport app, click Org Settings in the header.
Select Registry.
Click Rotate credential. This generates a new credential and invalidates the previous one. Use this to cycle the credential on a regular basis or after a suspected exposure.
Update PASSPORT_REGISTRY_KEY in any environment or CI system that uses it, and re-authenticate Docker and Helm.

To revoke the credential, do the following:

In the Passport app, click Org Settings in the header.
Select Registry.
Click Revoke credential. This permanently invalidates the credential without generating a replacement. Any registry pull that relies on the revoked credential fails until a new one is generated.

API traffic logging

The proxy logs API traffic in OpenTelemetry (OTEL) format. Namespaces aren’t required for logging. Traffic is logged once the proxy is running. You can view logged traffic at <management_url>/console.

You can export those OTEL logs and use them as a source when adding resources to a namespace to identify the APIs being accessed.

Next steps

After the proxy is running, register it in Passport so your team can use it.