Creating a Gateway

Click + New Gateway on the Gateways dashboard tab to open the New Gateway modal.

Basic Info

Field	Required	Description
Alias	Yes	The gateway’s display name; 2 to 50 characters, letters, numbers, spaces, hyphens, and underscores only, with at least one letter or number.
Description	No	Up to 500 characters.
Tags	No	Free-form tags, shown on the gateway card.
Kubernetes Namespace	No	Defaults to confluent.

Routes, auth, and secret stores are configured in the builder after creation: this modal only sets metadata.

Starting Without a Template

Leave Start from a migration template unchecked to create a gateway with three empty states (Init, Fenced, Switchover), each holding only workload defaults (replicas, external access, probes, admin config, resources) and no routes, auth blocks, or secret stores. Build these out afterward in the Builder Workspace.

Starting From a Migration Template

Checking Start from a migration template reveals Template Options, which pre-populate all three state configs with a route, plus auth and secret-store blocks, where the selected mode requires them:

Authentication Mode

Mode	Behavior
Passthrough	Forwards client credentials to the upstream cluster unchanged. Seeds a passthrough mTLS route in all three states; no secret store is created. Adjust the source auth in the builder afterward if your clients use a different auth type.
Swap	Replaces client credentials at the gateway. Reveals Source auth, Upstream auth, and Secret store selectors.

Swap Mode Options

Source auth	Upstream auth	Secret store
mTLS	OAuth or SASL/PLAIN	File store, HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault
SASL/SCRAM	OAuth or SASL/PLAIN	Same options
SASL/PLAIN (API Key)	OAuth or SASL/PLAIN	Same options
None (unauthenticated)	OAuth or SASL/PLAIN	Same options

Note

mTLS is never offered as an upstream auth choice in Swap mode: an mTLS upstream means credentials pass through unchanged, which is what Passthrough mode is for.

Caution

Swap only applies at Switchover. Whichever source/upstream combination you pick, the seeded route stays passthrough to the source cluster in both Init and Fenced, the same as a Passthrough-mode gateway. Only the Switchover state actually swaps credentials and points at the destination cluster, where you’ll see the Source Auth, Upstream Auth, and Secret Store nodes connected to the route. This is by design: before cutover, real client credentials should reach the source untouched; the swap only needs to exist once traffic moves to a cluster with a different credential type.

Tip

Choosing SASL/SCRAM as the source auth seeds an additional scram-registration-route in the Init state, used to pre-register credentials before switchover. This route is intentionally not fenced in the Fenced state, unlike the main migration route, see Validation Reference for what happens if it’s moved.

Apply migration template is also available from inside the builder canvas, but only while all three states are still empty. It’s an empty-canvas starting point, not a way to re-seed a gateway you’ve already started configuring; once any state has content, the button no longer appears.

Result

On success, a Gateway created toast confirms the alias is ready to configure. Created from the Gateways tab, the gateway opens straight in the Builder Workspace; created from the planner’s gateway selection step, it’s added to that step’s list and selected for the plan.

A failure shows an error toast and leaves the modal open so you can retry. The most common cause is a duplicate alias, since aliases must be unique, but the toast just reads “Failed to create gateway” with no further detail, so check for a name collision first.

Note

Alias, description, tags, and namespace are set here and can’t be edited afterward. The card and detail-page Edit actions open the builder, which changes state configuration only, and Duplicate always names the copy ALIAS-copy rather than asking for a new alias. Pick the alias and namespace you want before you create the gateway.