> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Install the data plane with Helm

> Install the Fabric AI Gateway data plane in your Kubernetes cluster with Helm, see what Helm does in order, and verify the install.

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](/run/plan-a-deployment), and the egress in [Network and egress](/run/network).
* 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:10` for the migration Job (MySQL store only), `ghcr.io/huggingface/text-embeddings-inference:cpu-1.9` for the embedder, `otel/opentelemetry-collector-contrib:0.149.0` for the collector sidecar, and `openpolicyagent/opa:1.20.2` if you turn on `opa.enabled`. The embedder is always deployed, and it downloads its model from `huggingface.co` at startup unless you run it offline. See [Embedder](/run/embedder).
* A MySQL database and user for the data plane, reachable from the cluster, unless you use the distributed secret store. See [Database migrations](/run/database-migrations#prerequisites) and [Scale and high availability](/run/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](/run/connect-a-data-plane).
* `kubectl` and 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 `default` ServiceAccount 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

1. Create the namespace:

   ```bash
   kubectl create namespace pm-fabric-dp
   ```

2. If the migration image comes from a private registry, add your pull Secret to the namespace's `default` ServiceAccount, which the migration Job runs as:

   ```bash
   kubectl -n pm-fabric-dp patch serviceaccount default \
     -p '{"imagePullSecrets":[{"name":"<pull-secret-name>"}]}'
   ```

3. 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](/run/secrets-and-keys#create-the-app-secret).

4. 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](/run/secrets-and-keys#the-control-plane-ca-certificate).

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.

```yaml
image:
  repository: registry.example.com/fabric/gateway
  tag: "<tag-from-postman>"
  imagePullSecrets: "<pull-secret-name>"   # omit for a registry without credentials

secrets:
  app:
    existingSecret: fabric-dp-secrets

syncCA:
  pem: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

attestation:
  enabled: true   # omit if you enroll with a bootstrap token

env:
  vars:
    FABRIC_GW_TENANT_ID: "<your-tenant-id>"
    FABRIC_GW_CP_ADDRESS: "<control-plane-sync-address>"
    FABRIC_GW_MYSQL_HOST: "<mysql-host>"   # add :<port> if MySQL isn't on 3306
    FABRIC_GW_MYSQL_USER: "<mysql-user>"
    FABRIC_GW_MYSQL_DATABASE: "fabric_gateway"
    # The external URL clients use to reach the gateway
    FABRIC_GW_ADMIN_EXTERNAL_URL: "https://gateway.example.com"
    FABRIC_GW_BROKER_EXTERNAL_URL: "https://gateway.example.com"
```

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](/guides/observability/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](/run/helm-values).

## Install the chart

1. Preview what the chart creates, without installing anything:

   ```bash
   helm template fabric-dp ./fabric-gateway-chart -n pm-fabric-dp -f my-values.yaml | less
   ```

2. 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.

3. Install:

   ```bash
   helm install fabric-dp ./fabric-gateway-chart -n pm-fabric-dp -f my-values.yaml
   ```

Replace `./fabric-gateway-chart` with the path to the chart Postman gave you.

> **Note**
>
> 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

1. **Loads the migrations.** Helm creates a ConfigMap with the chart's SQL migration files.
2. **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.backoffLimit` times (default `2`) before the Job fails. After you fix the cause, run the install again with `helm upgrade --install fabric-dp ./fabric-gateway-chart -n pm-fabric-dp -f my-values.yaml`. Running `helm install` a second time fails, because the failed release still holds the name. See [Database migrations](/run/database-migrations).
3. **Applies the release.** Helm creates the gateway Deployment, Service, ServiceAccount, PodDisruptionBudgets, ConfigMaps, and the embedder.
4. **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 a `503` or a `404`.

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

1. Check the migration Job. It deletes itself when it succeeds, so `No resources found` is the expected result. A Job that's still there failed. Read its logs with `kubectl -n pm-fabric-dp logs job/fabric-gateway-chart-dp-migrate`.

   ```bash
   kubectl -n pm-fabric-dp get jobs -l app.kubernetes.io/name=fabric-gateway-chart
   ```

2. Check the pods. Gateway pods show `READY 2/2` (the gateway and its collector sidecar), `1/1` without the sidecar, or `3/3` with both sidecars (`2/2` with OPA and no collector). The embedder shows `READY 1/1`.

   ```bash
   kubectl -n pm-fabric-dp get pods -l app.kubernetes.io/name=fabric-gateway-chart
   kubectl -n pm-fabric-dp get pods -l app=fabric-gateway-embedder
   ```

   > **Warning**
   >
   > With `opa.enabled`, the OPA sidecar never passes its readiness check, so gateway pods stay at `READY 2/3` and get no traffic. See [Helm values](/run/helm-values#feature-toggles).

3. Check that the gateway enrolled and started, with no restart loop:

   ```bash
   kubectl -n pm-fabric-dp logs deploy/fabric-gateway-chart -c fabric-gateway-chart \
     | grep -iE "dp enrollment|sync|started"
   ```

   With the distributed secret store, use `sts/fabric-gateway-chart` instead of `deploy/fabric-gateway-chart`.

4. Check that the gateway answers its health endpoint:

   ```bash
   kubectl -n pm-fabric-dp port-forward svc/fabric-gateway-chart 8080:8080
   curl -s localhost:8080/healthz
   ```

   The response is `{"status":"ok"}`. The gateway also serves `/readyz` on port `8080`. It answers `200` once 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](/run/monitor#health-endpoints).

5. In the console, open **Admin**, and then select **Gateway health**. Each gateway pod appears as a node. See [Connect to the control plane](/run/connect-a-data-plane#check-the-data-plane-in-the-console).

If a gateway pod restarts in a loop, check its logs for enrollment errors. See [Troubleshooting](/run/troubleshooting).

## Next steps

* To let clients outside the cluster reach the gateway, see [Expose the gateway](/run/expose-the-gateway).
* Before you send production traffic, work through the [Production checklist](/run/production-checklist).
* To set up dashboards and alerts, see [Monitor the data plane](/run/monitor).