Skip to navigation

Helm values

This page applies to the Enterprise plan, where you run the data plane in your own VPC. It covers how to apply configuration, the values to change for every install, the values you’re most likely to set, how environment variables are layered, and the hardening defaults that are already on. The chart’s own values.yaml has the full list, including advanced pod and container settings. The chart doesn’t support nodeSelector, affinity, or tolerations for gateway pods. Setting them fails the install.

Applying configuration

Keep your overrides in a values file in version control, and pass it on every install and upgrade:

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

You can also set a single value with --set, for example --set env.vars.LOG_LEVEL=debug. Helm doesn’t remember --set flags from a previous release, so a value set this way is lost on the next upgrade unless you repeat it. Prefer the values file for anything you want to keep.

The chart ships a values schema that checks the types of its core values, so a mistake such as a string where a boolean belongs fails when Helm renders the chart, before anything is deployed. It doesn’t reject keys it doesn’t know.

Retarget checklist

The chart’s defaults for your environment are placeholders. Before you install, set:

  • image.repository and image.tag: your mirrored image and the tag Postman gives you. Add image.imagePullSecrets if the registry is private.

  • secrets.app.existingSecret: the name of the app Secret you created. Set it explicitly, even if you use the default name.

  • syncCA.pem: the control plane CA certificate, unless you create the fabric-dp-sync-ca Secret instead.

  • attestation.enabled: true if you enroll with workload attestation.

  • env.vars.FABRIC_GW_TENANT_ID: your tenant ID. An empty value stops the data plane from starting.

  • env.vars.FABRIC_GW_CP_ADDRESS: the control plane’s sync address.

  • env.vars.FABRIC_GW_MYSQL_HOST, FABRIC_GW_MYSQL_USER, and FABRIC_GW_MYSQL_DATABASE: your MySQL, with the MySQL secret store.

  • env.vars.FABRIC_GW_ADMIN_EXTERNAL_URL and FABRIC_GW_BROKER_EXTERNAL_URL: the external URL clients use. See Expose the gateway.

  • otel.clickhouse.*, or another telemetry setup: the default ClickHouse endpoint is an example host. See OpenTelemetry.

  • env.vars.FABRIC_GW_SSRF_BLOCK_PRIVATE_UPSTREAMS (optional): "true" to stop routes from reaching upstreams on private addresses. See Calls to private hosts.

  • env.vars.OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES (optional): the service and environment labels on your telemetry.

  • accountId, roleName, and iam.* (AWS only): leave them blank and iam.enabled off unless you use an IAM role for the gateway’s ServiceAccount. roleName becomes the role ARN arn:aws:iam::<accountId>:role/auto-<roleName>. To use an existing role with any other name, leave roleName blank and set the annotation yourself:

    serviceAccount:
    annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<account-id>:role/<role-name>

Required values

ValueDefaultDescription
image.repository<your-registry>/fabric/gatewayRepository of the mirrored gateway image.
image.tagThe build the chart was released withImage tag Postman gives you.
env.vars.FABRIC_GW_TENANT_ID""Your tenant ID. Must match the tenant your enrollment credential was issued for.
env.vars.FABRIC_GW_CP_ADDRESS""The control plane’s sync address, as host:port.
env.vars.FABRIC_GW_MYSQL_HOSTyour-dp-mysql-hostMySQL host, with the MySQL secret store. If MySQL isn’t on port 3306, include the port, for example db.internal:3307. Don’t set only FABRIC_GW_MYSQL_PORT: the migration Job ignores it.
env.vars.FABRIC_GW_ADMIN_EXTERNAL_URLhttps://fabric-gateway-dp.example.comExternal base URL of your data plane, used for OAuth callbacks.
env.vars.FABRIC_GW_BROKER_EXTERNAL_URLhttps://fabric-gateway-dp.example.comExternal base URL used for account-connection links and callbacks when users connect upstream accounts. Usually the same as the admin URL.
syncCA.pem""The control plane CA certificate, as PEM text. Leave empty if you create the fabric-dp-sync-ca Secret instead.

