From 1beb8d34c2217e6fe2f1538f4ad25f063f63151c Mon Sep 17 00:00:00 2001
From: Jarvis <jarvis@api7.ai>
Date: Tue, 29 Sep 2026 07:19:25 +0000
Subject: [PATCH 1/5] feat(aisix): render the gateway's startup config from an
 explicit config block

Every gateway setting the chart deploys is now declared in values.yaml
and reaches the gateway as its config file through a ConfigMap, in both
modes. `config:` mirrors the gateway's startup file key for key at the
gateway's own defaults; the chart fills the keys it owns (listen
addresses, listeners, rate-limit backend, the control-plane connection,
the standalone resources file, admin) and rejects them under config:.

Credentials never enter the ConfigMap: the control-plane mTLS bundle is
mounted as files (managed.cp_*_file), the rate-limit Redis URL stays a
secretKeyRef env var, and the new configSecrets block wires the other
credential-bearing keys from Secrets. extraEnvVars is documented as
system-level only; AISIX_* variables there still override the file.

The pod template always carries checksum/config and checksum/secret, so
a config change or a chart-managed Secret change rolls the pods in both
modes.

CI checks config: against api7/aisix config.reference.json at the
chart's appVersion and boots the appVersion image on the rendered file
in both modes.
---
 .github/scripts/aisix-config-boot.sh        |  97 ++++++++++
 .github/scripts/check-aisix-config-drift.py |  99 +++++++++++
 .github/workflows/ci.yaml                   |   8 +
 AGENTS.md                                   |  12 ++
 charts/aisix/README.md                      | 116 ++++++++++--
 charts/aisix/README.md.gotmpl               |  63 +++++--
 charts/aisix/ci/config-values.yaml          |  34 ++++
 charts/aisix/config-policy.yaml             |  41 +++++
 charts/aisix/templates/_helpers.tpl         | 140 +++++++++++++--
 charts/aisix/templates/configmap.yaml       |  17 +-
 charts/aisix/templates/deployment.yaml      | 102 ++++-------
 charts/aisix/templates/secret.yaml          |   2 +-
 charts/aisix/values.yaml                    | 188 +++++++++++++++++++-
 13 files changed, 805 insertions(+), 114 deletions(-)
 create mode 100755 .github/scripts/aisix-config-boot.sh
 create mode 100644 .github/scripts/check-aisix-config-drift.py
 create mode 100644 charts/aisix/ci/config-values.yaml
 create mode 100644 charts/aisix/config-policy.yaml

