Use Gateway API when the edge should be explicit, portable, and multi-tenant aware.

Gateway API is the preferred long-term edge model for OpenBao because it makes route ownership, listener mode, and cross-namespace attachment clearer than a generic Ingress path. For most production deployments, start with TLS passthrough so OpenBao remains the TLS endpoint.

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 termination only when you actually need Gateway-side HTTP features. 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 is only useful if the controller owning the GatewayClass is real 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. That means the route object stays steady while the selected revision changes underneath.

Continue service boundary setup

Network configurationAlign trusted ingress peers and external dependency egress with the Gateway path you just chose.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.