Helm Chart

Learn where to find API7 Gateway Helm chart values and how Helm values are rendered into gateway configuration.

The API7 Gateway Helm chart installs API7 Gateway data plane instances on Kubernetes and renders the gateway configuration from chart values. The chart supports configuration for both Kubernetes deployment resources and the gateway runtime configuration generated into config.yaml.

For Kubernetes deployments, Helm values should be treated as the source of truth. Changes made directly to conf/config.yaml inside a running pod, or to the generated ConfigMap, are overwritten by the next Helm upgrade.

Chart Repository

API7 Helm Chart provides Helm-based installation and management of API7 components on Kubernetes.

Add the API7 Helm repository:

helm repo add api7 https://charts.api7.ai
helm repo update

Install API7 Gateway with a values file and an exact chart version:

helm upgrade --install api7-ee-3-gateway api7/gateway \
  -n api7 \
  --create-namespace \
  --version "3.10.15" \
  -f values.yaml

Chart version 3.10.15 has application version 3.10.7 and uses the 3.10.7 gateway image tag by default. The chart and gateway versions are separate values. Pin the chart version in an upgrade so an unrelated configuration change does not also select a newer chart. If API7 Dashboard generated your data plane installation command or values file, keep the generated connection settings, certificates, and token-related environment variables when you add custom values.

Chart Values

Helm chart values define the configuration of a chart. They can come from the chart's default values.yaml file or be overridden during installation or upgrade to customize the deployment.

View Default Values

To view the default values provided by the chart documented on this page, run:

helm show values api7/gateway --version "3.10.15"

This command displays the packaged values.yaml. It does not read values from an installed release. To inspect the values currently associated with a release, use helm get values.

For chart references that match this page, see the values reference for readable field descriptions and values.yaml for the raw default values and nesting:

The ConfigMap template is the chart-side mapping between Helm values and the generated gateway config.yaml. The Pod template adds a checksum of that ConfigMap to the workload's Pod template. A configuration change therefore causes Kubernetes to roll out new gateway Pods.

View Effective Values

To view the values applied to an installed release, including defaults and overrides, run:

helm get values api7-ee-3-gateway -n api7 --all

Update Values

Before changing any value, use helm list -n api7 --filter '^api7-ee-3-gateway$' to confirm the release's installed chart. Save its user-supplied values with helm get values api7-ee-3-gateway -n api7 -o yaml > values.before.yaml. Put only the intended overrides in a separate file, then reuse all existing release values and the same exact chart version:

helm upgrade api7-ee-3-gateway api7/gateway \
  -n api7 \
  --version "3.10.15" \
  --reuse-values \
  -f values.override.yaml \
  --wait \
  --timeout 5m

If the installed chart is not gateway-3.10.15, stop and verify the value paths and templates for that installed version before upgrading. This preserves existing API7 Dashboard connection settings, certificates, Secret references, image settings, and other release values while applying the explicit overrides.

Change GraphQL Request Size

In chart 3.10.15, the graphql.maxSize value renders as graphql.max_size in the generated config.yaml. The value is the maximum GraphQL request size in bytes; its default is 1048576 (1 MiB).

The following example changes the limit to 2 MiB on a release that already uses chart gateway-3.10.15:

export RELEASE="api7-ee-3-gateway"
export NAMESPACE="api7"
export CHART_VERSION="3.10.15"
export GRAPHQL_MAX_SIZE="2097152"

helm list -n "${NAMESPACE}" --filter "^${RELEASE}$"

Verify that the CHART column reports gateway-3.10.15. If it reports another version, stop and check that version's values and templates before changing the release. The commands below deliberately keep the verified chart version.

Back up the release's user-supplied values and record the current gateway image and configuration checksum:

helm get values "${RELEASE}" -n "${NAMESPACE}" -o yaml > values.before.yaml

export POD_SELECTOR="app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/name=gateway"
kubectl get pods -n "${NAMESPACE}" -l "${POD_SELECTOR}" \
  -o custom-columns='NAME:.metadata.name,CHECKSUM:.metadata.annotations.checksum/config,IMAGE:.spec.containers[0].image,IMAGE_ID:.status.containerStatuses[0].imageID'

Check the effective value of apisix.enableCustomizedConfig in the output of helm get values "${RELEASE}" -n "${NAMESPACE}" --all. Use one of the following upgrade commands according to that value.

For the default mode, update the native chart value:

helm upgrade "${RELEASE}" api7/gateway \
  -n "${NAMESPACE}" \
  --version "${CHART_VERSION}" \
  --reuse-values \
  --set "graphql.maxSize=${GRAPHQL_MAX_SIZE}" \
  --wait \
  --timeout 5m

If the existing release already has apisix.enableCustomizedConfig: true, update the equivalent field inside its complete customized configuration:

helm upgrade "${RELEASE}" api7/gateway \
  -n "${NAMESPACE}" \
  --version "${CHART_VERSION}" \
  --reuse-values \
  --set "apisix.customizedConfig.graphql.max_size=${GRAPHQL_MAX_SIZE}" \
  --wait \
  --timeout 5m

Do not enable apisix.enableCustomizedConfig only for this setting. When it is enabled, the chart renders apisix.customizedConfig as the entire config.yaml and ignores the other chart-derived gateway settings. --reuse-values in both commands retains the release's existing connection, certificate, Secret reference, image, and other user-supplied values while changing the selected field.

After the upgrade, confirm that the workload rollout completed and inspect the ConfigMap actually mounted by a new gateway Pod:

export WORKLOAD="$(kubectl get deployment,daemonset -n "${NAMESPACE}" \
  -l "${POD_SELECTOR}" -o name | head -n 1)"
kubectl rollout status "${WORKLOAD}" -n "${NAMESPACE}" --timeout=5m

export POD="$(kubectl get pods -n "${NAMESPACE}" -l "${POD_SELECTOR}" \
  -o jsonpath='{.items[0].metadata.name}')"
export CONFIGMAP="$(kubectl get pod "${POD}" -n "${NAMESPACE}" \
  -o jsonpath='{.spec.volumes[?(@.name=="apisix-config")].configMap.name}')"
kubectl get configmap "${CONFIGMAP}" -n "${NAMESPACE}" \
  -o jsonpath='{.data.config\.yaml}' | sed -n '/^graphql:/,/^[^ ]/p'

kubectl get pods -n "${NAMESPACE}" -l "${POD_SELECTOR}" \
  -o custom-columns='NAME:.metadata.name,CHECKSUM:.metadata.annotations.checksum/config,IMAGE:.spec.containers[0].image,IMAGE_ID:.status.containerStatuses[0].imageID'

The rendered graphql.max_size should be 2097152 and the Pods should be Ready. If the rendered ConfigMap changed, checksum/config should differ from the value recorded before the upgrade; if the release already had this value, the checksum can remain unchanged and no replacement Pod is required. The gateway image reference should remain unchanged. API7 Gateway chart 3.10.15 uses imagePullPolicy: Always by default, so Kubernetes can resolve the same mutable image tag to a different digest during a rollout. Compare IMAGE_ID before and after if preserving the exact image artifact is required. When the checksum changes, the chart causes Kubernetes to create new Pods that mount the new config.yaml; after that rollout completes, you do not need to enter a Pod and run apisix reload.