Gateway API integration

Gateway API is the recommended edge model for explicit route ownership, listener mode, and cross-namespace attachment. For most production deployments, start with TLS passthrough so OpenBao remains the TLS endpoint.

Use the Gateway API Standard channel

The operator emits Gateway API v1 resources for HTTPRoute, TLSRoute, and BackendTLSPolicy. Install a Gateway API Standard bundle that serves those versions, such as Gateway API v1.5.1 or newer. Treat the experimental bundle as a reference-only deviation for clusters that intentionally depend on experimental Gateway API resources outside the operator-managed surface.

Decision matrix

Choose the Gateway mode

Choose the Gateway mode.

Mode	Use it when	What the operator creates	Watch for
TLS passthrough	You want OpenBao to remain the TLS endpoint and keep end-to-end certificate identity.	TLSRoute-based integration that forwards encrypted traffic to the cluster.	Your controller and GatewayClass need usable TLSRoute support, and ACME depends on this model.
TLS termination	You need HTTP-aware policy, WAF behavior, or centralized certificate handling at the Gateway.	HTTPRoute plus optional BackendTLSPolicy for re-encrypted traffic to OpenBao.	Be explicit about backend trust and do not assume termination alone preserves the same trust model.

Diagram

Gateway API modes

Passthrough keeps OpenBao as the TLS endpoint. Termination shifts certificate presentation to the Gateway and then re-establishes trust on the backend hop.

Recommended path: TLS passthrough

Configure

Expose OpenBao through a passthrough Gateway listener

yaml

spec:
gateway:
  enabled: true
  tlsPassthrough: true
  hostname: bao.example.com
  gatewayRef:
    name: main-gateway
    namespace: gateway-system

This is the default production recommendation because OpenBao remains the TLS endpoint. It fits the trust model used by External TLS and ACME particularly well.

Example Gateway listener for passthrough

Inspect

Gateway listener with `TLS` passthrough

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: main-gateway
namespace: gateway-system
spec:
gatewayClassName: traefik
listeners:
  - name: websecure-passthrough
    port: 443
    protocol: TLS
    tls:
      mode: Passthrough

ACME requires passthrough

If tls.mode is ACME, do not terminate TLS at the Gateway. OpenBao must remain the TLS endpoint to complete the ACME lifecycle correctly.

Alternative path: Gateway-side termination

Configure

Expose OpenBao with Gateway termination

yaml

spec:
gateway:
  enabled: true
  hostname: bao.example.com
  gatewayRef:
    name: main-gateway
    namespace: gateway-system

Use Gateway-side termination when you need HTTP-aware policy, WAF behavior, or centralized certificate handling. In that model the operator can create a BackendTLSPolicy so the backend hop stays encrypted and validated.

What the operator adds for backend TLS

When backend TLS is enabled, the operator creates a BackendTLSPolicy that pins backend validation to the cluster's CA ConfigMap and expected service hostname.

Compatibility and readiness

Reference table

What must be true

What must be true.

Check	Why it matters	What to confirm
Gateway reference exists	The operator cannot integrate with a missing or mistyped target.	The referenced Gateway object is present in the namespace you point to.
GatewayClass exists and is accepted	A route works only when the controller owning the GatewayClass is present and healthy.	The selected GatewayClass exists and reports acceptance.
Required feature support exists	Passthrough needs TLSRoute; termination may need BackendTLSPolicy support.	If the controller publishes status.supportedFeatures, verify the required features are present.
Listener mode matches the chosen path	A passthrough route attached to a terminating listener will never behave correctly.	The selected listener protocol and mode are compatible with the route type the operator is going to create.

Reference table

Conditions to watch

Conditions to watch.

Condition	What it means	Typical next move
GatewayIntegrationReady=True	The operator verified the Gateway reference, class, listener path, and available controller support well enough for the chosen mode.	Continue with end-to-end validation and client connectivity checks.
GatewayIntegrationReady=Unknown	The controller has not published enough status, or feature support cannot be verified from the available information.	Wait for more Gateway status or inspect whether the controller publishes supported features at all.
GatewayIntegrationReady=False	The operator found a concrete incompatibility or missing dependency.	Read the condition reason first: missing reference, unsupported feature, incompatible listener, or not-programmed gateway are the common cases.

Blue-green upgrades keep the route stable

During blue-green cutover, the operator keeps the Gateway route attached to the stable external Service and updates the Service selector behind it. When steady read replicas are enabled, that same external Service can fan out to both voter and read-replica Pods during normal operation, relying on OpenBao to serve reads locally and forward writes to the active leader. During blue-green cutover the selector is temporarily narrowed to the active voter revision, so the route object stays steady while the selected backend set changes underneath.

The operator does not create a second Gateway route for the dedicated read-replica Service yet. If you need an explicit read-only hostname, keep that as a separate edge concern for now.

Continue service boundary setup

Network configurationAlign trusted ingress peers and external dependency egress with the Gateway path you just chose.Read replicasReview the shared client endpoint and optional dedicated read Service before exposing the cluster through a Gateway.External accessSwitch back to the broader exposure decision page if you still need to compare Gateway with Ingress or direct Service exposure.TLS and workload identityReview the underlying TLS ownership model when deciding between passthrough and termination.