Install the data plane with Helm
This page applies to the Enterprise plan, where the control plane runs in Postman cloud and you run the data plane in your own VPC. It walks through a first install with the Helm chart Postman provides: mirroring the image, creating the Secrets, writing a values file, installing, and checking that the data plane came up and enrolled.
The examples use the release name fabric-dp and the namespace pm-fabric-dp. Resource names come from the chart, so the gateway Deployment and Service are named fabric-gateway-chart whatever release name you use. A few names are fixed too: the embedder (fabric-gateway-embedder), the collector ConfigMap (fabric-gateway-otel-collector-config), and the default CA Secret (fabric-dp-sync-ca). Keep the release name fabric-dp, as the chart’s values file requires.
Prerequisites
Before you begin, make sure you have the following:
- A cluster and capacity that meet Requirements and sizing, and the egress in Network and egress.
- The chart, the gateway image, your tenant ID, and the control plane’s sync address from Postman.
- Pull access from the cluster to the public images the chart also uses, or mirrored copies of them:
flyway/flyway:10for the migration Job (MySQL store only),ghcr.io/huggingface/text-embeddings-inference:cpu-1.9for the embedder,otel/opentelemetry-collector-contrib:0.149.0for the collector sidecar, andopenpolicyagent/opa:1.20.2if you turn onopa.enabled. The embedder is always deployed, and it downloads its model fromhuggingface.coat startup unless you run it offline. See Embedder. - A MySQL database and user for the data plane, reachable from the cluster, unless you use the distributed secret store. See Database migrations and Scale and high availability.
- An enrollment method. Workload attestation is recommended: register the trust anchor in the console before you install. See Connect to the control plane.
kubectland Helm 3 or later, with access to the cluster.
Mirror the image
Copy the gateway image Postman provides into a registry your cluster can pull from, and pin the tag Postman gives you. If the registry is private, create an image pull Secret in the data plane’s namespace, and reference it for each component:
- The gateway pod, including the collector and OPA sidecars: set
image.imagePullSecrets. - The embedder: set
embedder.image.imagePullSecrets. - The migration Job: it has no pull Secret setting of its own. Add the Secret to the namespace’s
defaultServiceAccount after you create the namespace.
The embedder, collector, OPA, and migration images come from public registries by default. To pull them from your registry instead, mirror them and set embedder.image.repository, the collector image in additionalContainers, opa.image.repository, and migrations.image.
To change the collector image, copy the whole otel-collector entry under additionalContainers from the chart’s values.yaml into your values file, and change only image. Helm replaces lists rather than merging them, so a partial entry drops the collector’s configuration.
Create the namespace and Secrets
-
Create the namespace:
-
If the migration image comes from a private registry, add your pull Secret to the namespace’s
defaultServiceAccount, which the migration Job runs as: -
Create the app Secret with your encryption key and MySQL password, plus a bootstrap token only if you enroll with one. See Secrets and keys.
-
Get the control plane CA certificate. You can put it in your values file in the next step, or create it as a Secret. See Secrets and keys.
The app Secret must exist before you install, because the migration Job reads the MySQL password from it during the install. For throwaway tests only, secrets.dev.enabled: true makes the chart create the Secret for you as a hook. Don’t use it in production.
Write a values file
Create my-values.yaml with the values for your environment. Keys you leave out keep the chart’s defaults. The chart’s defaults for the image, tenant, sync address, MySQL host, and external URLs are placeholders, so set every value below.
If MySQL listens on a port other than 3306, include the port in FABRIC_GW_MYSQL_HOST, for example db.internal:3307. Don’t set only FABRIC_GW_MYSQL_PORT: the migration Job ignores it and connects to 3306.
Then choose where telemetry goes. By default, the collector sidecar exports to ClickHouse: set otel.clickhouse.endpoint, otel.clickhouse.database, and otel.clickhouse.username, and put the password in the app Secret as FABRIC_GW_CLICKHOUSE_PASSWORD. To send telemetry to another OTLP backend, see OpenTelemetry. If the key is missing, the pod still starts, but the collector’s ClickHouse password is empty and telemetry is dropped. To turn export off, set otelCollector.enabled: false, and set OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, and OTEL_LOGS_EXPORTER to "none" under env.vars. With export off, requests don’t appear on the console’s Traces page. If you leave any exporter on, the gateway keeps trying to reach the missing sidecar, and Gateway health reports its telemetry export as degraded.
For the full list of values and a retarget checklist, see Helm values.
Install the chart
-
Preview what the chart creates, without installing anything:
-
Make sure the MySQL host in your values is reachable from the cluster and the password in the app Secret is correct. The migration Job runs as part of the install and needs both.
-
Install:
Replace ./fabric-gateway-chart with the path to the chart Postman gave you.
After the install, Helm prints the chart’s notes. Two of them are out of date: your encryption key doesn’t need to match the control plane’s, and the gateway does serve /readyz on port 8080.
What Helm does, in order
- Loads the migrations. Helm creates a ConfigMap with the chart’s SQL migration files.
- Runs the schema migration Job. The Job connects to MySQL with the credentials from the app Secret and applies any migrations the database doesn’t have yet. If a migration fails, the install stops here, and no gateway pod starts. Kubernetes retries a failed migration Pod up to
migrations.backoffLimittimes (default2) before the Job fails. After you fix the cause, run the install again withhelm upgrade --install fabric-dp ./fabric-gateway-chart -n pm-fabric-dp -f my-values.yaml. Runninghelm installa second time fails, because the failed release still holds the name. See Database migrations. - Applies the release. Helm creates the gateway Deployment, Service, ServiceAccount, PodDisruptionBudgets, ConfigMaps, and the embedder.
- Starts the pods. Each gateway pod mounts the CA certificate, loads the app Secret as environment variables, enrolls with the control plane, starts listening on port
8080, and receives your configuration. A request that arrives before a pod has its configuration can get a503or a404.
The gateway itself never changes the database schema. Schema changes only come from the migration Job, or from you if you run migrations yourself.
With the distributed secret store, Helm skips the migration Job, and the gateway runs as a StatefulSet instead of a Deployment.
Verify the install
-
Check the migration Job. It deletes itself when it succeeds, so
No resources foundis the expected result. A Job that’s still there failed. Read its logs withkubectl -n pm-fabric-dp logs job/fabric-gateway-chart-dp-migrate. -
Check the pods. Gateway pods show
READY 2/2(the gateway and its collector sidecar),1/1without the sidecar, or3/3with both sidecars (2/2with OPA and no collector). The embedder showsREADY 1/1.With
opa.enabled, the OPA sidecar never passes its readiness check, so gateway pods stay atREADY 2/3and get no traffic. See Helm values. -
Check that the gateway enrolled and started, with no restart loop:
With the distributed secret store, use
sts/fabric-gateway-chartinstead ofdeploy/fabric-gateway-chart. -
Check that the gateway answers its health endpoint:
The response is
{"status":"ok"}. The gateway also serves/readyzon port8080. It answers200once the process is running, unless the OPA sidecar is on and its policy bundle hasn’t loaded. It doesn’t wait for your configuration. See Health endpoints. -
In the console, open Admin, and then select Gateway health. Each gateway pod appears as a node. See Connect to the control plane.
If a gateway pod restarts in a loop, check its logs for enrollment errors. See Troubleshooting.
Next steps
- To let clients outside the cluster reach the gateway, see Expose the gateway.
- Before you send production traffic, work through the Production checklist.
- To set up dashboards and alerts, see Monitor the data plane.

