fix(gateway): decouple outbound CA trust store from tls.enabled; add README examples

charts/gateway/Chart.yaml

@@ -16,7 +16,7 @@ type: application
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
 # major.minor mirrors the API7 EE release line (3.10.x), patch is this chart's
 # own counter on that line and is decoupled from the app patch (see appVersion).
-version: 3.10.8
+version: 3.10.9
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to

charts/gateway/README.md

@@ -30,6 +30,85 @@ helm delete [RELEASE_NAME] --namespace api7
 
 The command removes all the Kubernetes components associated with the chart and deletes the release.
 
+## Configuration examples
+
+The full list of values is in the [Parameters](#parameters) table below. The snippets here cover a
+few common setups — put them in a `values.yaml` and pass it with `-f values.yaml`, or translate each
+line into a `--set key=value` flag.
+
+### Trust additional CA certificates for outbound TLS
+
+The gateway verifies the TLS certificate of any external service it dials (for example an
+`openid-connect` identity provider) against its outbound trust store, which is the system CA bundle
+plus `gateway.tls.existingCASecret`. In a Control Plane-managed deployment `existingCASecret` already
+carries the Control Plane CA, so use `gateway.tls.additionalTrustedCAs` to trust an extra private or
+enterprise CA **on top of** it, without modifying that Secret.
+
+Create a Secret that holds the CA certificate:
+
+```sh
+kubectl -n api7 create secret generic keycloak-ca --from-file=keycloak-ca.crt=./keycloak-ca.crt
+```
+
+Reference it (each entry mounts `filename` from `secretName` and appends it to the trust store):
+
+```yaml
+gateway:
+  tls:
+    additionalTrustedCAs:
+      - secretName: keycloak-ca
+        filename: keycloak-ca.crt
+```
+
+The rendered `ssl_trusted_certificate` becomes `system,<existingCASecret CA>,<additional CA>`, so the
+system CAs and the existing CA are preserved. The trust store is merged when the gateway starts, so
+restart the gateway Pods after adding an entry or changing the Secret contents:
+
+```sh
+kubectl -n api7 rollout restart deploy/[RELEASE_NAME]
+```
+
+### Expose the gateway through a LoadBalancer
+
+`gateway.type` defaults to `NodePort`. To publish the proxy through a cloud load balancer instead:
+
+```yaml
+gateway:
+  type: LoadBalancer
+  http:
+    servicePort: 80
+  tls:
+    servicePort: 443
+```
+
+### Set replicas and resource limits
+
+```yaml
+apisix:
+  replicaCount: 3
+  resources:
+    requests:
+      cpu: 500m
+      memory: 512Mi
+    limits:
+      cpu: "2"
+      memory: 2Gi
+```
+
+### Inject extra environment variables
+
+```yaml
+apisix:
+  extraEnvVars:
+    - name: MY_ENV
+      value: "my-value"
+    - name: TOKEN_ENV
+      valueFrom:
+        secretKeyRef:
+          name: my-secret
+          key: token
+```
+
 ## Parameters
 
 ## Values

charts/gateway/README.md.gotmpl

@@ -31,6 +31,86 @@ helm delete [RELEASE_NAME] --namespace api7
 The command removes all the Kubernetes components associated with the chart and deletes the release.
 
 
+## Configuration examples
+
+The full list of values is in the [Parameters](#parameters) table below. The snippets here cover a
+few common setups — put them in a `values.yaml` and pass it with `-f values.yaml`, or translate each
+line into a `--set key=value` flag.
+
+### Trust additional CA certificates for outbound TLS
+
+The gateway verifies the TLS certificate of any external service it dials (for example an
+`openid-connect` identity provider) against its outbound trust store, which is the system CA bundle
+plus `gateway.tls.existingCASecret`. In a Control Plane-managed deployment `existingCASecret` already
+carries the Control Plane CA, so use `gateway.tls.additionalTrustedCAs` to trust an extra private or
+enterprise CA **on top of** it, without modifying that Secret.
+
+Create a Secret that holds the CA certificate:
+
+```sh
+kubectl -n api7 create secret generic keycloak-ca --from-file=keycloak-ca.crt=./keycloak-ca.crt
+```
+
+Reference it (each entry mounts `filename` from `secretName` and appends it to the trust store):
+
+```yaml
+gateway:
+  tls:
+    additionalTrustedCAs:
+      - secretName: keycloak-ca
+        filename: keycloak-ca.crt
+```
+
+The rendered `ssl_trusted_certificate` becomes `system,<existingCASecret CA>,<additional CA>`, so the
+system CAs and the existing CA are preserved. The trust store is merged when the gateway starts, so
+restart the gateway Pods after adding an entry or changing the Secret contents:
+
+```sh
+kubectl -n api7 rollout restart deploy/[RELEASE_NAME]
+```
+
+### Expose the gateway through a LoadBalancer
+
+`gateway.type` defaults to `NodePort`. To publish the proxy through a cloud load balancer instead:
+
+```yaml
+gateway:
+  type: LoadBalancer
+  http:
+    servicePort: 80
+  tls:
+    servicePort: 443
+```
+
+### Set replicas and resource limits
+
+```yaml
+apisix:
+  replicaCount: 3
+  resources:
+    requests:
+      cpu: 500m
+      memory: 512Mi
+    limits:
+      cpu: "2"
+      memory: 2Gi
+```
+
+### Inject extra environment variables
+
+```yaml
+apisix:
+  extraEnvVars:
+    - name: MY_ENV
+      value: "my-value"
+    - name: TOKEN_ENV
+      valueFrom:
+        secretKeyRef:
+          name: my-secret
+          key: token
+```
+
+
 ## Parameters
 
 {{ template "chart.valuesSection" . }}

charts/gateway/templates/_helpers.tpl

@@ -199,14 +199,15 @@ Output: JSON {"entries": [{"port": 9200, "nodePort": ""}, ...]}
 
 {{/*
 Build the value of `apisix.ssl.ssl_trusted_certificate` — the gateway's outbound
-trust store. Starts from the system CA bundle (`system`), then appends the
-Control Plane CA (gateway.tls.existingCASecret) and every entry in
-gateway.tls.additionalTrustedCAs, matching the mount paths rendered in _pod.tpl.
-Returns an empty string when TLS is disabled or no CA is configured, so the
-caller can omit the key entirely.
+trust store, used to verify external services the gateway dials (etcd/Control
+Plane, openid-connect, loggers, ...). It is independent of the inbound HTTPS
+listener (gateway.tls.enabled). Starts from the system CA bundle (`system`),
+then appends the Control Plane CA (gateway.tls.existingCASecret) and every entry
+in gateway.tls.additionalTrustedCAs, matching the mount paths rendered in
+_pod.tpl. Returns an empty string when no CA is configured, so the caller can
+omit the key entirely.
 */}}
 {{- define "gateway.sslTrustedCertificate" -}}
-{{- if .Values.gateway.tls.enabled -}}
 {{- $paths := list -}}
 {{- if .Values.gateway.tls.existingCASecret -}}
 {{- $paths = append $paths (printf "/usr/local/apisix/conf/ssl/%s" .Values.gateway.tls.certCAFilename) -}}
@@ -218,4 +219,3 @@ caller can omit the key entirely.
 {{- printf "system,%s" (join "," $paths) -}}
 {{- end -}}
 {{- end -}}
-{{- end -}}

charts/gateway/templates/_pod.tpl

@@ -184,18 +184,16 @@ spec:
         - mountPath: /usr/local/apisix/conf/config.yaml
           name: apisix-config
           subPath: config.yaml
-      {{- if and .Values.gateway.tls.enabled .Values.gateway.tls.existingCASecret }}
+      {{- if .Values.gateway.tls.existingCASecret }}
         - mountPath: /usr/local/apisix/conf/ssl/{{ .Values.gateway.tls.certCAFilename }}
           name: ssl
           subPath: {{ .Values.gateway.tls.certCAFilename }}
       {{- end }}
-      {{- if .Values.gateway.tls.enabled }}
       {{- range $i, $ca := .Values.gateway.tls.additionalTrustedCAs }}
         - mountPath: /usr/local/apisix/conf/ssl/additional-ca-{{ $i }}
           name: additional-ca-{{ $i }}
           readOnly: true
       {{- end }}
-      {{- end }}
 
       {{- if .Values.etcd.auth.tls.enabled }}
         - mountPath: /etcd-ssl
@@ -298,12 +296,11 @@ spec:
     - configMap:
         name: {{ include "apisix.fullname" . }}
       name: apisix-config
-    {{- if and .Values.gateway.tls.enabled .Values.gateway.tls.existingCASecret }}
+    {{- if .Values.gateway.tls.existingCASecret }}
     - secret:
         secretName: {{ .Values.gateway.tls.existingCASecret | quote }}
       name: ssl
     {{- end }}
-    {{- if .Values.gateway.tls.enabled }}
     {{- range $i, $ca := .Values.gateway.tls.additionalTrustedCAs }}
     - secret:
         secretName: {{ $ca.secretName | quote }}
@@ -312,7 +309,6 @@ spec:
             path: {{ $ca.filename | quote }}
       name: additional-ca-{{ $i }}
     {{- end }}
-    {{- end }}
     {{- if .Values.etcd.auth.tls.enabled }}
     - secret:
         secretName: {{ .Values.etcd.auth.tls.existingSecret | quote }}