Validation Reference

Validation runs continuously per state as you edit. Error-severity issues block YAML download, both from the builder toolbar and from the Deploy tab; warnings never block Save or download. The builder additionally refuses to download while you have unsaved changes, because the download always renders the last saved gateway. The Deploy tab and the detail page have no unsaved-changes gate, since they only ever show saved state.

Danger

Six of the warnings below, the Cross-State Sanity Checks, are re-evaluated server-side as hard-blocking errors when you initialize or execute a gateway migration, even though they never blocked Save or Download in the builder. Unresolved placeholders anywhere in the generated CRs block a migration the same way. A gateway that saves and downloads cleanly can still be rejected at migration time for these reasons, so treat them as required fixes rather than optional advice before running a migration.

Blocking Errors

Route

• Duplicate route, streaming domain, secret store, or per-side auth name within a state.
• A route referencing a streaming domain that doesn’t exist in that state, or a bootstrap ID that isn’t on the domain the route references. The second case is checked against that domain only, so a bootstrap ID that exists elsewhere in the state still errors.
• A swap route missing a secret store, or referencing one that isn’t defined in the state.
• A swap route missing a client auth or cluster auth reference, referencing one that no longer exists, or referencing a block of the wrong side (a client auth used as cluster auth, or vice versa).
• A passthrough route that still carries auth or secret-store references, clear them, or switch the route to swap.

Streaming Domain

• Duplicate name.
• No bootstrap server configured.

External Access

• LoadBalancer missing a domain, or with an out-of-range port.
• NodePort missing a host, or missing/negative/non-integer offset.

Advanced State Configuration

• Invalid image pull policy.
• Invalid Kubernetes resource quantities (e.g. a malformed 500m or 1Gi value).
• A probe port, the admin.port, or the jvmTuning.jmxPort outside the 1-65535 range. Non-positive values are also rejected, but the Inspector clears any of those three that you set to zero or below, so in practice that case only reaches validation through a direct API write or a gateway saved by an older version.
• A JVM heapMin or heapMax that isn’t in JVM short form (e.g. 512m, 1g, 2048k).

Unresolved Placeholders Literal <...>-style tokens (e.g. <bootstrap-server>:9092) seeded by templates or fresh palette drops are flagged as errors in the fields this check covers:

• Bootstrap server endpoints and their TLS secret references.
• Route endpoints, broker hostname patterns, and listener TLS secret references.
• Auth TLS, JAAS, admin, and OAuth Bearer secret references, plus the six OAuth settings.
• Secret store config, client credentials, and certificate references, plus the Vault address and prefix.
• The external access load balancer domain and NodePort host.

$(nodeId) expansion tokens contain no angle brackets and are never flagged.

Caution

Fields outside that list are not checked here, including environment variables, the application and init container images, the admin bind address, JVM extra opts, the Vault auth token, and the AWS and Azure connection fields. The Deploy tab closes part of that gap, but not all of it, and it does so in two separate places.

Its unresolved-value banner scans the three generated CRs. A token left in an environment variable, an image, the admin bind address, or JVM extra opts is listed there, and a gateway migration is hard-blocked while any remain. JVM extra opts reach the CR as a JAVA_TOOL_OPTIONS environment variable, which is why they are caught despite not being checked in the builder.

The secret store’s own credential values are the part that stays uncovered: the Vault auth token, and the AWS and Azure connection fields, never reach a CR. They go into the Secret manifests instead, which the banner does not scan, so they appear only as the per-Secret Replace before running fill-ins inside the Deploy tab’s Secrets step, and they never block the migration. Note this is narrower than the secret store as a whole, since the Vault address and prefix path are placeholder-checked in the builder, as the list above says.

One value escapes every check. A Vault address left empty is not reported anywhere: the generated Secret silently carries https://vault.example.com, which looks like a real endpoint and is flagged only by the separate, non-blocking store-connection warning. A builder with no placeholder errors is necessary but not sufficient: check the banner, each Secret, and the Vault address before you deploy.

Host/SNI vs. Port Strategy

A route’s broker identification strategy determines what else it needs:

Strategy	Requires
Host (SNI)	A TLS secret reference on the listener, and a broker hostname pattern such as broker$(nodeId).gateway.example.com. Selecting this strategy seeds the pattern with an angle-bracket placeholder for the domain, which is an error until you replace it with your real hostname.
Port	The route’s streaming domain must have node ID ranges defined.

The toolbar’s issue badge counts every state’s issues, not just the state you are on, so it stays visible until all three states are clean. The per-state counts are the small red and amber badges on the Init, Fenced, and Switchover tabs. When no state has an issue, the badge disappears and the toolbar shows just Preview, Download, and Save, as below. That’s the state to aim for before downloading or deploying:

Non-Blocking Warnings

Secret and Auth Mapping Completeness

• A swap route’s secret store has no auth mappings: its generated Secret will contain only placeholders.
• A File store’s auth mapping has no destination key: the generated credential entry will contain a placeholder. (Vault/AWS/Azure mappings are exempt, their real mapping lives in the external store, not a generated Secret.)

Secret Store Connection Fields File stores have no connection fields of their own and are exempt. For Vault, AWS, and Azure stores, a missing connection field warns that the generated config Secret will contain a placeholder in its place:

• Vault: address, auth token.
• AWS: region; access key and secret access key (only checked once either half of the pair is set, both blank is a valid IAM-role configuration).
• Azure: Key Vault URL, tenant ID, client ID, client secret.

SCRAM Registration scram-registration-route is only needed in Init, for credential pre-registration before switchover. Leaving or moving it into Fenced or Switchover warns that it has no effect there and can be removed (keep it in Init). The check only runs on a state that also holds a client SCRAM auth block, so a registration route copied into a state without one is not flagged.

JVM Tuning A JVM jmxPort that collides with the admin port warns of a runtime bind conflict, without blocking download.

Cross-State Sanity Checks

Tip

These six checks exist specifically to catch a migration that completes but silently changes nothing. They’re warnings here in the builder, where Save and Download both stay available, but see the callout above: the same six conditions are hard-blocking errors at actual migration init and execution time.

• Fenced state has no fenced route, so producers won’t actually be blocked during the migration window.
• Switchover state still has a fenced route, so clients remain blocked after cutover completes.
• Every one of Switchover’s bootstrap endpoints already appears in Init’s, so cutover wouldn’t introduce a new endpoint. This isn’t a full-set match: it fires even if Switchover has just one endpoint, as long as that one is also in Init’s set.
• Switchover declares no destination bootstrap endpoint at all, so there is no cluster to cut over to.
• Switchover has no routes at all, so there is nothing to cut over.
• Switchover still routes to the same streaming domain as Init, so traffic never cuts over. Routes are paired by name: Switchover routes whose names don’t appear in Init are ignored, and the warning fires only when every remaining pair still points at Init’s domain. Renaming a route in Switchover takes it out of this comparison deliberately, not as an oversight: kubectl apply replaces the spec wholesale, so route names are not a mapping key between applies, and a renamed Switchover route that targets the destination and carries no fence still cuts over correctly. The endpoint check above covers a different hole, a renamed streaming domain whose bootstrap entries still hold the source addresses.