Image

ValueDefaultDescription
image.digest""Pins the image by digest. When set, the chart renders repository@digest.
image.pullPolicyIfNotPresentKubernetes image pull policy.
image.imagePullSecrets""Name of an image pull Secret for a private registry.

Secrets

ValueDefaultDescription
secrets.app.existingSecret""Name of the app Secret you created. Empty means fabric-gateway-chart-ext-secret.
secrets.dev.enabledfalseCreates the app Secret from secrets.dev.values, as a Helm hook. Ignored when secrets.app.existingSecret is set. Local testing only.
mysqlPassword.existingSecret""Another Secret to read the MySQL password from, for example one owned by a MySQL chart. Empty means the app Secret. The migration Job doesn’t use this value. Also set migrations.existingSecret and migrations.passwordKey to the same Secret and key.
mysqlPassword.passwordKeymysql-passwordKey in mysqlPassword.existingSecret that holds the password.
syncCA.keyca.crtFile name of the mounted CA certificate.
syncCA.mountPath/etc/fabric/syncWhere the CA certificate is mounted. Keep it consistent with FABRIC_GW_SYNC_SERVER_CA.

For the keys the app Secret holds, see Secrets and keys.

Enrollment

ValueDefaultDescription
attestation.enabledfalseEnrolls with a projected Kubernetes service account token instead of a bootstrap token. Mounts the token and sets the matching environment variables.
attestation.audiencefabric-cpAudience of the projected token. Must equal the Audience of the trust anchor you registered in the console.
attestation.expirationSeconds3600Lifetime of the projected token. The kubelet rotates it. Minimum 600.
attestation.mountPath/var/run/secrets/fabric-cpWhere the token is mounted. The gateway reads <mountPath>/token.

See Connect to the control plane.

Gateway environment

The gateway is configured through environment variables under env.vars. The chart renders them into a ConfigMap. Helm merges maps, so you only need to list the variables you change.

ValueDefaultDescription
FABRIC_GW_MODEdpRuns the process as a data plane. Don’t change it.
FABRIC_GW_PRODUCTION_MODE"true"Fail-closed startup: the data plane refuses to start without an encryption key, and the credential broker and kill switch fail closed. The kill switch also needs FABRIC_GW_ADMIN_KEY_PRIMARY in the app Secret. Set "false" only for throwaway testing.
FABRIC_GW_STRICT_MODENot setSet "true" to require PKCE in the credential broker and HTTPS-only MCP discovery.
FABRIC_GW_HTTP_LISTEN:8080Address the gateway listens on for client traffic. Keep :8080: the Service, container port, and health probes all use port 8080.
FABRIC_GW_CACHE_PATH/data/cacheWhere the gateway keeps its configuration cache and certificate.
FABRIC_GW_SYNC_SERVER_CA/etc/fabric/sync/ca.crtPath to the control plane CA certificate.
FABRIC_GW_SYNC_ENROLLMENT_ENABLED"true"Enrolls with the control plane at startup.
FABRIC_GW_SYNC_CLIENT_CERT/data/cache/leaf.crtWhere the enrolled certificate is written.
FABRIC_GW_SYNC_CLIENT_KEY/data/cache/leaf.keyWhere the private key is written.
FABRIC_GW_SECRETS_TYPEmysqlSecret store. The chart switches it when you set distributed.enabled.
FABRIC_GW_MYSQL_USERfabric_gw_userMySQL user.
FABRIC_GW_MYSQL_DATABASEfabric_gatewayMySQL database.
FABRIC_GW_SSRF_ALLOW_PRIVATE_HOSTS""Comma-separated hosts that the gateway’s own authentication calls (OAuth and OIDC discovery, client registration, token exchange, and JWT Auth key fetches) may reach on private addresses. It doesn’t affect upstreams.
FABRIC_GW_SSRF_BLOCK_PRIVATE_UPSTREAMSNot set (false)Set "true" to refuse upstreams on private addresses (RFC 1918, carrier-grade NAT, and IPv6 unique local). Routes reach them by default.
FABRIC_GW_SSRF_ALLOW_PRIVATE_UPSTREAM_HOSTSNot setComma-separated upstream hosts that stay reachable when FABRIC_GW_SSRF_BLOCK_PRIVATE_UPSTREAMS is on. Exact hostnames or *. wildcards.
FABRIC_GW_METERING_ENABLED"true"Sends usage counts to the control plane over the sync connection. Don’t change it.
FABRIC_MCP_DEBUG_LOGS"1"Writes extra log lines for MCP requests. They record whether a header or token was present, never its value.
LOG_LEVELNot set (info)debug, info, warn, or error.
LOG_FORMATNot set (json)json or text.

