Support configuring a CA bundle for the control plane connection (GatewayProxy)

[shreemaan-abhishek]

Summary

Allow users to configure a CA bundle for the control plane connection on GatewayProxy.spec.provider.controlPlane, so that TLS certificate verification can be kept on when the control plane uses a self-signed certificate or a private/internal CA.

Background

GatewayProxy.spec.provider.controlPlane.tlsVerify controls whether the ingress controller (via the ADC executor) verifies the control plane's TLS certificate. We are moving this to a secure default (tlsVerify: true) in:

• api7-ingress-controller fix: verify control-plane TLS certificate by default #438
• apache/apisix-ingress-controller #2811 (review discussion: fix: verify control-plane TLS certificate by default apache/apisix-ingress-controller#2811 (comment))

Review feedback (AlinsRan) on that PR raised a real gap: today there are effectively only two states available to users:

1. tlsVerify: false -> no verification (insecure)
2. tlsVerify: true -> verify against the system trust store only (works only if the control plane cert chains to a publicly trusted CA)

There is no way to supply a custom CA. So for the common case of a self-signed or private-CA control plane, a user who wants verification on has no path to make it succeed. Their only escape from the resulting connection error is to set tlsVerify: false, which risks turning the insecure opt-out into copy-paste boilerplate and defeats the point of the secure default.

The missing third state is:

3. tlsVerify: true + a CA bundle -> verify against a CA the user explicitly trusts (the correct setup for self-signed / private CAs)

Problem

ControlPlaneProvider only exposes Mode, Endpoints, Service, TlsVerify, Auth:

• api/v1alpha1/gatewayproxy_types.go (ControlPlaneProvider struct) - no CA field.
• api/adc/types.go (Config struct) - only TlsVerify bool, no CA material.
• internal/adc/client/executor.go (ADCServerOpts) - only TlsSkipVerify *bool is sent to the ADC server; there is no field to pass a CA certificate.

So the gap is end to end: CRD -> translator Config -> ADC request -> adc.

Proposed solution

Add an optional CA bundle to the control plane provider, supporting either an inline PEM or a reference to a Kubernetes Secret/ConfigMap:

// CaBundle is a PEM-encoded CA certificate (or bundle) used to verify the
// control plane's TLS certificate. Takes precedence over the system trust
// store. Only relevant when tlsVerify is true.
// +optional
CaBundle string `json:"caBundle,omitempty"`

// Alternatively / additionally, a Secret/ConfigMap reference:
// CaBundleRef *SecretKeySelector `json:"caBundleRef,omitempty"`

Then thread it through:

1. CRD - add the field(s) to ControlPlaneProvider in api/v1alpha1/gatewayproxy_types.go; regenerate CRDs (config/crd/bases, config/crd-nocel/...), deepcopy, and docs.
2. Translator - resolve the CA (inline value, or read the referenced Secret/ConfigMap the same way admin-key secrets and Gateway frontendValidation caCertificateRefs are resolved - see internal/adc/translator/gatewayproxy.go and internal/adc/translator/gateway.go) and set it on the ADC Config (api/adc/types.go).
3. Executor - carry the CA into the request sent to the ADC server (internal/adc/client/executor.go, ADCServerOpts).

Open questions / dependencies

• ADC server support (blocker to confirm first). The ADC request today only carries tlsSkipVerify. Passing a CA end to end requires the adc server to accept and honor a CA bundle for the upstream Admin API connection. Confirm whether adc already supports this; if not, that side needs a companion change and this feature depends on it.
• Source shape. Decide between inline PEM, a Secret/ConfigMap ref, or supporting both. There is prior art for resolving CA cert refs from Secret/ConfigMap in internal/adc/translator/gateway.go (frontendValidation caCertificateRefs) worth reusing for consistency.
• Validation. Reject an invalid/unparseable PEM early (translator or webhook) with a clear status/condition rather than a late connection failure.
• Interaction with tlsVerify. A CA bundle only makes sense when verification is on; document precedence (explicit CA bundle overrides the system trust store) and whether supplying a CA bundle while tlsVerify: false should warn.

Acceptance criteria

• GatewayProxy can specify a CA bundle for the control plane (inline PEM and/or Secret/ConfigMap ref).
• With tlsVerify: true + a valid CA bundle, the controller connects to a control plane using a cert signed by that CA (no tlsVerify: false needed).
• Invalid CA material surfaces a clear error/condition, not a silent or opaque failure.
• CRDs, deepcopy, and API reference docs regenerated; unit test covering the translator wiring (CA resolved and set on Config).

Related

• api7-ingress-controller fix: verify control-plane TLS certificate by default #438 (tlsVerify secure default)
• apache/apisix-ingress-controller #2811 and review comment r3654031187
• The same gap exists in apache/apisix-ingress-controller; if implemented there too, the change should be synced per the two-repo sync rule.

[coderabbitai]

🔗 Related PRs

#393 - feat: validate APISIX resources in webhooks [closed]
#396 - fix: use https_verify_certificate for standalone active health checks [closed]
#424 - feat: support downstream mTLS via Gateway API frontendValidation [closed]
#437 - fix: harden SSL host/certificate consistency (conflict detector + SAN coverage) [open]
#438 - fix: verify control-plane TLS certificate by default [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[shreemaan-abhishek]

Implemented in #447 (enterprise) and apache/apisix-ingress-controller#2826 (open source), with the ADC-side dependency in api7/adc#537.

Answers to the open questions raised here:

• ADC server support — was a real blocker. adc only honors a CA on the CLI path (caCertFile); the /sync and /validate HTTP handlers that this controller uses picked between two static agents (rejectUnauthorized true/false), with a standing //TODO: dynamic rejectUnauthorized and support mTLS. feat(server): support a custom CA bundle for the backend connection adc#537 adds a caCert task option and builds a per-CA agent for it (cached per bundle so keep-alive sockets stay pooled). Until an ADC build carrying that ships, the CRD field is accepted, validated, and transmitted, but not yet acted on.
• Source shape — inline PEM. A CA certificate is public material, so a Secret buys no confidentiality, and inline is what Kubernetes uses for the same job (WebhookClientConfig.CABundle). It also avoids a new watch, index, and RBAC rule, and rotation is an edit of the GatewayProxy the controller already reconciles on. A caBundleRef can be added later without breaking the field.
• Validation — fails fast, twice. A CEL rule rejects a non-PEM caBundle at admission, and the translator parses it with x509.CertPool.AppendCertsFromPEM before anything is pushed.
• Interaction with tlsVerify. The bundle replaces the system trust store when verification is on and is ignored when it is off; that case is logged rather than silently ignored. It is still sent, so turning tlsVerify back on needs no other change.