diff --git a/.github/scripts/aisix-config-boot.sh b/.github/scripts/aisix-config-boot.sh
new file mode 100755
index 0000000..32c5008
--- /dev/null
+++ b/.github/scripts/aisix-config-boot.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Boot the gateway image the chart deploys (its appVersion) on the config file
+# the chart renders, in both modes, with charts/aisix/ci/config-values.yaml
+# setting list-typed keys through `config`.
+#
+# Standalone must come up and answer /livez. Control-plane mode has no control
+# plane to reach here, so it must get past loading the config file and fail
+# only once it acts on the connection. Override the image with AISIX_IMAGE.
+set -euo pipefail
+
+chart=charts/aisix
+app=$(awk '/^appVersion:/ {gsub(/"/, "", $2); print $2}' "$chart/Chart.yaml")
+image=${AISIX_IMAGE:-docker.io/api7/aisix:$app}
+work=$(mktemp -d)
+chmod 755 "$work"
+run_id=$$
+trap 'docker rm -f "aisix-cfgboot-standalone-$run_id" "aisix-cfgboot-managed-$run_id" >/dev/null 2>&1 || true; rm -rf "$work"' EXIT
+
+# extract <template> <data key> <out file> [helm args...]
+extract() {
+  local template=$1 key=$2 out=$3
+  shift 3
+  helm template ci "$chart" "$@" --show-only "templates/$template" \
+    | python3 -c '
+import sys, yaml
+key = sys.argv[1]
+for doc in yaml.safe_load_all(sys.stdin):
+    if doc:
+        data = doc.get("data") or doc.get("stringData") or {}
+        if key in data:
+            sys.stdout.write(data[key])
+' "$key" >"$out"
+  test -s "$out"
+  chmod 644 "$out"
+}
+
+echo "== image $image"
+docker pull -q "$image" >/dev/null
+
+echo "== standalone"
+mkdir -p "$work/standalone"
+set_standalone=(-f "$chart/ci/standalone-values.yaml" -f "$chart/ci/config-values.yaml")
+extract configmap.yaml config.yaml "$work/standalone/config.yaml" "${set_standalone[@]}"
+extract secret.yaml resources.yaml "$work/standalone/resources.yaml" "${set_standalone[@]}"
+cat "$work/standalone/config.yaml"
+name=aisix-cfgboot-standalone-$run_id
+docker run -d --name "$name" -p 127.0.0.1::3000 \
+  -e AISIX_CONFIG_PATH=/etc/aisix/chart/config.yaml \
+  -e OPENAI_API_KEY=sk-ci-placeholder -e CALLER_API_KEY=ci-caller-placeholder \
+  -v "$work/standalone/config.yaml:/etc/aisix/chart/config.yaml:ro" \
+  -v "$work/standalone/resources.yaml:/etc/aisix/resources/resources.yaml:ro" \
+  "$image" >/dev/null
+port=$(docker port "$name" 3000/tcp | head -n1 | sed 's/.*://')
+ok=
+for _ in $(seq 1 60); do
+  if curl -fsS "http://127.0.0.1:$port/livez" >/dev/null 2>&1; then ok=1; break; fi
+  if [ "$(docker inspect -f '{{.State.Running}}' "$name")" != true ]; then break; fi
+  sleep 1
+done
+if [ -z "$ok" ]; then
+  echo "standalone gateway did not come up on the rendered config:"
+  docker logs "$name" 2>&1 | tail -n 50
+  exit 1
+fi
+echo "standalone: /livez answered"
+
+echo "== control-plane mode"
+mkdir -p "$work/managed/cp-mtls"
+extract configmap.yaml config.yaml "$work/managed/config.yaml" -f "$chart/ci/config-values.yaml"
+cat "$work/managed/config.yaml"
+openssl req -x509 -newkey rsa:2048 -nodes -days 1 -subj "/CN=aisix-ci" \
+  -keyout "$work/managed/cp-mtls/key.pem" -out "$work/managed/cp-mtls/cert.pem" 2>/dev/null
+cp "$work/managed/cp-mtls/cert.pem" "$work/managed/cp-mtls/ca.pem"
+chmod 755 "$work/managed/cp-mtls"
+chmod 644 "$work/managed/cp-mtls/"*.pem
+name=aisix-cfgboot-managed-$run_id
+docker run -d --name "$name" \
+  -e AISIX_CONFIG_PATH=/etc/aisix/chart/config.yaml \
+  -v "$work/managed/config.yaml:/etc/aisix/chart/config.yaml:ro" \
+  -v "$work/managed/cp-mtls:/etc/aisix/cp-mtls:ro" \
+  "$image" >/dev/null
+for _ in $(seq 1 30); do
+  [ "$(docker inspect -f '{{.State.Running}}' "$name")" = true ] || break
+  sleep 1
+done
+logs=$(docker logs "$name" 2>&1)
+echo "$logs" | tail -n 20
+# `level=debug` is config-values.yaml's log_level: the file was read and applied.
+if echo "$logs" | grep -q "config load failed"; then
+  echo "control-plane mode: the rendered config file did not load"
+  exit 1
+fi
+if ! echo "$logs" | grep -q "tracing initialised service=aisix level=debug"; then
+  echo "control-plane mode: the gateway never got past loading its config file"
+  exit 1
+fi
+echo "control-plane mode: config file loaded; the gateway stopped at the control-plane connection"
diff --git a/.github/scripts/check-aisix-config-drift.py b/.github/scripts/check-aisix-config-drift.py
new file mode 100644
index 0000000..344d729
--- /dev/null
+++ b/.github/scripts/check-aisix-config-drift.py
@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Fail when charts/aisix's `config:` block drifts from the gateway.
+
+The gateway publishes config.reference.json — every startup-config key with
+its default — at the root of api7/aisix. This compares it, at the tag of the
+chart's appVersion, with the chart's `config:` block: the same keys, with the
+same defaults, except the keys charts/aisix/config-policy.yaml names as set by
+the chart or held in Secrets.
+
+A release that predates config.reference.json has no tag copy; the check then
+falls back to api7/aisix main and says so. CONFIG_REFERENCE_FILE points the
+check at a local copy instead, for testing a gateway change before it merges.
+"""
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+import yaml
+
+CHART = "charts/aisix"
+RAW = "https://raw.githubusercontent.com/api7/aisix/{ref}/config.reference.json"
+
+
+def fetch(ref):
+    try:
+        with urllib.request.urlopen(RAW.format(ref=ref), timeout=30) as resp:
+            return json.load(resp)
+    except urllib.error.HTTPError as err:
+        if err.code == 404:
+            return None
+        raise
+
+
+def flatten(node, prefix=""):
+    out = {}
+    if isinstance(node, dict) and node:
+        for key, value in node.items():
+            out.update(flatten(value, f"{prefix}{key}."))
+    else:
+        out[prefix[:-1]] = node
+    return out
+
+
+def excluded(path, prefixes):
+    return any(path == p or path.startswith(p + ".") for p in prefixes)
+
+
+def main():
+    with open(f"{CHART}/Chart.yaml") as f:
+        app_version = yaml.safe_load(f)["appVersion"]
+    with open(f"{CHART}/values.yaml") as f:
+        chart_config = yaml.safe_load(f)["config"]
+    with open(f"{CHART}/config-policy.yaml") as f:
+        policy = yaml.safe_load(f)
+
+    ref = f"v{app_version}"
+    local = os.environ.get("CONFIG_REFERENCE_FILE")
+    if local:
+        ref = local
+        with open(local) as f:
+            reference = json.load(f)
+    else:
+        reference = fetch(ref)
+    if reference is None:
+        print(f"note: api7/aisix {ref} has no config.reference.json; comparing against main")
+        ref = "main"
+        reference = fetch(ref)
+        if reference is None:
+            sys.exit("api7/aisix main has no config.reference.json")
+
+    skip = list(policy["owned"]) + list(policy["secrets"])
+    want = {k: v for k, v in flatten(reference).items() if not excluded(k, skip)}
+    have = flatten(chart_config)
+
+    problems = []
+    for path in sorted(want.keys() - have.keys()):
+        problems.append(f"missing from config: {path} (gateway default {json.dumps(want[path])})")
+    for path in sorted(have.keys() - want.keys()):
+        problems.append(f"not a gateway setting at {ref}: {path}")
+    for path in sorted(want.keys() & have.keys()):
+        if want[path] != have[path]:
+            problems.append(
+                f"default differs: {path} is {json.dumps(have[path])} in values.yaml, "
+                f"{json.dumps(want[path])} in the gateway"
+            )
+
+    if problems:
+        print(f"charts/aisix config: drifted from api7/aisix {ref} config.reference.json:")
+        for line in problems:
+            print(f"  {line}")
+        print("Mirror the gateway in values.yaml `config:`, or name the key in config-policy.yaml.")
+        sys.exit(1)
+    print(f"charts/aisix config: matches api7/aisix {ref} ({len(want)} keys)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 5f3e2cb..46792a6 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -41,6 +41,14 @@ jobs:
                   --charts charts/developer-portal-fe \
                   --charts charts/ngxdig'
 
+      - name: Check aisix chart config against the gateway
+        run: |
+          python3 -c 'import yaml' 2>/dev/null || sudo apt-get install -y python3-yaml
+          python3 .github/scripts/check-aisix-config-drift.py
+
+      - name: Boot the aisix gateway on the chart-rendered config
+        run: bash .github/scripts/aisix-config-boot.sh
+
       - name: Verify Chart.lock files
         run: |
           docker run --rm --interactive --network host \
diff --git a/AGENTS.md b/AGENTS.md
index d43c061..445617b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,6 +76,18 @@ The gateway chart's `values.yaml`/configmap mirror the gateway's `conf/config-de
 
 When adding values, keep defaults identical to `config-default.yaml` so a default render changes nothing. To verify a rendered config is valid, extract `config.yaml` from the rendered configmap and run it through the real image: `docker run --rm --entrypoint sh -v $PWD/config.yaml:/usr/local/apisix/conf/config.yaml api7/api7-ee-3-gateway:<ver> -c 'apisix init'` — the config schema is validated at init.
 
+## aisix chart: application settings are explicit values rendered to a ConfigMap
+
+Every application setting `charts/aisix` deploys is declared explicitly in `values.yaml` and reaches the gateway as its config file through a ConfigMap. `extraEnvVars` is for system-level environment (`TZ`) and for variables a standalone resources file references — never the documented way to set a gateway setting, even though an `AISIX_*` variable there still overrides the file.
+
+How the chart implements it:
+
+- `config:` mirrors the gateway's startup file one-to-one — the same section and key names as `config.example.yaml` / `crates/aisix-core/src/config.rs` in `api7/aisix` — with every key listed at the gateway's own default (`null` = omitted = gateway default). No chart-specific renaming. `aisix.configFile` in `_helpers.tpl` renders it into `templates/configmap.yaml` in both modes, fills the chart-owned keys for the mode, and drops nulls. The pod template carries `checksum/config` and `checksum/secret`, so a change rolls the pods.
+- `config-policy.yaml` is the single list of what `config:` does not carry: `owned` keys the chart sets from its other values (listen addresses, `listeners`, `rateLimit`, `controlPlane`, `standalone`, `admin`, most of `etcd`), and `secrets` — credential-bearing keys, set only through `configSecrets` and wired as `secretKeyRef` env. The render fails when `config:` names either kind. Credentials never go into the ConfigMap: where the gateway has a `*_file` key (the control-plane mTLS bundle) the Secret is mounted as a file, otherwise it is a chart-managed `secretKeyRef` env var.
+- `.github/scripts/check-aisix-config-drift.py` compares `config:` with `config.reference.json` from `api7/aisix` at `v<appVersion>` (falling back to `main` for a tag that predates the file), minus `config-policy.yaml`. So a new gateway key, a changed default, or a new chart-owned/secret key is a `values.yaml` or `config-policy.yaml` edit, made with the chart bump that moves `appVersion` to the release that has it — not earlier, since the chart only runs its own `appVersion` image and an older gateway rejects unknown keys.
+- `.github/scripts/aisix-config-boot.sh` boots the `appVersion` image on the rendered file in both modes with `ci/config-values.yaml`; run it locally after changing `config:` or `aisix.configFile`.
+- Values keys are a compatibility surface for `helm upgrade` from released charts, `--reuse-values` included — and `--reuse-values` replaces the new chart's defaults with the old release's values, so a template must treat a new values key as possibly absent (`| default dict`).
+
 ## developer-portal-fe chart: config is a pass-through
 
 `config.yaml` is rendered from `developerPortal.config`, which carries the application's whole config schema (owned by `api7/api7ee-developer-portal`, `apps/site/src/lib/config/schema.ts`). **Do not hoist schema fields into their own `.Values` keys** — a dedicated key plus template plumbing per field mirrors that schema, drifts on every application release, and leaves two ways to set one field. Only the connection settings the chart itself owns are templated, and they are merged over the block, so a user cannot replace the `${PORTAL_TOKEN}` / `${DB_URL}` / `${AUTH_SECRET}` placeholders with literal credentials — those placeholders stay in the ConfigMap and resolve from Secret-backed env vars at startup.
diff --git a/charts/aisix/README.md b/charts/aisix/README.md
index 920b50c..9bce3f9 100644
--- a/charts/aisix/README.md
+++ b/charts/aisix/README.md
@@ -186,9 +186,7 @@ kubectl rollout restart deploy/<release>-aisix -n <namespace>
 Standalone mode has no control plane, so there is no console, no usage or budget
 reporting, and no per-environment configuration distribution. The admin API is
 left unbound as well: it is read-only against a file source, and binding it would
-require admin keys the chart does not manage. Turn it on with
-`extraEnvVars` — `AISIX_ADMIN__ENABLED`, `AISIX_ADMIN__ADDR` and
-`AISIX_ADMIN__ADMIN_KEYS` — if you want it.
+require admin keys the chart does not manage.
 
 ## Termination and draining
 
@@ -413,17 +411,62 @@ topologySpreadConstraints:
 
 ### Set any other gateway configuration
 
-Every field of the gateway's configuration file is reachable as an environment
-variable named `AISIX_<SECTION>__<FIELD>`:
+The gateway reads its settings from a configuration file the chart renders into
+a ConfigMap, in both modes. `config` in `values.yaml` mirrors that file key for
+key — the same section and key names as the gateway's own `config.example.yaml`
+— and lists every setting with the gateway's default, so change only what you
+need:
 
 ```yaml
-extraEnvVars:
-  - name: AISIX_OBSERVABILITY__LOG_LEVEL
-    value: debug
-  - name: AISIX_CACHE__BACKEND
-    value: redis
+config:
+  observability:
+    log_level: debug
+  upstream:
+    pool_idle_timeout_secs: 15
+  proxy:
+    real_ip:
+      trusted_proxies: ["10.0.0.0/8"]
+      recursive: true
 ```
 
+A `null` leaves the key to the gateway's default. A change rolls the pods on
+`helm upgrade`.
+
+A few keys are set by the chart from its other values and are rejected under
+`config` with a message naming the value to use instead: the proxy and metrics
+addresses (`containerPorts`), `proxy.listeners` (`listeners`),
+`ratelimit.backend` and the rate-limit Redis URL (`rateLimit`), the
+control-plane connection (`controlPlane`), and the standalone resources file
+(`standalone`). The list is in the chart's `config-policy.yaml`.
+
+Settings that hold a credential never go into the ConfigMap. Put the value in a
+Secret and name it under `configSecrets`, keyed by the configuration path; the
+chart hands it to the gateway as an environment variable that overrides the
+file:
+
+```yaml
+config:
+  cache:
+    backend: redis
+    redis:
+      mode: single
+configSecrets:
+  cache.redis.url:
+    secretName: aisix-cache-redis
+    key: url
+  cache.redis.password:
+    secretName: aisix-cache-redis
+    key: password
+```
+
+`configSecrets` accepts `cache.redis.url`, `cache.redis.username`,
+`cache.redis.password`, `ratelimit.redis.username` and
+`ratelimit.redis.password`.
+
+`extraEnvVars` is for system-level environment variables such as `TZ`, and for
+the variables a standalone resources file references. An `AISIX_*` variable set
+there still overrides the file, as it always has.
+
 ## Parameters
 
 ## Values
@@ -438,6 +481,57 @@ extraEnvVars:
 | autoscaling.minReplicas | int | `2` | Lower replica bound |
 | autoscaling.targetCPUUtilizationPercentage | int | `70` | Target average CPU utilization, in percent of the CPU request. Set to null to drop the CPU metric |
 | autoscaling.targetMemoryUtilizationPercentage | string | `nil` | Target average memory utilization, in percent of the memory request. Null by default: gateway memory tracks in-flight streams more than load |
+| config.bedrock_endpoint_url | string | `nil` | Deployment-wide AWS Bedrock endpoint override for bedrock guardrails, e.g. a LocalStack URL. Null uses the AWS SDK default |
+| config.cache.backend | string | `"memory"` | Legacy cache backend switch, `memory` or `redis`. `redis` requires `cache.redis`. Which cache serves a request is chosen per cache policy |
+| config.cache.redis | object | `nil` | Shared Redis for the response cache, e.g. `{mode: single}`; the redis cache is built only when this is set. Keys: `mode` (single, cluster, sentinel), `nodes`, `sentinels`, `master_name`, `database`, `tls`, `timeout_secs`. `url`, `username` and `password` go through `configSecrets` |
+| config.downstream.idle_timeout_secs | int | `0` | Seconds an idle client connection is held. 0 never closes it |
+| config.downstream.sse_keepalive_interval_secs | int | `15` | Seconds between SSE keepalive comments on a stalled stream |
+| config.etcd.dial_timeout_ms | int | `5000` | Bound on one dial to the control plane's etcd, in milliseconds. 0 means unbounded |
+| config.etcd.request_timeout_ms | int | `nil` | Bound on one etcd request, in milliseconds. Null means unbounded |
+| config.managed.cp_ca_cert_file | string | `nil` | Extra CA bundle trusted for the control-plane connection, when it serves a private-CA certificate. Mount the file through `extraVolumes` |
+| config.managed.dp_id_file | string | `"/var/lib/aisix/dp_id"` | File the gateway id is persisted in |
+| config.managed.mtls_dir | string | `"/var/lib/aisix/mtls"` | Directory the materialised mTLS bundle is written to |
+| config.managed.snapshot_cache_enabled | bool | `false` | Persist a configuration snapshot for recovery while etcd is unreachable. The snapshot holds unencrypted credentials |
+| config.managed.snapshot_cache_path | string | `nil` | Snapshot location. Null uses `/var/lib/aisix/config_cache.json` |
+| config.observability.access_log | bool | `true` | Write an access-log line per request |
+| config.observability.debug.addr | string | `"127.0.0.1:9091"` | Diagnostics listener address. Loopback keeps it off the network |
+| config.observability.debug.enabled | bool | `true` | Serve the unauthenticated heap-profile endpoint (`/debug/pprof/heap`) |
+| config.observability.heap_profiling.auto_dump.dir | string | `"/var/lib/aisix/heap"` | Directory the profiles are written to |
+| config.observability.heap_profiling.auto_dump.enabled | bool | `true` | Write a heap profile as resident memory nears the memory limit |
+| config.observability.heap_profiling.auto_dump.keep | int | `5` | Newest profiles kept |
+| config.observability.heap_profiling.auto_dump.thresholds | list | `[0.8,0.9]` | Fractions of the memory limit that each trigger one profile |
+| config.observability.log_level | string | `"info"` | Log level: trace, debug, info, warn or error |
+| config.observability.metrics.buckets | object | `{"a2a_ttfb":null,"guardrail_latency":null,"request_e2e_latency":null,"request_ttft":null}` | Per-metric histogram bucket edges in seconds. Null keeps that metric's default buckets |
+| config.observability.metrics.client_type_rules | list | `[]` | User-Agent to `client_type` mapping rules, first match wins, e.g. `[{pattern: "^py-billing-batcher/", client: billing-batcher}]` |
+| config.observability.metrics.labels | object | `{}` | Complete optional label list per metric, e.g. `{aisix_request_ttft_seconds: [model, provider]}`. Omitted metrics keep their default labels |
+| config.observability.metrics.prometheus.enabled | bool | `true` | Serve Prometheus metrics on the metrics listener (`containerPorts.metrics`) |
+| config.observability.metrics.prometheus.path | string | `"/metrics"` | Metrics path |
+| config.observability.service_name | string | `"aisix"` | Service name reported in telemetry |
+| config.proxy.real_ip.header | string | `"x-forwarded-for"` | Header carrying the client IP |
+| config.proxy.real_ip.recursive | bool | `false` | Walk the header right to left past every trusted proxy |
+| config.proxy.real_ip.trusted_proxies | list | `[]` | CIDRs (or bare IPs) of proxies trusted to set the client-IP header |
+| config.proxy.request_body_limit_bytes | int | `0` | Request-body size cap in bytes. 0 means no cap |
+| config.proxy.request_id.accept_headers | list | `["x-aisix-request-id"]` | Headers a caller may supply its own request id in. Add `x-request-id` only when no proxy in front stamps it |
+| config.proxy.thread_per_core | bool | `nil` | Thread-per-core serving topology. Null uses the gateway default (on for Linux) |
+| config.proxy.url_rewrites | list | `[]` | Entry-level URL rewrite rules, first match wins, e.g. `[{name: per-server-mcp, match: "^/mcp-servers/([^/]+)/mcp$", rewrite: "/mcp/$1"}]` |
+| config.proxy.workers | int | `nil` | Worker count. Null uses the gateway default |
+| config.ratelimit.concurrency_ttl_secs | int | `300` | Seconds a concurrency-limit slot is held at most |
+| config.ratelimit.redis | object | `nil` | Extra settings for the shared rate-limit Redis selected by `rateLimit.backend: redis`, e.g. `{timeout_secs: 2}` or `{mode: cluster, nodes: [...]}`. Same keys as `cache.redis`; the URL comes from `rateLimit.redis`, `username` and `password` go through `configSecrets` |
+| config.shutdown.min_drain_secs | int | `30` | Seconds the gateway keeps accepting after SIGTERM while `/readyz` reports 503. `terminationGracePeriodSeconds` must cover it |
+| config.upstream.connect_timeout_ms | int | `5000` | Connect timeout in milliseconds |
+| config.upstream.pool_idle_timeout_secs | int | `30` | Seconds an idle pooled connection is kept. Lower it when a load balancer or NAT between the gateway and the provider closes idle connections sooner |
+| config.upstream.pool_max_idle_per_host | int | `nil` | Idle pooled connections kept per host. Null means unbounded |
+| config.upstream.retries | int | `2` | Retry budget every dispatch starts from |
+| config.upstream.stream_timeout_ms | int | `0` | Streaming idle timeout in milliseconds. 0 means none |
+| config.upstream.tcp_keepalive_interval_secs | int | `30` | TCP keepalive probe interval in seconds |
+| config.upstream.tcp_keepalive_retries | int | `5` | TCP keepalive probes before the connection is dropped |
+| config.upstream.tcp_keepalive_secs | int | `60` | TCP keepalive idle time in seconds |
+| config.upstream.timeout_ms | int | `6000000` | Request timeout for calls to LLM providers, in milliseconds |
+| config.upstream.tls.ca_file | string | `nil` | Extra CA bundle, added to the platform trust store, for every upstream TLS handshake. Mount the file through `extraVolumes` |
+| config.upstream.tls.client_cert_file | string | `nil` | Client certificate for mutual TLS to upstreams |
+| config.upstream.tls.client_key_file | string | `nil` | Client key for mutual TLS to upstreams |
+| config.upstream.tls.verify | bool | `true` | Verify upstream certificates. false accepts any certificate — test use only |
+| configSecrets | object | `{}` | Configuration keys that hold a credential, each read from a Secret you supply and handed to the gateway as an environment variable (which overrides the config file), never written to the ConfigMap. Keyed by the configuration path: `cache.redis.url`, `cache.redis.username`, `cache.redis.password`, `ratelimit.redis.username` or `ratelimit.redis.password`. For example `{cache.redis.password: {secretName: redis-auth, key: password}}` |
 | containerPorts.metrics | int | `9090` | Port the Prometheus metrics listener binds inside the container |
 | containerPorts.proxy | int | `3000` | Port the proxy listener binds inside the container. Nothing binds it when `listeners` is set — that list then carries every proxy port, and the gateway keeps requiring this address only to ignore it. The image carries the `CAP_NET_BIND_SERVICE` file capability, so a privileged port works without running as root — see `securityContext` below |
 | controlPlane.baseURL | string | `""` | Data-plane manager mTLS endpoint the gateway connects out to, e.g. `https://dpm.example.com:7944`. Required. |
@@ -451,7 +545,7 @@ extraEnvVars:
 | controlPlane.enabled | bool | `true` | Read configuration from an AISIX control plane. Set to false to run standalone, from the `resources.yaml` file configured under `standalone` |
 | controlPlane.etcdEndpoint | string | `""` | Control-plane etcd endpoint as bare `host:port`. Leave empty unless the control plane publishes an etcd endpoint distinct from `baseURL` |
 | controlPlane.heartbeatIntervalSeconds | int | `15` | Heartbeat interval in seconds. The control plane marks a gateway connected on its first heartbeat. Clamped to [5, 300] by the gateway |
-| extraEnvVars | list | `[]` | Extra environment variables for the gateway container. Every gateway configuration field is reachable as `AISIX_<SECTION>__<FIELD>` |
+| extraEnvVars | list | `[]` | Extra environment variables for the gateway container: system-level environment variables (such as `TZ`) and variables referenced by the resources file. Gateway settings belong in `config` |
 | extraVolumeMounts | list | `[]` | Extra volume mounts for the gateway container |
 | extraVolumes | list | `[]` | Extra volumes for the gateway pod |
 | fullnameOverride | string | `""` | Override the fully qualified resource name prefix |
diff --git a/charts/aisix/README.md.gotmpl b/charts/aisix/README.md.gotmpl
index 89c4ef9..e62dce7 100644
--- a/charts/aisix/README.md.gotmpl
+++ b/charts/aisix/README.md.gotmpl
@@ -180,9 +180,7 @@ kubectl rollout restart deploy/<release>-aisix -n <namespace>
 Standalone mode has no control plane, so there is no console, no usage or budget
 reporting, and no per-environment configuration distribution. The admin API is
 left unbound as well: it is read-only against a file source, and binding it would
-require admin keys the chart does not manage. Turn it on with
-`extraEnvVars` — `AISIX_ADMIN__ENABLED`, `AISIX_ADMIN__ADDR` and
-`AISIX_ADMIN__ADMIN_KEYS` — if you want it.
+require admin keys the chart does not manage.
 
 ## Termination and draining
 
@@ -407,17 +405,62 @@ topologySpreadConstraints:
 
 ### Set any other gateway configuration
 
-Every field of the gateway's configuration file is reachable as an environment
-variable named `AISIX_<SECTION>__<FIELD>`:
+The gateway reads its settings from a configuration file the chart renders into
+a ConfigMap, in both modes. `config` in `values.yaml` mirrors that file key for
+key — the same section and key names as the gateway's own `config.example.yaml`
+— and lists every setting with the gateway's default, so change only what you
+need:
 
 ```yaml
-extraEnvVars:
-  - name: AISIX_OBSERVABILITY__LOG_LEVEL
-    value: debug
-  - name: AISIX_CACHE__BACKEND
-    value: redis
+config:
+  observability:
+    log_level: debug
+  upstream:
+    pool_idle_timeout_secs: 15
+  proxy:
+    real_ip:
+      trusted_proxies: ["10.0.0.0/8"]
+      recursive: true
 ```
 
+A `null` leaves the key to the gateway's default. A change rolls the pods on
+`helm upgrade`.
+
+A few keys are set by the chart from its other values and are rejected under
+`config` with a message naming the value to use instead: the proxy and metrics
+addresses (`containerPorts`), `proxy.listeners` (`listeners`),
+`ratelimit.backend` and the rate-limit Redis URL (`rateLimit`), the
+control-plane connection (`controlPlane`), and the standalone resources file
+(`standalone`). The list is in the chart's `config-policy.yaml`.
+
+Settings that hold a credential never go into the ConfigMap. Put the value in a
+Secret and name it under `configSecrets`, keyed by the configuration path; the
+chart hands it to the gateway as an environment variable that overrides the
+file:
+
+```yaml
+config:
+  cache:
+    backend: redis
+    redis:
+      mode: single
+configSecrets:
+  cache.redis.url:
+    secretName: aisix-cache-redis
+    key: url
+  cache.redis.password:
+    secretName: aisix-cache-redis
+    key: password
+```
+
+`configSecrets` accepts `cache.redis.url`, `cache.redis.username`,
+`cache.redis.password`, `ratelimit.redis.username` and
+`ratelimit.redis.password`.
+
+`extraEnvVars` is for system-level environment variables such as `TZ`, and for
+the variables a standalone resources file references. An `AISIX_*` variable set
+there still overrides the file, as it always has.
+
 ## Parameters
 
 {{ template "chart.valuesSection" . }}
diff --git a/charts/aisix/ci/config-values.yaml b/charts/aisix/ci/config-values.yaml
new file mode 100644
index 0000000..41c620c
--- /dev/null
+++ b/charts/aisix/ci/config-values.yaml
@@ -0,0 +1,34 @@
+# Values that set gateway configuration through `config`, including
+# list-typed keys, so CI proves the rendered file loads. `ct lint` renders it
+# in control-plane mode with the placeholders below; the config-boot check in
+# ci.yaml renders it in both modes and boots the appVersion image on the file.
+controlPlane:
+  baseURL: "https://dp-manager.example.com:7944"
+  certificate:
+    existingSecret: "aisix-gateway-certificate"
+
+config:
+  observability:
+    log_level: debug
+    metrics:
+      labels:
+        aisix_request_ttft_seconds: [model, provider]
+      buckets:
+        request_ttft: [0.1, 0.5, 1, 5, 30, 300]
+    heap_profiling:
+      auto_dump:
+        thresholds: [0.7, 0.95]
+  proxy:
+    real_ip:
+      trusted_proxies: ["10.0.0.0/8", "127.0.0.1/32"]
+      recursive: true
+    request_id:
+      accept_headers: [x-aisix-request-id, x-request-id]
+    url_rewrites:
+      - name: per-server-mcp-compat
+        match: "^/mcp-servers/([^/]+)/mcp$"
+        rewrite: "/mcp/$1"
+  upstream:
+    pool_idle_timeout_secs: 15
+  etcd:
+    request_timeout_ms: 10000
diff --git a/charts/aisix/config-policy.yaml b/charts/aisix/config-policy.yaml
new file mode 100644
index 0000000..6e88561
--- /dev/null
+++ b/charts/aisix/config-policy.yaml
@@ -0,0 +1,41 @@
+# Which gateway startup-config keys the chart does NOT take from `config:`.
+# Read by templates/_helpers.tpl (render-time validation) and by
+# scripts/check-aisix-config-drift.py (CI drift check), so the two cannot
+# disagree. Keys are dotted configuration paths.
+
+# Set by the chart from its own values. Writing one under `config:` fails the
+# render with this message.
+owned:
+  resources_file: "set by the chart in standalone mode: supply the file through standalone.resources, standalone.existingSecret or standalone.existingConfigMap"
+  admin: "the admin listener is not deployed by this chart"
+  etcd.endpoints: "set by the chart from the control-plane connection"
+  etcd.prefix: "set by the chart from the control-plane connection"
+  etcd.env_id: "not configurable through this chart"
+  etcd.user: "not configurable through this chart"
+  etcd.password_env: "not configurable through this chart"
+  etcd.tls: "not configurable through this chart"
+  proxy.addr: "use containerPorts.proxy"
+  proxy.listeners: "use listeners"
+  proxy.tls: "use listeners with a tls.secretName"
+  observability.metrics.prometheus.addr: "use containerPorts.metrics"
+  ratelimit.backend: "use rateLimit.backend"
+  ratelimit.redis.url: "use rateLimit.redis.url or rateLimit.redis.existingSecret"
+  managed.enabled: "use controlPlane.enabled"
+  managed.cp_base_url: "use controlPlane.baseURL"
+  managed.cp_etcd_endpoint: "use controlPlane.etcdEndpoint"
+  managed.heartbeat_interval_secs: "use controlPlane.heartbeatIntervalSeconds"
+  managed.cp_cert_pem: "use controlPlane.certificate"
+  managed.cp_key_pem: "use controlPlane.certificate"
+  managed.cp_ca_pem: "use controlPlane.certificate"
+  managed.cp_cert_file: "use controlPlane.certificate"
+  managed.cp_key_file: "use controlPlane.certificate"
+  managed.cp_ca_file: "use controlPlane.certificate"
+
+# Hold a credential. Set through `configSecrets` only; writing one under
+# `config:` fails the render.
+secrets:
+  - cache.redis.url
+  - cache.redis.username
+  - cache.redis.password
+  - ratelimit.redis.username
+  - ratelimit.redis.password
diff --git a/charts/aisix/templates/_helpers.tpl b/charts/aisix/templates/_helpers.tpl
index cfd1bce..8e0185e 100644
--- a/charts/aisix/templates/_helpers.tpl
+++ b/charts/aisix/templates/_helpers.tpl
@@ -80,13 +80,14 @@ Name of the Secret holding the gateway certificate bundle.
 {{- end }}
 
 {{/*
-Standalone mode: the directory the startup config is mounted in, the file the
-gateway reads from it, and the resources file it points at. Both live under
-their own directory so neither mount shadows the image's own
-/etc/aisix/config.managed.yaml.
+The directory the chart-rendered startup config is mounted in and the file the
+gateway reads from it; the standalone resources file; and the control-plane
+mTLS bundle. Each lives under its own directory so no mount shadows the image's
+own /etc/aisix/config.managed.yaml.
 */}}
-{{- define "aisix.standaloneConfigDir" -}}/etc/aisix/standalone{{- end }}
-{{- define "aisix.standaloneConfigPath" -}}{{ include "aisix.standaloneConfigDir" . }}/config.yaml{{- end }}
+{{- define "aisix.configDir" -}}/etc/aisix/chart{{- end }}
+{{- define "aisix.configPath" -}}{{ include "aisix.configDir" . }}/config.yaml{{- end }}
+{{- define "aisix.cpCertDir" -}}/etc/aisix/cp-mtls{{- end }}
 {{- define "aisix.standaloneResourcesDir" -}}/etc/aisix/resources{{- end }}
 {{- define "aisix.standaloneResourcesPath" -}}{{ include "aisix.standaloneResourcesDir" . }}/resources.yaml{{- end }}
 
@@ -137,10 +138,9 @@ the built-in "proxy" port.
 "aisix.proxyListenerTLS" is non-empty when that first listener terminates TLS,
 so the probes know to speak HTTPS to it.
 
-"aisix.proxyListenersJson" builds the AISIX_PROXY__LISTENERS value. The gateway
-takes the whole list as one JSON document — indexed environment variables are
-not a form it accepts — and reads TLS material from files, so each TLS listener
-points at the directory its Secret is mounted in.
+"aisix.proxyListenersJson" builds the `proxy.listeners` list of the rendered
+config file, as JSON. The gateway reads TLS material from files, so each TLS
+listener points at the directory its Secret is mounted in.
 */}}
 {{- define "aisix.proxyPortName" -}}
 {{- if .Values.listeners }}{{ (first .Values.listeners).name }}{{ else }}proxy{{ end }}
@@ -169,6 +169,102 @@ points at the directory its Secret is mounted in.
 {{- toJson $listeners }}
 {{- end }}
 
+{{/*
+"aisix.configPathSet" prints "true" when the dotted path .path is set to a
+non-null value in the map .cfg.
+*/}}
+{{- define "aisix.configPathSet" -}}
+{{- $cur := .cfg }}
+{{- $found := true }}
+{{- range (splitList "." .path) }}
+{{- if and $found (kindIs "map" $cur) (hasKey $cur .) }}
+{{- $cur = get $cur . }}
+{{- else }}
+{{- $found = false }}
+{{- end }}
+{{- end }}
+{{- if and $found (not (kindIs "invalid" $cur)) }}true{{ end }}
+{{- end }}
+
+{{/*
+"aisix.dropNulls" deletes every null-valued key from a map, recursively, so a
+null in `config` means "leave it to the gateway's default".
+*/}}
+{{- define "aisix.dropNulls" -}}
+{{- $m := . }}
+{{- range $k, $v := $m }}
+{{- if kindIs "invalid" $v }}
+{{- $_ := unset $m $k }}
+{{- else if kindIs "map" $v }}
+{{- include "aisix.dropNulls" $v }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+"aisix.ensureMap" makes .parent[.key] a map when it
+is absent or null, so a chart-owned key can be set beneath it.
+*/}}
+{{- define "aisix.ensureMap" -}}
+{{- if not (kindIs "map" (get .parent .key)) }}
+{{- $_ := set .parent .key dict }}
+{{- end }}
+{{- end }}
+
+{{/*
+The gateway startup config file: the user's `config` block with the chart-owned
+keys filled in for the mode. Keys the chart owns or that hold a credential are
+rejected by "aisix.validateValues" before this runs.
+*/}}
+{{- define "aisix.configFile" -}}
+{{- $cfg := deepCopy (.Values.config | default dict) }}
+{{- range $section := list "proxy" "observability" "ratelimit" }}
+{{- include "aisix.ensureMap" (dict "parent" $cfg "key" $section) }}
+{{- end }}
+{{- $_ := set $cfg.proxy "addr" (printf "0.0.0.0:%d" (int .Values.containerPorts.proxy)) }}
+{{- if .Values.listeners }}
+{{- $_ := set $cfg.proxy "listeners" (include "aisix.proxyListenersJson" . | fromJsonArray) }}
+{{- end }}
+{{- include "aisix.ensureMap" (dict "parent" $cfg.observability "key" "metrics") }}
+{{- include "aisix.ensureMap" (dict "parent" $cfg.observability.metrics "key" "prometheus") }}
+{{- $_ := set $cfg.observability.metrics.prometheus "addr" (printf "0.0.0.0:%d" (int .Values.containerPorts.metrics)) }}
+{{- $_ := set $cfg.ratelimit "backend" .Values.rateLimit.backend }}
+{{- if .Values.controlPlane.enabled }}
+{{- include "aisix.ensureMap" (dict "parent" $cfg "key" "etcd") }}
+{{- include "aisix.ensureMap" (dict "parent" $cfg "key" "managed") }}
+{{- /* Overwritten at boot from the control-plane connection, but required. */}}
+{{- $_ := set $cfg.etcd "endpoints" (list "https://placeholder-overridden-at-register:2379") }}
+{{- $_ := set $cfg.etcd "prefix" "/aisix" }}
+{{- /* Never bound in control-plane mode; validation requires the slot. */}}
+{{- $_ := set $cfg "admin" (dict "addr" "127.0.0.1:0" "admin_keys" (list "managed-mode-admin-disabled")) }}
+{{- $_ := set $cfg.managed "enabled" true }}
+{{- $_ := set $cfg.managed "cp_base_url" .Values.controlPlane.baseURL }}
+{{- with .Values.controlPlane.etcdEndpoint }}
+{{- $_ := set $cfg.managed "cp_etcd_endpoint" . }}
+{{- end }}
+{{- $_ := set $cfg.managed "heartbeat_interval_secs" (int .Values.controlPlane.heartbeatIntervalSeconds) }}
+{{- $dir := include "aisix.cpCertDir" . }}
+{{- $_ := set $cfg.managed "cp_cert_file" (printf "%s/cert.pem" $dir) }}
+{{- $_ := set $cfg.managed "cp_key_file" (printf "%s/key.pem" $dir) }}
+{{- $_ := set $cfg.managed "cp_ca_file" (printf "%s/ca.pem" $dir) }}
+{{- else }}
+{{- $_ := unset $cfg "etcd" }}
+{{- $_ := unset $cfg "managed" }}
+{{- $_ := set $cfg "resources_file" (include "aisix.standaloneResourcesPath" .) }}
+{{- $_ := set $cfg "admin" (dict "enabled" false) }}
+{{- end }}
+{{- include "aisix.dropNulls" $cfg }}
+{{- toYaml $cfg }}
+{{- end }}
+
+{{/*
+The environment variable the gateway reads a `configSecrets` path from:
+AISIX_ plus the path upper-cased with `.` as `__`.
+*/}}
+{{- define "aisix.configSecretEnvName" -}}
+AISIX_{{ . | upper | replace "." "__" }}
+{{- end }}
+
 {{/*
 Reject value combinations that render successfully but cannot run.
 */}}
@@ -197,11 +293,33 @@ Reject value combinations that render successfully but cannot run.
 {{- if and .Values.keda.enabled (not .Values.keda.triggers) }}
 {{- fail "keda.enabled requires at least one entry in keda.triggers" }}
 {{- end }}
+{{- $config := .Values.config | default dict }}
 {{- if eq .Values.rateLimit.backend "redis" }}
-{{- if not (or .Values.rateLimit.redis.url .Values.rateLimit.redis.existingSecret) }}
+{{- $mode := "single" }}
+{{- if kindIs "map" $config.ratelimit }}{{ if kindIs "map" $config.ratelimit.redis }}{{ $mode = $config.ratelimit.redis.mode | default "single" }}{{ end }}{{ end }}
+{{- if and (eq $mode "single") (not (or .Values.rateLimit.redis.url .Values.rateLimit.redis.existingSecret)) }}
 {{- fail "rateLimit.backend=redis requires rateLimit.redis.url or rateLimit.redis.existingSecret" }}
 {{- end }}
 {{- end }}
+{{- $policy := .Files.Get "config-policy.yaml" | fromYaml }}
+{{- range $path, $use := $policy.owned }}
+{{- if include "aisix.configPathSet" (dict "cfg" $config "path" $path) }}
+{{- fail (printf "config.%s is set by the chart and cannot be written under config: %s" $path $use) }}
+{{- end }}
+{{- end }}
+{{- range $path := $policy.secrets }}
+{{- if include "aisix.configPathSet" (dict "cfg" $config "path" $path) }}
+{{- fail (printf "config.%s holds a credential and is never written to the ConfigMap: set it through configSecrets.%s with a secretName and key" $path $path) }}
+{{- end }}
+{{- end }}
+{{- range $path, $ref := (.Values.configSecrets | default dict) }}
+{{- if not (has $path $policy.secrets) }}
+{{- fail (printf "configSecrets.%s is not a credential-bearing setting; accepted keys: %s" $path (join ", " $policy.secrets)) }}
+{{- end }}
+{{- if not (and (kindIs "map" $ref) $ref.secretName $ref.key) }}
+{{- fail (printf "configSecrets.%s requires secretName and key" $path) }}
+{{- end }}
+{{- end }}
 {{- $names := list }}
 {{- $ports := list }}
 {{- range $i, $listener := .Values.listeners }}
diff --git a/charts/aisix/templates/configmap.yaml b/charts/aisix/templates/configmap.yaml
index 36fe8f1..ee5b72e 100644
--- a/charts/aisix/templates/configmap.yaml
+++ b/charts/aisix/templates/configmap.yaml
@@ -1,4 +1,3 @@
-{{- if not .Values.controlPlane.enabled }}
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -7,15 +6,9 @@ metadata:
     {{- include "aisix.labels" . | nindent 4 }}
     {{- include "aisix.selectorLabels" . | nindent 4 }}
 data:
-  # Startup configuration for standalone mode. It carries only what an
-  # AISIX_-prefixed environment variable cannot express as a default the
-  # user can still override: the resources file to read, and the admin
-  # listener, which defaults to enabled and would refuse to boot without
-  # admin keys. Everything else — the proxy and metrics addresses, the
-  # rate-limit backend, and anything set through `extraEnvVars` — reaches
-  # the gateway as environment variables, which override this file.
+  # The gateway's startup configuration: `config` from values.yaml, with the
+  # keys the chart owns filled in for this mode. Credentials are never here —
+  # they reach the gateway from Secrets, as mounted files or as environment
+  # variables, which override this file.
   config.yaml: |
-    resources_file: {{ include "aisix.standaloneResourcesPath" . }}
-    admin:
-      enabled: false
-{{- end }}
+    {{- include "aisix.configFile" . | trim | nindent 4 }}
diff --git a/charts/aisix/templates/deployment.yaml b/charts/aisix/templates/deployment.yaml
index 02201f9..b5fbc32 100644
--- a/charts/aisix/templates/deployment.yaml
+++ b/charts/aisix/templates/deployment.yaml
@@ -18,30 +18,17 @@ spec:
       {{- include "aisix.selectorLabels" . | nindent 6 }}
   template:
     metadata:
-      {{- if or (not .Values.controlPlane.enabled) (not .Values.controlPlane.certificate.existingSecret) .Values.podAnnotations }}
       annotations:
-        {{- if .Values.controlPlane.enabled }}
-        {{- if not .Values.controlPlane.certificate.existingSecret }}
-        # Roll the pods when the chart-managed bundle changes, so a rotated
-        # certificate takes effect without a manual restart. An existingSecret
-        # has its own lifecycle — restart the Deployment after rotating it.
-        checksum/mtls: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
-        {{- end }}
-        {{- else }}
-        # Roll the pods when the rendered startup config or the chart-managed
-        # resources file changes. The gateway re-reads the resources file on
-        # SIGHUP only and the chart never sends one, so the rollout is what
-        # applies the change. An existingSecret / existingConfigMap has its own
-        # lifecycle — restart the Deployment after editing it.
+        # Roll the pods when the rendered startup config or a chart-managed
+        # Secret (mTLS bundle, resources file, rate-limit Redis URL) changes:
+        # the gateway reads all of them at boot only. A Secret or ConfigMap
+        # supplied by name has its own lifecycle — restart the Deployment
+        # after editing it.
         checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
-        {{- if .Values.standalone.resources }}
-        checksum/resources: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
-        {{- end }}
-        {{- end }}
+        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
         {{- with .Values.podAnnotations }}
         {{- toYaml . | nindent 8 }}
         {{- end }}
-      {{- end }}
       labels:
         {{- include "aisix.labels" . | nindent 8 }}
         {{- include "aisix.selectorLabels" . | nindent 8 }}
@@ -92,57 +79,23 @@ spec:
               protocol: TCP
           env:
             - name: AISIX_CONFIG_PATH
-              {{- if .Values.controlPlane.enabled }}
-              value: /etc/aisix/config.managed.yaml
-              {{- else }}
-              value: {{ include "aisix.standaloneConfigPath" . }}
-              {{- end }}
-            - name: AISIX_PROXY__ADDR
-              value: "0.0.0.0:{{ .Values.containerPorts.proxy }}"
-            {{- if .Values.listeners }}
-            # The complete set of proxy listeners, as one JSON document: the
-            # gateway takes no indexed environment variables. It replaces the
-            # single listener AISIX_PROXY__ADDR describes — that address is
-            # then required but ignored, and nothing binds it.
-            - name: AISIX_PROXY__LISTENERS
-              value: {{ include "aisix.proxyListenersJson" . | quote }}
-            {{- end }}
-            - name: AISIX_OBSERVABILITY__METRICS__PROMETHEUS__ADDR
-              value: "0.0.0.0:{{ .Values.containerPorts.metrics }}"
-            {{- if .Values.controlPlane.enabled }}
-            - name: AISIX_MANAGED__CP_BASE_URL
-              value: {{ .Values.controlPlane.baseURL | quote }}
-            {{- with .Values.controlPlane.etcdEndpoint }}
-            - name: AISIX_MANAGED__CP_ETCD_ENDPOINT
-              value: {{ . | quote }}
-            {{- end }}
-            - name: AISIX_MANAGED__HEARTBEAT_INTERVAL_SECS
-              value: {{ .Values.controlPlane.heartbeatIntervalSeconds | quote }}
-            - name: AISIX_MANAGED__CP_CERT_PEM
-              valueFrom:
-                secretKeyRef:
-                  name: {{ include "aisix.certSecretName" . }}
-                  key: {{ .Values.controlPlane.certificate.certKey }}
-            - name: AISIX_MANAGED__CP_KEY_PEM
-              valueFrom:
-                secretKeyRef:
-                  name: {{ include "aisix.certSecretName" . }}
-                  key: {{ .Values.controlPlane.certificate.keyKey }}
-            - name: AISIX_MANAGED__CP_CA_PEM
-              valueFrom:
-                secretKeyRef:
-                  name: {{ include "aisix.certSecretName" . }}
-                  key: {{ .Values.controlPlane.certificate.caKey }}
-            {{- end }}
+              value: {{ include "aisix.configPath" . }}
             {{- if eq .Values.rateLimit.backend "redis" }}
-            - name: AISIX_RATELIMIT__BACKEND
-              value: "redis"
+            {{- if or .Values.rateLimit.redis.url .Values.rateLimit.redis.existingSecret }}
             - name: AISIX_RATELIMIT__REDIS__URL
               valueFrom:
                 secretKeyRef:
                   name: {{ include "aisix.redisSecretName" . }}
                   key: {{ include "aisix.redisSecretKey" . }}
             {{- end }}
+            {{- end }}
+            {{- range $path, $ref := (.Values.configSecrets | default dict) }}
+            - name: {{ include "aisix.configSecretEnvName" $path }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ $ref.secretName }}
+                  key: {{ $ref.key }}
+            {{- end }}
             {{- with .Values.extraEnvVars }}
             {{- toYaml . | nindent 12 }}
             {{- end }}
@@ -216,12 +169,16 @@ spec:
             # instances, and a restarted pod re-registers.
             - name: state
               mountPath: /var/lib/aisix
-            {{- if not .Values.controlPlane.enabled }}
-            # Each in its own directory, so neither mount shadows the
+            # Each in its own directory, so no mount shadows the
             # /etc/aisix/config.managed.yaml the image ships.
             - name: config
-              mountPath: {{ include "aisix.standaloneConfigDir" . }}
+              mountPath: {{ include "aisix.configDir" . }}
+              readOnly: true
+            {{- if .Values.controlPlane.enabled }}
+            - name: cp-mtls
+              mountPath: {{ include "aisix.cpCertDir" . }}
               readOnly: true
+            {{- else }}
             - name: resources
               mountPath: {{ include "aisix.standaloneResourcesDir" . }}
               readOnly: true
@@ -241,10 +198,21 @@ spec:
       volumes:
         - name: state
           emptyDir: {}
-        {{- if not .Values.controlPlane.enabled }}
         - name: config
           configMap:
             name: {{ include "aisix.fullname" . }}-config
+        {{- if .Values.controlPlane.enabled }}
+        - name: cp-mtls
+          secret:
+            secretName: {{ include "aisix.certSecretName" . }}
+            items:
+              - key: {{ .Values.controlPlane.certificate.certKey }}
+                path: cert.pem
+              - key: {{ .Values.controlPlane.certificate.keyKey }}
+                path: key.pem
+              - key: {{ .Values.controlPlane.certificate.caKey }}
+                path: ca.pem
+        {{- else }}
         - name: resources
           {{- if .Values.standalone.existingConfigMap }}
           configMap:
diff --git a/charts/aisix/templates/secret.yaml b/charts/aisix/templates/secret.yaml
index e262576..a8e951f 100644
--- a/charts/aisix/templates/secret.yaml
+++ b/charts/aisix/templates/secret.yaml
@@ -31,7 +31,7 @@ stringData:
   resources.yaml: |
 {{ toYaml .Values.standalone.resources | indent 4 }}
 {{- end }}
-{{- if and (eq .Values.rateLimit.backend "redis") (not .Values.rateLimit.redis.existingSecret) }}
+{{- if and (eq .Values.rateLimit.backend "redis") (not .Values.rateLimit.redis.existingSecret) .Values.rateLimit.redis.url }}
 ---
 apiVersion: v1
 kind: Secret
diff --git a/charts/aisix/values.yaml b/charts/aisix/values.yaml
index 3a061cb..564c0db 100644
--- a/charts/aisix/values.yaml
+++ b/charts/aisix/values.yaml
@@ -179,6 +179,189 @@ rateLimit:
     # -- Secret key holding the connection URL
     existingSecretKey: "redis-url"
 
+## Gateway startup configuration, rendered into the config file the gateway
+## boots from (a ConfigMap mounted read-only, the same in both modes). It
+## mirrors that file one-to-one — the section and key names are the gateway's
+## own, as in its `config.example.yaml` — and every key is listed with the
+## gateway's own default, so an untouched block renders the configuration the
+## gateway would use anyway. A `null` key is left out of the file, which means
+## "the gateway's default".
+##
+## A few keys are set by the chart from its own values and must not be written
+## here — the render fails naming the value to use instead: the proxy and
+## metrics addresses (`containerPorts`), `proxy.listeners` / `proxy.tls`
+## (`listeners`), `ratelimit.backend` and `ratelimit.redis.url` (`rateLimit`),
+## the control-plane connection under `managed` (`controlPlane`),
+## `resources_file` (`standalone`), and `admin` (not deployed by this chart).
+## Keys that hold a credential are never written to the ConfigMap either: set
+## them through `configSecrets` below.
+##
+## A change here rolls the pods on `helm upgrade`.
+config:
+  # -- Deployment-wide AWS Bedrock endpoint override for bedrock guardrails,
+  # e.g. a LocalStack URL. Null uses the AWS SDK default
+  bedrock_endpoint_url: null
+  proxy:
+    # -- Request-body size cap in bytes. 0 means no cap
+    request_body_limit_bytes: 0
+    real_ip:
+      # -- CIDRs (or bare IPs) of proxies trusted to set the client-IP header
+      trusted_proxies: []
+      # -- Walk the header right to left past every trusted proxy
+      recursive: false
+      # -- Header carrying the client IP
+      header: x-forwarded-for
+    request_id:
+      # -- Headers a caller may supply its own request id in. Add
+      # `x-request-id` only when no proxy in front stamps it
+      accept_headers:
+        - x-aisix-request-id
+    # -- (bool) Thread-per-core serving topology. Null uses the gateway default (on
+    # for Linux)
+    thread_per_core: null
+    # -- (int) Worker count. Null uses the gateway default
+    workers: null
+    # -- Entry-level URL rewrite rules, first match wins, e.g.
+    # `[{name: per-server-mcp, match: "^/mcp-servers/([^/]+)/mcp$", rewrite: "/mcp/$1"}]`
+    url_rewrites: []
+  observability:
+    # -- Service name reported in telemetry
+    service_name: aisix
+    # -- Log level: trace, debug, info, warn or error
+    log_level: info
+    # -- Write an access-log line per request
+    access_log: true
+    metrics:
+      # -- Complete optional label list per metric, e.g.
+      # `{aisix_request_ttft_seconds: [model, provider]}`. Omitted metrics keep
+      # their default labels
+      labels: {}
+      # -- User-Agent to `client_type` mapping rules, first match wins, e.g.
+      # `[{pattern: "^py-billing-batcher/", client: billing-batcher}]`
+      client_type_rules: []
+      # -- Per-metric histogram bucket edges in seconds. Null keeps that
+      # metric's default buckets
+      buckets:
+        request_ttft: null
+        request_e2e_latency: null
+        guardrail_latency: null
+        a2a_ttfb: null
+      prometheus:
+        # -- Serve Prometheus metrics on the metrics listener
+        # (`containerPorts.metrics`)
+        enabled: true
+        # -- Metrics path
+        path: /metrics
+    debug:
+      # -- Serve the unauthenticated heap-profile endpoint
+      # (`/debug/pprof/heap`)
+      enabled: true
+      # -- Diagnostics listener address. Loopback keeps it off the network
+      addr: "127.0.0.1:9091"
+    heap_profiling:
+      auto_dump:
+        # -- Write a heap profile as resident memory nears the memory limit
+        enabled: true
+        # -- Fractions of the memory limit that each trigger one profile
+        thresholds:
+          - 0.8
+          - 0.9
+        # -- Directory the profiles are written to
+        dir: /var/lib/aisix/heap
+        # -- Newest profiles kept
+        keep: 5
+  cache:
+    # -- Legacy cache backend switch, `memory` or `redis`. `redis` requires
+    # `cache.redis`. Which cache serves a request is chosen per cache policy
+    backend: memory
+    # -- (object) Shared Redis for the response cache, e.g. `{mode: single}`; the redis
+    # cache is built only when this is set. Keys: `mode` (single, cluster,
+    # sentinel), `nodes`, `sentinels`, `master_name`, `database`, `tls`,
+    # `timeout_secs`. `url`, `username` and `password` go through
+    # `configSecrets`
+    redis: null
+  ratelimit:
+    # -- Seconds a concurrency-limit slot is held at most
+    concurrency_ttl_secs: 300
+    # -- (object) Extra settings for the shared rate-limit Redis selected by
+    # `rateLimit.backend: redis`, e.g. `{timeout_secs: 2}` or
+    # `{mode: cluster, nodes: [...]}`. Same keys as `cache.redis`; the URL
+    # comes from `rateLimit.redis`, `username` and `password` go through
+    # `configSecrets`
+    redis: null
+  upstream:
+    # -- Request timeout for calls to LLM providers, in milliseconds
+    timeout_ms: 6000000
+    # -- Streaming idle timeout in milliseconds. 0 means none
+    stream_timeout_ms: 0
+    # -- Connect timeout in milliseconds
+    connect_timeout_ms: 5000
+    # -- TCP keepalive idle time in seconds
+    tcp_keepalive_secs: 60
+    # -- TCP keepalive probe interval in seconds
+    tcp_keepalive_interval_secs: 30
+    # -- TCP keepalive probes before the connection is dropped
+    tcp_keepalive_retries: 5
+    # -- Seconds an idle pooled connection is kept. Lower it when a load
+    # balancer or NAT between the gateway and the provider closes idle
+    # connections sooner
+    pool_idle_timeout_secs: 30
+    # -- (int) Idle pooled connections kept per host. Null means unbounded
+    pool_max_idle_per_host: null
+    # -- Retry budget every dispatch starts from
+    retries: 2
+    tls:
+      # -- Extra CA bundle, added to the platform trust store, for every
+      # upstream TLS handshake. Mount the file through `extraVolumes`
+      ca_file: null
+      # -- Client certificate for mutual TLS to upstreams
+      client_cert_file: null
+      # -- Client key for mutual TLS to upstreams
+      client_key_file: null
+      # -- Verify upstream certificates. false accepts any certificate — test
+      # use only
+      verify: true
+  downstream:
+    # -- Seconds an idle client connection is held. 0 never closes it
+    idle_timeout_secs: 0
+    # -- Seconds between SSE keepalive comments on a stalled stream
+    sse_keepalive_interval_secs: 15
+  shutdown:
+    # -- Seconds the gateway keeps accepting after SIGTERM while `/readyz`
+    # reports 503. `terminationGracePeriodSeconds` must cover it
+    min_drain_secs: 30
+  ## Read in control-plane mode only.
+  etcd:
+    # -- Bound on one dial to the control plane's etcd, in milliseconds. 0
+    # means unbounded
+    dial_timeout_ms: 5000
+    # -- (int) Bound on one etcd request, in milliseconds. Null means unbounded
+    request_timeout_ms: null
+  ## Read in control-plane mode only. The connection itself comes from
+  ## `controlPlane`.
+  managed:
+    # -- Extra CA bundle trusted for the control-plane connection, when it
+    # serves a private-CA certificate. Mount the file through `extraVolumes`
+    cp_ca_cert_file: null
+    # -- Directory the materialised mTLS bundle is written to
+    mtls_dir: /var/lib/aisix/mtls
+    # -- File the gateway id is persisted in
+    dp_id_file: /var/lib/aisix/dp_id
+    # -- Persist a configuration snapshot for recovery while etcd is
+    # unreachable. The snapshot holds unencrypted credentials
+    snapshot_cache_enabled: false
+    # -- Snapshot location. Null uses `/var/lib/aisix/config_cache.json`
+    snapshot_cache_path: null
+
+# -- Configuration keys that hold a credential, each read from a Secret you
+# supply and handed to the gateway as an environment variable (which
+# overrides the config file), never written to the ConfigMap. Keyed by the
+# configuration path: `cache.redis.url`, `cache.redis.username`,
+# `cache.redis.password`, `ratelimit.redis.username` or
+# `ratelimit.redis.password`. For example
+# `{cache.redis.password: {secretName: redis-auth, key: password}}`
+configSecrets: {}
+
 ## HorizontalPodAutoscaler. Scaling is safe by construction: a new replica is
 ## kept out of the Service until its readiness probe passes, which happens
 ## only after it has loaded its configuration from the control plane.
@@ -355,8 +538,9 @@ terminationGracePeriodSeconds: 1230
 # with `/readyz` already answering 503.
 preStopSleepSeconds: 30
 
-# -- Extra environment variables for the gateway container. Every gateway
-# configuration field is reachable as `AISIX_<SECTION>__<FIELD>`
+# -- Extra environment variables for the gateway container: system-level
+# environment variables (such as `TZ`) and variables referenced by the
+# resources file. Gateway settings belong in `config`
 extraEnvVars: []
 
 # -- Extra volumes for the gateway pod

From e39029bcfe903f38bccec051eadc2693c9187410 Mon Sep 17 00:00:00 2001
From: Jarvis <jarvis@api7.ai>
Date: Tue, 29 Sep 2026 07:31:15 +0000
Subject: [PATCH 2/5] fix(aisix): reject dotted keys under config

A literal `cache.redis.password` key (at any depth) slipped past the
owned/secret path checks, which walk nested maps, and would have landed
in the ConfigMap. config is nested maps only; a dotted key now fails the
render.
---
 charts/aisix/templates/_helpers.tpl | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/charts/aisix/templates/_helpers.tpl b/charts/aisix/templates/_helpers.tpl
index 8e0185e..da26c13 100644
--- a/charts/aisix/templates/_helpers.tpl
+++ b/charts/aisix/templates/_helpers.tpl
@@ -186,6 +186,19 @@ non-null value in the map .cfg.
 {{- if and $found (not (kindIs "invalid" $cur)) }}true{{ end }}
 {{- end }}
 
+{{/*
+"aisix.configDottedKey" prints the first key under .cfg (recursively, prefixed
+by .at) that contains a `.`. `config` is nested maps; a literal
+`cache.redis.password` key would slip past the path checks below.
+*/}}
+{{- define "aisix.configDottedKey" -}}
+{{- $at := .at }}
+{{- range $k, $v := .cfg }}
+{{- if contains "." $k }}{{ printf "%s%s" $at $k }}{{ end }}
+{{- if kindIs "map" $v }}{{ include "aisix.configDottedKey" (dict "cfg" $v "at" (printf "%s%s." $at $k)) }}{{ end }}
+{{- end }}
+{{- end }}
+
 {{/*
 "aisix.dropNulls" deletes every null-valued key from a map, recursively, so a
 null in `config` means "leave it to the gateway's default".
@@ -301,6 +314,9 @@ Reject value combinations that render successfully but cannot run.
 {{- fail "rateLimit.backend=redis requires rateLimit.redis.url or rateLimit.redis.existingSecret" }}
 {{- end }}
 {{- end }}
+{{- with include "aisix.configDottedKey" (dict "cfg" $config "at" "") }}
+{{- fail (printf "config key %q contains a dot: write config as nested maps, e.g. cache: {redis: {mode: single}}" .) }}
+{{- end }}
 {{- $policy := .Files.Get "config-policy.yaml" | fromYaml }}
 {{- range $path, $use := $policy.owned }}
 {{- if include "aisix.configPathSet" (dict "cfg" $config "path" $path) }}

From 30b07021060941a67aa9c3852da10e010fb43a76 Mon Sep 17 00:00:00 2001
From: Jarvis <jarvis@api7.ai>
Date: Tue, 29 Sep 2026 07:37:33 +0000
Subject: [PATCH 3/5] fix(aisix): keep PEM env wiring for releases that set it;
 drift-check optional sub-keys

A release that sets AISIX_MANAGED__CP_{CERT,KEY,CA}_PEM through
extraEnvVars would fail to boot once the chart wrote managed.cp_*_file
(the gateway rejects a PEM and a file for one slot). Such a release now
keeps the 1.5.0 wiring: all three PEMs as secretKeyRef env vars from the
bundle Secret, no file keys, no mount.

The drift check reads config.reference.json's new optional_blocks and
fails on a sub-key of cache.redis / ratelimit.redis that
config-policy.yaml neither documents (optional), owns, nor routes
through configSecrets.

.github/scripts/aisix-render-checks.sh pins the rendering: file vs PEM
wiring, configSecrets env, list keys, standalone sections, and the
refusals. Wired into CI.
---
 .github/scripts/aisix-render-checks.sh      | 67 +++++++++++++++++++++
 .github/scripts/check-aisix-config-drift.py | 21 ++++++-
 .github/workflows/ci.yaml                   |  3 +
 AGENTS.md                                   |  2 +
 charts/aisix/config-policy.yaml             | 28 +++++++++
 charts/aisix/templates/_helpers.tpl         | 15 +++++
 charts/aisix/templates/deployment.yaml      | 13 ++++
 7 files changed, 147 insertions(+), 2 deletions(-)
 create mode 100644 .github/scripts/aisix-render-checks.sh

diff --git a/.github/scripts/aisix-render-checks.sh b/.github/scripts/aisix-render-checks.sh
new file mode 100644
index 0000000..312c56f
--- /dev/null
+++ b/.github/scripts/aisix-render-checks.sh
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Render-time assertions for charts/aisix: what the config file, env and
+# volumes look like for a given set of values, and which values the chart
+# refuses. Needs helm and python3 with PyYAML.
+set -euo pipefail
+
+chart=charts/aisix
+base=(-f "$chart/ci/default-values.yaml")
+fails=0
+
+render() { helm template ci "$chart" "${base[@]}" "$@"; }
+
+# query <python expr over `docs` (the rendered manifests)> <helm args...>
+query() {
+  local expr=$1
+  shift
+  render "$@" | python3 -c '
+import sys, yaml
+docs = [d for d in yaml.safe_load_all(sys.stdin) if d]
+dep = next(d for d in docs if d["kind"] == "Deployment")
+pod = dep["spec"]["template"]["spec"]
+env = {e["name"]: e for e in pod["containers"][0].get("env", [])}
+vols = {v["name"] for v in pod.get("volumes", [])}
+cm = next(d for d in docs if d["kind"] == "ConfigMap" and d["metadata"]["name"].endswith("-config"))
+cfg = yaml.safe_load(cm["data"]["config.yaml"])
+sys.exit(0 if eval(sys.argv[1]) else 1)
+' "$expr"
+}
+
+check() {
+  local what=$1
+  shift
+  if "$@"; then echo "ok   $what"; else echo "FAIL $what"; fails=$((fails + 1)); fi
+}
+
+refuses() {
+  local want=$1
+  shift
+  local out
+  if out=$(render "$@" 2>&1); then return 1; fi
+  grep -q -- "$want" <<<"$out"
+}
+
+check "control-plane mode mounts the mTLS bundle as files" \
+  query '"cp-mtls" in vols and cfg["managed"]["cp_cert_file"] == "/etc/aisix/cp-mtls/cert.pem" and not any(n.startswith("AISIX_MANAGED__CP_") for n in env)'
+check "extraEnvVars PEMs keep the env wiring: no file keys, no mount, all three PEMs from the bundle Secret" \
+  query '"cp-mtls" not in vols and not any(k.startswith("cp_") and k.endswith("_file") for k in cfg["managed"]) and all(env[f"AISIX_MANAGED__CP_{s}_PEM"].get("valueFrom") or env[f"AISIX_MANAGED__CP_{s}_PEM"].get("value") for s in ("CERT", "KEY", "CA"))' \
+  --set 'extraEnvVars[0].name=AISIX_MANAGED__CP_CERT_PEM' --set 'extraEnvVars[0].value=pem'
+check "configSecrets becomes a secretKeyRef env var" \
+  query 'env["AISIX_CACHE__REDIS__PASSWORD"]["valueFrom"]["secretKeyRef"] == {"name": "redis-auth", "key": "password"}' \
+  --set 'configSecrets.cache\.redis\.password.secretName=redis-auth' --set 'configSecrets.cache\.redis\.password.key=password'
+check "config values land in the file, list-typed ones included" \
+  query 'cfg["observability"]["heap_profiling"]["auto_dump"]["thresholds"] == [0.7, 0.95] and cfg["proxy"]["request_id"]["accept_headers"] == ["x-aisix-request-id", "x-request-id"]' \
+  -f "$chart/ci/config-values.yaml"
+check "standalone mode renders no etcd or managed section" \
+  query '"etcd" not in cfg and "managed" not in cfg and cfg["admin"] == {"enabled": False} and cfg["resources_file"]' \
+  -f "$chart/ci/standalone-values.yaml"
+check "a chart-owned key under config is refused" \
+  refuses "use containerPorts.proxy" --set config.proxy.addr=0.0.0.0:1
+check "a credential under config is refused" \
+  refuses "set it through configSecrets.cache.redis.password" --set config.cache.redis.password=x
+check "a dotted key under config is refused" \
+  refuses "contains a dot" --set 'config.cache\.redis\.password=x'
+check "configSecrets outside the allow-list is refused" \
+  refuses "not a credential-bearing setting" --set 'configSecrets.upstream\.timeout_ms.secretName=a' --set 'configSecrets.upstream\.timeout_ms.key=b'
+
+[ "$fails" -eq 0 ] || { echo "$fails render check(s) failed"; exit 1; }
diff --git a/.github/scripts/check-aisix-config-drift.py b/.github/scripts/check-aisix-config-drift.py
index 344d729..7035582 100644
--- a/.github/scripts/check-aisix-config-drift.py
+++ b/.github/scripts/check-aisix-config-drift.py
@@ -5,7 +5,8 @@
 its default — at the root of api7/aisix. This compares it, at the tag of the
 chart's appVersion, with the chart's `config:` block: the same keys, with the
 same defaults, except the keys charts/aisix/config-policy.yaml names as set by
-the chart or held in Secrets.
+the chart or held in Secrets; and, for each block that is off unless written,
+the same sub-keys as config-policy.yaml accounts for.
 
 A release that predates config.reference.json has no tag copy; the check then
 falls back to api7/aisix main and says so. CONFIG_REFERENCE_FILE points the
@@ -71,10 +72,26 @@ def main():
             sys.exit("api7/aisix main has no config.reference.json")
 
     skip = list(policy["owned"]) + list(policy["secrets"])
-    want = {k: v for k, v in flatten(reference).items() if not excluded(k, skip)}
+    want = {k: v for k, v in flatten(reference["defaults"]).items() if not excluded(k, skip)}
     have = flatten(chart_config)
 
     problems = []
+    # Blocks that are off unless written: every gateway sub-key must be one
+    # the chart documents, owns, or routes through configSecrets.
+    documented = policy.get("optional") or {}
+    for block, keys in sorted(reference["optional_blocks"].items()):
+        if excluded(block, skip):
+            continue
+        listed = {f"{block}.{k}" for k in documented.get(block, [])}
+        for path in sorted(f"{block}.{k}" for k in flatten(keys)):
+            if path not in listed and not excluded(path, skip):
+                problems.append(
+                    f"unaccounted sub-key: {path} — add it to config-policy.yaml "
+                    f"optional.{block}, or to secrets if it holds a credential"
+                )
+        for path in sorted(listed - {f"{block}.{k}" for k in flatten(keys)}):
+            problems.append(f"not a gateway setting at {ref}: {path} (config-policy.yaml optional)")
+
     for path in sorted(want.keys() - have.keys()):
         problems.append(f"missing from config: {path} (gateway default {json.dumps(want[path])})")
     for path in sorted(have.keys() - want.keys()):
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 46792a6..ed7ba3d 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -46,6 +46,9 @@ jobs:
           python3 -c 'import yaml' 2>/dev/null || sudo apt-get install -y python3-yaml
           python3 .github/scripts/check-aisix-config-drift.py
 
+      - name: Check aisix chart renders
+        run: bash .github/scripts/aisix-render-checks.sh
+
       - name: Boot the aisix gateway on the chart-rendered config
         run: bash .github/scripts/aisix-config-boot.sh
 
diff --git a/AGENTS.md b/AGENTS.md
index 445617b..4ffdef0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,6 +85,8 @@ How the chart implements it:
 - `config:` mirrors the gateway's startup file one-to-one — the same section and key names as `config.example.yaml` / `crates/aisix-core/src/config.rs` in `api7/aisix` — with every key listed at the gateway's own default (`null` = omitted = gateway default). No chart-specific renaming. `aisix.configFile` in `_helpers.tpl` renders it into `templates/configmap.yaml` in both modes, fills the chart-owned keys for the mode, and drops nulls. The pod template carries `checksum/config` and `checksum/secret`, so a change rolls the pods.
 - `config-policy.yaml` is the single list of what `config:` does not carry: `owned` keys the chart sets from its other values (listen addresses, `listeners`, `rateLimit`, `controlPlane`, `standalone`, `admin`, most of `etcd`), and `secrets` — credential-bearing keys, set only through `configSecrets` and wired as `secretKeyRef` env. The render fails when `config:` names either kind. Credentials never go into the ConfigMap: where the gateway has a `*_file` key (the control-plane mTLS bundle) the Secret is mounted as a file, otherwise it is a chart-managed `secretKeyRef` env var.
 - `.github/scripts/check-aisix-config-drift.py` compares `config:` with `config.reference.json` from `api7/aisix` at `v<appVersion>` (falling back to `main` for a tag that predates the file), minus `config-policy.yaml`. So a new gateway key, a changed default, or a new chart-owned/secret key is a `values.yaml` or `config-policy.yaml` edit, made with the chart bump that moves `appVersion` to the release that has it — not earlier, since the chart only runs its own `appVersion` image and an older gateway rejects unknown keys.
+- `config-policy.yaml` also lists, under `optional`, the documented sub-keys of the blocks that are off unless written (`cache.redis`, `ratelimit.redis`); the drift check fails on a gateway sub-key there that none of the three lists accounts for.
+- A release that sets `AISIX_MANAGED__CP_*_PEM` through `extraEnvVars` keeps the pre-file wiring (PEM env vars from the bundle Secret, no `cp_*_file`, no mount): the gateway rejects a PEM and a file for the same slot. `.github/scripts/aisix-render-checks.sh` pins that and the refusals; extend it when the rendering changes.
 - `.github/scripts/aisix-config-boot.sh` boots the `appVersion` image on the rendered file in both modes with `ci/config-values.yaml`; run it locally after changing `config:` or `aisix.configFile`.
 - Values keys are a compatibility surface for `helm upgrade` from released charts, `--reuse-values` included — and `--reuse-values` replaces the new chart's defaults with the old release's values, so a template must treat a new values key as possibly absent (`| default dict`).
 
diff --git a/charts/aisix/config-policy.yaml b/charts/aisix/config-policy.yaml
index 6e88561..884e295 100644
--- a/charts/aisix/config-policy.yaml
+++ b/charts/aisix/config-policy.yaml
@@ -39,3 +39,31 @@ secrets:
   - cache.redis.password
   - ratelimit.redis.username
   - ratelimit.redis.password
+
+# Sub-keys of the blocks that are off unless written (`null` in values.yaml),
+# other than the owned and secret ones above. `config` passes these blocks
+# through as written; the list is what the chart documents for them, and the
+# drift check fails on a gateway sub-key that is in none of the three lists.
+optional:
+  cache.redis:
+    - mode
+    - nodes
+    - sentinels
+    - master_name
+    - database
+    - timeout_secs
+    - tls.ca_file
+    - tls.client_cert_file
+    - tls.client_key_file
+    - tls.verify
+  ratelimit.redis:
+    - mode
+    - nodes
+    - sentinels
+    - master_name
+    - database
+    - timeout_secs
+    - tls.ca_file
+    - tls.client_cert_file
+    - tls.client_key_file
+    - tls.verify
diff --git a/charts/aisix/templates/_helpers.tpl b/charts/aisix/templates/_helpers.tpl
index da26c13..fcf526c 100644
--- a/charts/aisix/templates/_helpers.tpl
+++ b/charts/aisix/templates/_helpers.tpl
@@ -256,10 +256,12 @@ rejected by "aisix.validateValues" before this runs.
 {{- $_ := set $cfg.managed "cp_etcd_endpoint" . }}
 {{- end }}
 {{- $_ := set $cfg.managed "heartbeat_interval_secs" (int .Values.controlPlane.heartbeatIntervalSeconds) }}
+{{- if not (include "aisix.cpPemFromEnv" .) }}
 {{- $dir := include "aisix.cpCertDir" . }}
 {{- $_ := set $cfg.managed "cp_cert_file" (printf "%s/cert.pem" $dir) }}
 {{- $_ := set $cfg.managed "cp_key_file" (printf "%s/key.pem" $dir) }}
 {{- $_ := set $cfg.managed "cp_ca_file" (printf "%s/ca.pem" $dir) }}
+{{- end }}
 {{- else }}
 {{- $_ := unset $cfg "etcd" }}
 {{- $_ := unset $cfg "managed" }}
@@ -270,6 +272,19 @@ rejected by "aisix.validateValues" before this runs.
 {{- toYaml $cfg }}
 {{- end }}
 
+{{/*
+"aisix.cpPemFromEnv" is non-empty when `extraEnvVars` sets one of the
+AISIX_MANAGED__CP_*_PEM variables — a setup from before the chart mounted the
+bundle as files. The gateway rejects a PEM and a file for the same slot, so
+such a release keeps the 1.5.0 wiring: all three PEMs as environment variables
+from the bundle Secret (which extraEnvVars then overrides), and no file keys.
+*/}}
+{{- define "aisix.cpPemFromEnv" -}}
+{{- range .Values.extraEnvVars }}
+{{- if has .name (list "AISIX_MANAGED__CP_CERT_PEM" "AISIX_MANAGED__CP_KEY_PEM" "AISIX_MANAGED__CP_CA_PEM") }}true{{ end }}
+{{- end }}
+{{- end }}
+
 {{/*
 The environment variable the gateway reads a `configSecrets` path from:
 AISIX_ plus the path upper-cased with `.` as `__`.
diff --git a/charts/aisix/templates/deployment.yaml b/charts/aisix/templates/deployment.yaml
index b5fbc32..30d407a 100644
--- a/charts/aisix/templates/deployment.yaml
+++ b/charts/aisix/templates/deployment.yaml
@@ -80,6 +80,15 @@ spec:
           env:
             - name: AISIX_CONFIG_PATH
               value: {{ include "aisix.configPath" . }}
+            {{- if and .Values.controlPlane.enabled (include "aisix.cpPemFromEnv" .) }}
+            {{- range $slot, $key := dict "CERT" .Values.controlPlane.certificate.certKey "KEY" .Values.controlPlane.certificate.keyKey "CA" .Values.controlPlane.certificate.caKey }}
+            - name: AISIX_MANAGED__CP_{{ $slot }}_PEM
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "aisix.certSecretName" $ }}
+                  key: {{ $key }}
+            {{- end }}
+            {{- end }}
             {{- if eq .Values.rateLimit.backend "redis" }}
             {{- if or .Values.rateLimit.redis.url .Values.rateLimit.redis.existingSecret }}
             - name: AISIX_RATELIMIT__REDIS__URL
@@ -175,9 +184,11 @@ spec:
               mountPath: {{ include "aisix.configDir" . }}
               readOnly: true
             {{- if .Values.controlPlane.enabled }}
+            {{- if not (include "aisix.cpPemFromEnv" .) }}
             - name: cp-mtls
               mountPath: {{ include "aisix.cpCertDir" . }}
               readOnly: true
+            {{- end }}
             {{- else }}
             - name: resources
               mountPath: {{ include "aisix.standaloneResourcesDir" . }}
@@ -202,6 +213,7 @@ spec:
           configMap:
             name: {{ include "aisix.fullname" . }}-config
         {{- if .Values.controlPlane.enabled }}
+        {{- if not (include "aisix.cpPemFromEnv" .) }}
         - name: cp-mtls
           secret:
             secretName: {{ include "aisix.certSecretName" . }}
@@ -212,6 +224,7 @@ spec:
                 path: key.pem
               - key: {{ .Values.controlPlane.certificate.caKey }}
                 path: ca.pem
+        {{- end }}
         {{- else }}
         - name: resources
           {{- if .Values.standalone.existingConfigMap }}

From 86d2e69c6c9754db983674a915a0d4131c34bc61 Mon Sep 17 00:00:00 2001
From: Jarvis <jarvis@api7.ai>
Date: Tue, 29 Sep 2026 07:40:52 +0000
Subject: [PATCH 4/5] fix(aisix): drift-check list-of-struct element sub-keys
 too

config.reference.json lists url_rewrites[] and client_type_rules[]
elements; config-policy.yaml documents their keys, and an owned list
(proxy.listeners) excludes its element.
---
 .github/scripts/check-aisix-config-drift.py |  2 +-
 charts/aisix/config-policy.yaml             | 13 +++++++++++--
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/.github/scripts/check-aisix-config-drift.py b/.github/scripts/check-aisix-config-drift.py
index 7035582..2caca01 100644
--- a/.github/scripts/check-aisix-config-drift.py
+++ b/.github/scripts/check-aisix-config-drift.py
@@ -45,7 +45,7 @@ def flatten(node, prefix=""):
 
 
 def excluded(path, prefixes):
-    return any(path == p or path.startswith(p + ".") for p in prefixes)
+    return any(path == p or path.startswith((p + ".", p + "[]")) for p in prefixes)
 
 
 def main():
diff --git a/charts/aisix/config-policy.yaml b/charts/aisix/config-policy.yaml
index 884e295..fef43ca 100644
--- a/charts/aisix/config-policy.yaml
+++ b/charts/aisix/config-policy.yaml
@@ -40,8 +40,9 @@ secrets:
   - ratelimit.redis.username
   - ratelimit.redis.password
 
-# Sub-keys of the blocks that are off unless written (`null` in values.yaml),
-# other than the owned and secret ones above. `config` passes these blocks
+# Sub-keys of the blocks that are off unless written (`null` in values.yaml)
+# and of the elements of lists of structs (`<path>[]`), other than the owned
+# and secret ones above. `config` passes these blocks
 # through as written; the list is what the chart documents for them, and the
 # drift check fails on a gateway sub-key that is in none of the three lists.
 optional:
@@ -67,3 +68,11 @@ optional:
     - tls.client_cert_file
     - tls.client_key_file
     - tls.verify
+  proxy.url_rewrites[]:
+    - name
+    - hosts
+    - match
+    - rewrite
+  observability.metrics.client_type_rules[]:
+    - pattern
+    - client

From 5bc703ccae8357dddebc4712f62fbccf320481f1 Mon Sep 17 00:00:00 2001
From: Jarvis <jarvis@api7.ai>
Date: Tue, 29 Sep 2026 07:52:14 +0000
Subject: [PATCH 5/5] test(aisix): pin the 1.5.0-identical PEM env rendering

A release that sets the CP PEMs through extraEnvVars must render the
chart's own PEM variables and then the extraEnvVars ones, duplicates
included, exactly as 1.5.0 did: dropping the chart's copy makes the
upgrade's three-way merge delete both entries of that name, and the
gateway then boots with no certificate bundle.
---
 .github/scripts/aisix-render-checks.sh | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.github/scripts/aisix-render-checks.sh b/.github/scripts/aisix-render-checks.sh
index 312c56f..539ce2d 100644
--- a/.github/scripts/aisix-render-checks.sh
+++ b/.github/scripts/aisix-render-checks.sh
@@ -46,6 +46,12 @@ check "control-plane mode mounts the mTLS bundle as files" \
 check "extraEnvVars PEMs keep the env wiring: no file keys, no mount, all three PEMs from the bundle Secret" \
   query '"cp-mtls" not in vols and not any(k.startswith("cp_") and k.endswith("_file") for k in cfg["managed"]) and all(env[f"AISIX_MANAGED__CP_{s}_PEM"].get("valueFrom") or env[f"AISIX_MANAGED__CP_{s}_PEM"].get("value") for s in ("CERT", "KEY", "CA"))' \
   --set 'extraEnvVars[0].name=AISIX_MANAGED__CP_CERT_PEM' --set 'extraEnvVars[0].value=pem'
+# 1.5.0 rendered the chart's own PEM variables and then the extraEnvVars ones,
+# duplicate names included. Rendering the same pair keeps an upgrade's
+# three-way merge from deleting both entries of a name that one side drops.
+check "extraEnvVars PEMs render after the chart's own, exactly as 1.5.0 did" \
+  query '[e["name"] for e in pod["containers"][0]["env"] if e["name"] == "AISIX_MANAGED__CP_CERT_PEM"] == ["AISIX_MANAGED__CP_CERT_PEM"] * 2 and pod["containers"][0]["env"][[e["name"] for e in pod["containers"][0]["env"]].index("AISIX_MANAGED__CP_CERT_PEM")]["valueFrom"]["secretKeyRef"]["name"] == "aisix-gateway-certificate"' \
+  --set 'extraEnvVars[0].name=AISIX_MANAGED__CP_CERT_PEM' --set 'extraEnvVars[0].value=pem'
 check "configSecrets becomes a secretKeyRef env var" \
   query 'env["AISIX_CACHE__REDIS__PASSWORD"]["valueFrom"]["secretKeyRef"] == {"name": "redis-auth", "key": "password"}' \
   --set 'configSecrets.cache\.redis\.password.secretName=redis-auth' --set 'configSecrets.cache\.redis\.password.key=password'