The node ID isn’t set, so each pod uses its hostname and enrolls as its own node.

Shared rate limiting

By default, each gateway pod keeps its own rate-limit counters. To share counters across pods, run a Redis and set:

ValueDescription
FABRIC_GW_COORD_REDIS_ENABLED"true" to use a coordination Redis.
FABRIC_GW_COORD_REDIS_ADDRESSRedis host:port.
FABRIC_GW_COORD_REDIS_TLS"true" for a TLS endpoint.
FABRIC_GW_COORD_REDIS_AUTH_REFSet to env://FABRIC_GW_COORD_REDIS_PASSWORD when Redis needs a password, and put the password in the app Secret as FABRIC_GW_COORD_REDIS_PASSWORD.
FABRIC_GW_RATE_LIMIT_COUNTER_STOREredis to keep counters in Redis.
FABRIC_GW_RATE_LIMIT_ON_ERRORWhat to do when Redis is unreachable: local (fall back to per-pod counters) or fail_open.

Environment variables

Every container the chart renders can take your own environment variables, except the OPA sidecar: the gateway, the collector sidecar, the embedder, and the migration Job.

TargetValueFormat
Every container except the OPA sidecarglobal.envA map of KEY: value. Values are passed through literally.
Gateway containerenv.varsA map, rendered into the gateway’s ConfigMap.
Embedderembedder.extraEnvA Kubernetes env list (name and value, or valueFrom).
Migration Jobmigrations.extraEnvA Kubernetes env list.
One sidecar in additionalContainerssidecarEnv.<container-name>A Kubernetes env list, keyed by container name, for example sidecarEnv.otel-collector.

Layers apply in this order, and a later layer replaces an earlier variable of the same name: the chart’s built-in variables and env.vars, then global.env, then extraEnv or sidecarEnv. So global.env overrides env.vars for the gateway. If a gateway value must not be overridden, don’t also set it in global.env.

A value in the app Secret overrides the same name in env.vars, but global.env overrides both, because it’s set directly on the container. Put secret values such as OTEL_EXPORTER_OTLP_HEADERS in the Secret.

global:
env:
HTTP_PROXY: "http://proxy.internal:3128" # every container except the OPA sidecar
embedder:
extraEnv:
- name: HF_HUB_OFFLINE
value: "1"
sidecarEnv:
otel-collector:
- name: MY_EXPORTER_TOKEN
valueFrom:
secretKeyRef: { name: my-secret, key: token }

Service

ValueDefaultDescription
service.enabledtrueRenders the Service. Keep it on: with it off, the chart also drops the gateway’s health probes and both autoscalers.
service.typeClusterIPService type. Use LoadBalancer or NodePort to expose the gateway outside the cluster.
service.port8080The Service port. The chart also uses it as the gateway’s container port, and the gateway listens only on 8080, so keep it at 8080. To serve clients on 80 or 443, use an Ingress or your load balancer’s listener settings.
service.annotations{}Annotations on the Service, for example cloud load balancer settings.

Scale and availability

