feat(helm): support gateway config arrays of tables

Author: gmenher

deploy/helm/openshell/templates/_toml.tpl

@@ -97,7 +97,8 @@ field must not require a Helm template change.
 {{- end -}}
 {{- end -}}
 
-{{/* Render the top-level gatewayConfig map as deterministic TOML tables. */}}
+{{/* Render the top-level gatewayConfig map as deterministic TOML tables.
+Top-level lists represent TOML arrays of tables and preserve their YAML order. */}}
 {{- define "openshell.gatewayConfigToml" -}}
 {{- $root := . -}}
 {{- $config := deepCopy (.Values.gatewayConfig | default dict) -}}
@@ -276,7 +277,7 @@ owner: server.*. Override any gatewayConfig copies before serializing TOML. */}}
 {{- range $tableName := keys $config | sortAlpha -}}
 {{- $fields := get $config $tableName -}}
 {{- if ne $fields nil -}}
-{{- if not (kindIs "map" $fields) -}}
+{{- if and (not (kindIs "map" $fields)) (not (kindIs "slice" $fields)) -}}
 {{- fail (printf "gatewayConfig table %q must be a map, got %s" $tableName (kindOf $fields)) -}}
 {{- end -}}
 {{- $header := list -}}
@@ -287,6 +288,7 @@ owner: server.*. Override any gatewayConfig copies before serializing TOML. */}}
 {{- end -}}
 {{- $header = append $header (include "openshell.toml.key" $segment) -}}
 {{- end -}}
+{{- if kindIs "map" $fields -}}
 {{ printf "[%s]\n" (join "." $header) }}
 {{- range $fieldName := keys $fields | sortAlpha }}
 {{- $value := get $fields $fieldName -}}
@@ -297,6 +299,23 @@ owner: server.*. Override any gatewayConfig copies before serializing TOML. */}}
 {{ printf "%s = %s\n" (include "openshell.toml.key" $fieldName) (include "openshell.toml.value" (list $root $value)) }}
 {{- end }}
 {{- end }}
+{{- else -}}
+{{- range $index, $entry := $fields -}}
+{{- if not (kindIs "map" $entry) -}}
+{{- fail (printf "gatewayConfig array-of-tables %q entry %d must be a map, got %s" $tableName $index (kindOf $entry)) -}}
+{{- end -}}
+{{ printf "[[%s]]\n" (join "." $header) }}
+{{- range $fieldName := keys $entry | sortAlpha }}
+{{- $value := get $entry $fieldName -}}
+{{- if ne $value nil }}
+{{- if eq $fieldName "database_url" -}}
+{{- fail "gatewayConfig must not contain database_url; provide database credentials through the chart's Secret-backed OPENSHELL_DB_URL environment variable" -}}
+{{- end -}}
+{{ printf "%s = %s\n" (include "openshell.toml.key" $fieldName) (include "openshell.toml.value" (list $root $value)) }}
+{{- end }}
+{{- end }}
+{{- end -}}
+{{- end -}}
 {{- end -}}
 {{- end -}}
 {{- end -}}

deploy/helm/openshell/tests/gateway_config_serializer_test.yaml

@@ -185,6 +185,33 @@ tests:
           path: data["gateway.toml"]
           pattern: omitted_value
 
+  - it: renders top-level lists as ordered TOML arrays of tables
+    set:
+      gatewayConfig:
+        openshell.gateway.interceptors:
+          - name: governance
+            grpc_endpoint: http://governance.ns.svc.cluster.local:18081
+            order: 0
+            failure_policy: fail_closed
+          - name: audit
+            grpc_endpoint: http://audit.ns.svc.cluster.local:18081
+            order: 1
+            failure_policy: fail_open
+    asserts:
+      - matchRegex:
+          path: data["gateway.toml"]
+          pattern: '(?ms)^\[\[openshell\.gateway\.interceptors\]\]\nfailure_policy = "fail_closed"\ngrpc_endpoint = "http://governance\.ns\.svc\.cluster\.local:18081"\nname = "governance"\norder = 0\n\[\[openshell\.gateway\.interceptors\]\]\nfailure_policy = "fail_open"\ngrpc_endpoint = "http://audit\.ns\.svc\.cluster\.local:18081"\nname = "audit"\norder = 1$'
+
+  - it: rejects non-map entries in a top-level array of tables
+    set:
+      gatewayConfig:
+        example.entries:
+          - valid: true
+          - invalid
+    asserts:
+      - failedTemplate:
+          errorMessage: 'gatewayConfig array-of-tables "example.entries" entry 1 must be a map, got string'
+
   - it: evaluates templates only in string values
     set:
       gatewayConfig:

docs/how-it-works/gateways/configuration.mdx

@@ -36,9 +36,15 @@ copies referenced Secret data into `gateway.toml`.
 
 The serializer has a deterministic YAML-to-TOML contract. YAML `null` fields
 are omitted; `null` array members are rejected because TOML has no equivalent.
-Strings, booleans, integers, and floats preserve their types. Scalar arrays
-become TOML arrays, maps become inline tables, and arrays of maps become arrays
-of inline tables. Keys are ordered alphabetically, so equivalent input produces
+Strings and booleans retain their TOML types, and numeric values remain TOML
+numbers. Helm normalizes YAML numbers before templates run, so it cannot retain
+the lexical distinction between an integral float such as `1.0` and an integer
+such as `1`; both render as the compact TOML value `1`. Scalar arrays become
+TOML arrays, maps become inline tables, and arrays of maps inside a table become
+arrays of inline tables. A top-level `gatewayConfig` list instead renders an
+ordered TOML array of tables: each list item must be a map and emits one
+`[[table]]` block. Keys are ordered alphabetically within each table, while
+array-of-tables item order follows the YAML list, so equivalent input produces
 the same ConfigMap checksum. Helm `tpl` expressions are evaluated only in
 string values, never in keys or YAML structure.
 

docs/kubernetes/migrate-gateway-config.mdx

@@ -2,7 +2,8 @@
 
 Chart schema v2 replaces application-specific Helm values with one non-secret
 `gatewayConfig` map. Its top-level keys are TOML tables; nested maps are TOML
-inline tables. Kubernetes resource references (Secrets, certificates, Services,
+inline tables. A top-level YAML list is an ordered TOML array of tables, with
+one map per `[[table]]` entry. Kubernetes resource references (Secrets, certificates, Services,
 and mounts) remain chart values.
 
 ## Upgrade compatibility