Helm Chart

Learn where to find Apache APISIX Helm chart values and how Helm values are rendered into gateway configuration.

The Apache APISIX Helm chart installs APISIX on Kubernetes and renders the gateway configuration from chart values. The chart supports configuration for both Kubernetes deployment resources and the APISIX 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

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

Add the APISIX Helm repository:

helm repo add apisix https://apache.github.io/apisix-helm-chart
helm repo update

Install APISIX with a values file and an exact chart version:

helm upgrade --install apisix apisix/apisix \
  -n apisix \
  --create-namespace \
  --version "2.17.0" \
  -f values.yaml

Chart version 2.17.0 has application version 3.18.0 and uses the 3.18.0-ubuntu APISIX image tag by default. The chart and APISIX versions are separate values. Pin the chart version in an upgrade so an unrelated configuration change does not also select a newer chart.

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 apisix/apisix --version "2.17.0"

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 packaged values and templates:

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

View Effective Values

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

helm get values apisix -n apisix --all

Update Values

Before changing any value, use helm list -n apisix --filter '^apisix$' to confirm the release's installed chart. Save its user-supplied values with helm get values apisix -n apisix -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 apisix apisix/apisix \
  -n apisix \
  --version "2.17.0" \
  --reuse-values \
  -f values.override.yaml \
  --wait \
  --timeout 5m

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

Change GraphQL Request Size

In chart 2.17.0, the apisix.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 apisix-2.17.0:

export RELEASE="apisix"
export NAMESPACE="apisix"
export CHART_VERSION="2.17.0"
export GRAPHQL_MAX_SIZE="2097152"

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

Verify that the CHART column reports apisix-2.17.0. 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 APISIX 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=apisix"
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'

Update the native chart value while reusing the release's existing values:

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

Using the exact installed chart version avoids a chart or default-image change. --reuse-values retains the release's existing etcd connection, certificates, Secret references, image, and other user-supplied values while changing the selected field.

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

export WORKLOAD="$(kubectl get deployment -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 APISIX image reference should remain unchanged. Compare IMAGE_ID before and after if your image tag is mutable and 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.