ValueDefaultDescription
replicaCount2Gateway replicas with the default Deployment, when no autoscaler is on.
distributed.replicaCount3Gateway replicas with the distributed secret store. The autoscalers don’t scale it.
autoscaling.enabledfalseAdds a HorizontalPodAutoscaler. Needs metrics-server.
autoscaling.targetCPUUtilizationPercentage60CPU target for the HorizontalPodAutoscaler. KEDA always uses 60.
autoscaling.targetMemoryUtilizationPercentage75Memory target for the HorizontalPodAutoscaler. KEDA always uses 75.
keda.enabledfalseAdds a KEDA ScaledObject instead. Needs the KEDA operator. Enabling both autoscalers fails the render.
scalingConfig.scalingProperties.minReplicas2Minimum replicas for either autoscaler.
scalingConfig.scalingProperties.maxReplicas2Maximum replicas for either autoscaler. Raise it, or the autoscaler stays at 2.
scalingConfig.triggers[]Extra KEDA triggers. Each uses the keda-cluster-trigger-authentication ClusterTriggerAuthentication, which you create. The CPU and memory triggers are always present.
podDisruptionBudget.enabledtrueAdds a PodDisruptionBudget for the gateway.
podDisruptionBudget.minAvailable1Gateway pods kept available during voluntary disruptions.
container.requests / container.limits300m and 512Mi / 500m and 1024MiGateway container resources.

The gateway’s liveness, readiness, and startup probes are pinned to /healthz on port 8080 (container.probes.*). Don’t reset them to the template defaults, because those paths return 404 and the pod is killed. Each pod also waits 60 seconds in a preStop hook and has a 100-second termination grace period (terminationGracePeriodSeconds), so a rollout or node drain takes about a minute or more per pod.

With an autoscaler on, each helm upgrade sets the gateway back to replicaCount replicas until the autoscaler scales it again. Run upgrades when traffic is low, or set replicaCount close to your usual replica count.

For guidance, see Scale and high availability.

Distributed secret store

These values apply when distributed.enabled is true. The chart then runs the gateway as a StatefulSet, adds a headless Service, and skips the migration Job.

ValueDefaultDescription
distributed.discoverydnsHow pods find each other: dns, or static with distributed.peers.
distributed.writeQuorum / distributed.readQuorum0Quorum sizes. 0 derives a majority.
distributed.persistence.size1GiSize of each pod’s snapshot volume.
distributed.persistence.storageClass""StorageClass for the volumes. Empty means the cluster default.
distributed.podManagementPolicyOrderedReadyHow the StatefulSet starts and stops pods.
distributed.networkPolicy.enabledtrueAdds a NetworkPolicy for the store’s ports.

Service account

ValueDefaultDescription
serviceAccount.createtrueCreates a ServiceAccount for the gateway.
serviceAccount.name""Empty means <release-name>-sa. With attestation, this is the Service account on the trust anchor.
serviceAccount.annotations{}Annotations, for example an AWS IAM role for service accounts.
automountServiceAccountTokennullEmpty mounts the API token only when an IAM role is configured. Set true or false to force it. Attestation doesn’t need it, because it uses its own projected token.

Database migrations

ValueDefaultDescription
migrations.enabledtrueRuns the schema migration Job before every install and upgrade. Skipped automatically with the distributed store.
migrations.existingSecret""Secret with the migration user’s password. Empty means the app Secret.
migrations.passwordKeyFABRIC_GW_MYSQL_PASSKey in that Secret.
migrations.dbUser""MySQL user for migrations. Empty means FABRIC_GW_MYSQL_USER.
migrations.baselineOnMigratetrueAdopts a database that already has the schema.
migrations.baselineVersion"0"Keep at "0", so every migration still applies to an adopted database.
migrations.connectRetries10Connection retries while the database starts.
migrations.imageflyway/flyway:10Migration image.
migrations.backoffLimit2How many times Kubernetes retries a failed migration Pod before the Job fails.
migrations.pullPolicyIfNotPresentImage pull policy for the migration image.
migrations.resources100m and 128Mi requests, 250m and 256Mi limitsResources for the migration container.
migrations.extraEnv[]Extra environment variables for the migration Job.

See Database migrations.

Telemetry

ValueDefaultDescription
otelCollector.enabledtrueRuns the OpenTelemetry Collector sidecar. Set false and set OTEL_EXPORTER_OTLP_ENDPOINT to send OTLP straight to your backend. Without the sidecar, requests don’t appear on the console’s Traces page.
otel.clickhouse.endpointtcp://clickhouse.example.com:9440?secure=trueClickHouse endpoint for the collector.
otel.clickhouse.databasefabric_gatewayClickHouse database.
otel.clickhouse.usernamefabric_gateway_writerClickHouse user. The password comes from FABRIC_GW_CLICKHOUSE_PASSWORD in the app Secret.
env.vars.OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317Where the gateway sends OTLP. The default is the collector sidecar.
env.vars.OTEL_SERVICE_NAMEfabric-gateway-dpService name on exported telemetry.
env.vars.OTEL_RESOURCE_ATTRIBUTESservice.namespace=fabric-gateway,deployment.environment=productionResource attributes on exported telemetry.
env.vars.OTEL_TRACES_SAMPLER_ARG"0.10"Fraction of traces sampled.
env.vars.FABRIC_GW_TRACING_CAPTURE_MESSAGE_CONTENT"false"Adds LLM prompts and replies to traces. Review data-handling rules before you turn it on.
env.vars.FABRIC_GW_TRACING_MAX_PAYLOAD_BYTES"16384"Maximum captured content per field.
metrics.serviceMonitor.enabledfalseAdds a PodMonitor for the collector and a ServiceMonitor for the embedder. Needs the Prometheus Operator.
metrics.serviceMonitor.interval / scrapeTimeout30s / 10sScrape timing for the monitors.
metrics.serviceMonitor.labels{}Labels so your Prometheus Operator selects the monitors.
metrics.annotations.enabledfalseAdds prometheus.io/scrape annotations for annotation-based scrapers.

For backends and overlays, see OpenTelemetry.

Embedder

The embedder powers MCP tool search.

ValueDefaultDescription
embedder.model.idBAAI/bge-small-en-v1.5Model to serve, or a local path.
embedder.image.repositoryghcr.io/huggingface/text-embeddings-inferenceEmbedder image.
embedder.image.tagcpu-1.9Embedder image tag.
embedder.image.digest""Pins the embedder image by digest.
embedder.image.imagePullSecrets""Pull Secret for a mirrored embedder image.
embedder.replicaCount1Embedder replicas.
embedder.resources500m and 1Gi / 2 and 2GiRequests / limits.
embedder.args.dtype / pooling / autoTruncate""Leave empty to let the embedder detect them from the model.
embedder.extraEnv[]Extra environment variables, for example HF_TOKEN.
embedder.persistence.enabledfalseKeeps the model cache on a PersistentVolumeClaim, so restarts don’t download the model again. With more than one replica, also set embedder.persistence.accessModes to ReadWriteMany, or set embedder.persistence.existingClaim. Otherwise the install fails.
embedder.offline.enabledfalseNever contacts huggingface.co. The model must already be in the cache or the image.
embedder.podDisruptionBudget.enabledtruePodDisruptionBudget for the embedder. With one replica, it blocks node drains.
embedder.autoscaling.enabledfalseHorizontalPodAutoscaler for the embedder.
embedder.networkPolicy.enabledfalseAllows only gateway pods to reach the embedder. Needs a NetworkPolicy controller.

For running the embedder offline or with a persistent cache, see Embedder.

Feature toggles

Every toggle below is off by default, except migrations.enabled and otelCollector.enabled. With all of them off, the chart renders a plain Kubernetes install with static replicas and no CRDs.

ToggleDefaultTurns onCluster requirement
migrations.enabledtrueThe schema migration JobA reachable MySQL at install time
otelCollector.enabledtrueThe collector sidecar and its ConfigMapNone
attestation.enabledfalseToken-free enrollment with a projected service account tokenA trust anchor registered in the console
autoscaling.enabledfalseA HorizontalPodAutoscaler for the gatewaymetrics-server
keda.enabledfalseA KEDA ScaledObject for the gatewayThe KEDA operator
opa.enabledfalseAn OPA sidecar on loopback. Required by the access-control, validator, and transformer policy plugins, which fail closed without it. See the warning below.None
distributed.enabledfalseThe distributed secret store: a StatefulSet, a headless Service, one volume per pod, and a NetworkPolicy. Add FABRIC_GW_DISTRIBUTED_GOSSIP_KEY and FABRIC_GW_DISTRIBUTED_AUTH_PASSWORD to the app Secret first, or pods don’t start in production mode.A StorageClass and a NetworkPolicy controller
istio.enabledfalseExcludes the ports in istio.excludeOutboundPorts (default 4317,4318,9090) from Istio’s outbound interception. If your sync address uses a port other than 9090, add it to that list.Istio
reloader.enabledfalseA Stakater Reloader annotation, so the gateway restarts when any Secret or ConfigMap it uses changes, including the app Secret and the CA certificateStakater Reloader
metrics.serviceMonitor.enabledfalseA PodMonitor and a ServiceMonitorThe Prometheus Operator
metrics.annotations.enabledfalseprometheus.io/scrape pod annotationsAn annotation-based scraper
embedder.persistence.enabledfalseA PVC model cache for the embedderA default StorageClass
embedder.autoscaling.enabledfalseA HorizontalPodAutoscaler for the embeddermetrics-server
embedder.networkPolicy.enabledfalseA NetworkPolicy for the embedderA NetworkPolicy controller
embedder.offline.enabledfalseOffline embedderA pre-cached or mirrored model
iam.enabledfalseAn IAM role for the gateway’s ServiceAccount, through CrossplaneCrossplane with the AWS provider. AWS only.
llmEgress.enabledfalseAn LLM egress (Transponder callback) listener on container port 8090, set by llmEgress.port. Configure it with FABRIC_GW_LLM_EGRESS_* variables under env.vars.None

Turning on opa.enabled keeps gateway pods from becoming ready. The OPA sidecar listens only on loopback, so its readiness check fails, and the pods stay at READY 2/3 with no traffic. Don’t turn it on until the chart is fixed. Until then, the access-control, validator, and transformer policy plugins can’t run on this data plane.

With distributed.enabled, the chart’s NetworkPolicy allows only ports 3320 and 3322 into gateway pods. On a cluster that enforces NetworkPolicy, it also blocks client traffic to port 8080. Add a rule for 8080 to your values file:

distributed:
networkPolicy:
extraIngress:
- ports:
- protocol: TCP
port: 8080

Production-hardening defaults

These are on by default. Keep them on.

  • Pod security. Gateway and embedder pods run as non-root with the RuntimeDefault seccomp profile. The gateway and embedder containers drop all Linux capabilities, disallow privilege escalation, and use a read-only root filesystem. The collector sidecar and the schema migration Job don’t set these restrictions, so they don’t meet the Kubernetes restricted Pod Security Standard. Use the baseline level for the data plane’s namespace. Writable state lives only in mounted volumes: /data/cache for the gateway, and /data and /tmp for the embedder.
  • Fail-closed startup. FABRIC_GW_PRODUCTION_MODE is "true", so a data plane without a usable encryption key refuses to start.
  • Pinned images. The gateway image uses an explicit tag, never latest. Set image.digest and embedder.image.digest to pin by digest. The migration image, flyway/flyway:10, uses a tag that moves with each Flyway 10 release. To pin it, set migrations.image to a full version tag or to flyway/flyway@sha256:<digest>.
  • Limited trace data. Tracing samples 10% of traces, and message content capture is off. Raise either only after you review the cost and data-handling impact.
  • Disruption budgets. PodDisruptionBudgets keep at least one gateway pod and one embedder pod available during node drains.

If you build your own gateway image on a base whose user isn’t numeric, the kubelet can’t verify that it runs as non-root and refuses to start it. Set podSecurityContext.runAsUser to the numeric user ID your image runs as. Postman’s image doesn’t need this.

Next steps