Exposing Argo CD with Kubernetes Gateway API

Exposing Argo CD with the Kubernetes Gateway API: when teams need it

Choose the Gateway API when your platform team is moving off Ingress and needs both the Argo CD web UI and the gRPC-based CLI to stay reachable through a supported routing layer. The Kubernetes Gateway API splits what an Ingress object mixes together: a Gateway owned by the platform team handles listeners and TLS, while route objects owned by the application side attach hostnames and paths. For Argo CD, that means HTTPRoute carries the browser and API traffic, GRPCRoute carries the CLI's gRPC calls, and TLSRoute carries traffic that must pass through to Argo CD without being decrypted at the gateway. The Argo CD ingress guide documents these configurations, and it is the source to follow for the exact resource shapes and the server settings each mode needs.

The main decision is where TLS ends. With termination at the gateway, you use HTTPRoute and GRPCRoute and usually run the Argo CD API server with server.insecure so traffic between the gateway and the pod is plain. With passthrough, TLSRoute forwards encrypted traffic to the API server, which keeps the certificate on Argo CD itself and leaves the gateway unable to inspect requests. Confirm with your security team whether the gateway must see decrypted traffic for logging or inspection, and confirm that your gateway implementation supports the route kinds you need, since support for GRPCRoute and TLSRoute varies across implementations.

Keep Ingress when the cluster already runs a controller your team operates well and the Gateway API offers no new requirement, because the migration itself adds change work to the cutover. Moving to the Gateway API fits best when the platform is already standardizing on Gateway resources for other services, when you need the separation between platform-owned listeners and team-owned routes, or when Ingress controller support is being retired in your environment. Plan a parallel route for the CLI before you remove the old path, and test argocd login against the new hostname from the networks your engineers use.

TLS termination or passthrough: how to choose for Argo CD

The first question is who holds the certificate for the Argo CD hostname and how it is renewed. With TLS termination, the Gateway holds a certificate for the public name, so the platform or network team manages issuance and rotation at the edge. With TLS passthrough, the Argo CD API server presents its own certificate, so whoever manages that server must issue, mount and rotate it. Confirm which team owns each certificate and how renewal alerts reach them before choosing.

Termination ownership: The Gateway listener references a certificate Secret, so one team usually manages edge certificates for many services.
Passthrough ownership: The Argo CD server needs its own certificate, which often means cert-manager or an internal CA inside the cluster.
Trust chain: Confirm that CLI users and the UI browser trust the issuing CA, especially with internal certificate authorities.
Rotation: Test a renewal in a non-production cluster and confirm that the Argo CD server picks up the new certificate without manual steps.
Audit evidence: Record who approves certificate changes, since certificates are part of the change record for this service.

Confirm your Gateway implementation's support for TLS modes and certificate references in the Argo CD ingress guide before you commit to a design.

The Argo CD CLI uses gRPC, and the web UI uses HTTP. With TLS termination, the gateway must route gRPC traffic with a GRPCRoute (or an equivalent HTTP/2 route) to the Argo CD service, and the backend protocol must match what the server expects. With TLS passthrough, gRPC travels inside the encrypted stream, so the same TLS connection carries both UI and CLI traffic without the gateway needing to understand gRPC. Verify both paths with the CLI and the browser before you hand the setup to users.

Termination routing: Use a GRPCRoute for CLI traffic and an HTTPRoute for the UI, and confirm the backend protocol setting.
Passthrough routing: A single TLSRoute can carry both protocols, which reduces the number of routes to maintain.
Server TLS settings: Check whether the Argo CD server runs with TLS enabled or with server.insecure set, since that changes what the gateway expects on the backend.
Test commands: Run argocd login against the public hostname from a workstation and from a CI runner.
Fallback behavior: Confirm the CLI's grpc-web fallback behavior if your network blocks HTTP/2.

Check the gRPC section of the ingress guide for the exact settings your Argo CD version expects.

Gateway API route types and when each fits Argo CD

This table compares HTTPRoute, GRPCRoute and TLSRoute by the traffic each carries, the TLS mode it pairs with and the conditions where it fits Argo CD. Read each row against how you plan to serve the web UI and the gRPC CLI, then confirm that your Gateway controller supports the route type you choose.

Route type	Traffic it carries	TLS mode it pairs with	When it fits Argo CD
HTTPRoute	Argo CD web UI and REST API over HTTP or HTTPS	TLS termination at the Gateway, with server.insecure set on Argo CD	Browser access on a single hostname where the gateway can hold the certificate and the CLI is served through a separate route or path
GRPCRoute	gRPC traffic from the argocd CLI and API clients, matched by service or method	TLS termination at the Gateway, with the gRPC backend reached over cleartext inside the cluster	Separate CLI hostname or match rule when the gateway must route gRPC explicitly instead of relying on the CLI's grpc-web fallback
TLSRoute	Encrypted TLS streams forwarded by SNI without the gateway reading the HTTP content	TLS passthrough, so Argo CD's own server terminates TLS	Keeping Argo CD's certificate inside the cluster and serving web and gRPC on one hostname, when your controller supports passthrough
Controller support	Varies by Gateway API implementation and version	Confirm which route kinds and TLS modes your controller implements	Check your controller's conformance and release notes before choosing a route type, since support differs between implementations

Building the Gateway API route for Argo CD step by step

This sequence takes a cluster from an existing Argo CD install to a published UI and CLI endpoint through Gateway API resources, with each step closing on a check you can run. It is written for platform engineers who must choose a TLS mode first and then make the Argo CD settings, Gateway, routes, DNS and certificates agree with it.

Confirm controller and Gateway API versions
The platform engineer checks which Gateway API CRD version and which Gateway controller your cluster runs, and confirms that the controller supports the HTTPRoute, GRPCRoute and TLSRoute kinds you plan to use. Compare the installed CRDs against the Gateway API and controller release notes, and confirm the Argo CD version you run with the Argo CD ingress guide's Gateway API examples. Done when kubectl get crd lists the Gateway API kinds at a version your controller documents as supported, and the controller reports Ready. Record the versions in your change ticket, because upgrades of either component can change which fields and route types are accepted.
Decide the TLS mode before configuring anything
Choose between TLS termination at the Gateway and TLS passthrough to the Argo CD server. Termination lets the Gateway present your certificate and route on HTTP and gRPC attributes, which requires Argo CD to serve plain HTTP internally with server.insecure. Passthrough keeps Argo CD's own TLS and uses a TLSRoute, which means the Gateway cannot inspect or route gRPC by method. The security team and the platform owner should sign this decision off, since it determines who holds the private key and whether traffic is inspected inside the cluster. Done when the mode and its reason are written down and the team agrees on which hostnames will be used.
Set Argo CD server settings for the chosen mode
The platform engineer edits the argocd-cmd-params-cm ConfigMap for the chosen mode. For termination, set server.insecure to true so the API server accepts plain traffic from the Gateway, and confirm that internal component TLS settings still match your policy. For passthrough, leave the server's TLS in place and make sure no insecure flag is set. Then restart the argocd-server deployment so the setting takes effect. Done when kubectl get configmap argocd-cmd-params-cm -n argocd -o yaml shows the intended value and the argocd-server pods have rolled out. Note that a wrong setting here often shows up later as an HTTP 400 or a redirect loop, so verify it before moving on.
Create the Gateway and its listeners
Create a Gateway resource in a namespace that your GatewayClass allows. In termination mode, add an HTTPS listener with the hostname, a certificate reference to a Secret, and an allowedRoutes policy that limits attachment to the Argo CD namespace or a labeled set of namespaces. In passthrough mode, add a TLS listener with Passthrough mode and the same hostname. Keep one listener per hostname so that status conditions are easy to read. Done when the Gateway shows Accepted and Programmed conditions True and the controller reports an address, which you can read with kubectl describe gateway.
Create routes for the UI and the gRPC CLI
In termination mode, create an HTTPRoute for the web UI and API, and a GRPCRoute that matches the gRPC service calls the argocd CLI makes, both attached to the same Gateway listener. In passthrough mode, create a single TLSRoute that forwards the hostname to the argocd-server Service, because the Gateway cannot split gRPC from HTTP. Confirm the backend Service name and port against the installed manifests. Done when both routes show Accepted and ResolvedRefs conditions True and the backend Service has endpoints, which you can check with kubectl get endpoints argocd-server -n argocd.
Set DNS and provision certificates
Create a DNS record for the Argo CD hostname that points to the address the Gateway reports, using the DNS team's normal change process. In termination mode, issue the certificate for that hostname in your certificate authority or cert manager, store it in the Secret the listener references, and confirm the chain is complete. In passthrough mode, the certificate is served by Argo CD, so confirm its subject names include the hostname. Done when the record resolves from the networks that need access and the certificate presented on the hostname matches the expected subject and issuer.
Verify CLI login and UI access
Test the web UI in a browser from an approved network, then sign in with your configured SSO or local account. Run argocd login against the hostname with the flags your TLS mode requires, and then run argocd version and argocd app list to confirm that gRPC calls succeed through the route. If the UI loads but the CLI fails, check the GRPCRoute match and the TLS mode before changing DNS. Done when the browser shows the Argo CD login page and an authenticated CLI command returns results. Record the successful test in the runbook so that later upgrades of the Gateway controller can be checked against the same commands.

Security controls for an internet or internal Argo CD endpoint

Publishing Argo CD through a Gateway API route puts the API server and UI on a network path you have to defend. The controls below cover how Argo CD authenticates requests, protects traffic between its components, handles credentials, and retires the built-in admin account. Each one should be checked on the live route, not only in the manifests.

JWT-only API authentication

Argo CD accepts API requests only with JSON Web Tokens, so the route does not need to pass along any other credential type for the API to be reached. Check that your gateway does not add a separate basic-auth or header-based login in front of Argo CD that could become a second, weaker path in. Confirm which token types your CLI and automation use, and confirm that tokens are issued only through the login flow you have approved.

TLS between Argo CD components

Argo CD uses TLS for traffic between its own components, not only at the edge. Termination at the Gateway is therefore a choice about where the outer connection ends, not a choice about whether internal traffic is encrypted. Document where TLS ends for the UI, for gRPC CLI traffic, and for each hop the route creates, and confirm the certificate chain your CLI clients trust.

Credential redaction in responses and logs

Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs. Verify this on your own installation by requesting an application and its repository details through the route and searching gateway and controller logs for known test secrets. Gateway access logs can still record URLs, headers and query strings, so review what your gateway logs and keep sensitive values out of it.

Disable the admin user after SSO

The user management guidance recommends using the built-in admin user only for initial setup. Once local users or SSO are configured and tested, set admin.enabled to false in the argocd-cm ConfigMap. Keep a documented break-glass procedure for restoring access, and confirm that an SSO administrator can sign in through the published hostname before you disable the account.

Limiting who reaches the gateway

A published route is reachable by everyone who can route to its address unless you restrict it. Decide whether the hostname should resolve on the internet, only on an internal network, or only from named source ranges, and enforce that at the load balancer, network policy or gateway listener. Confirm that the Argo CD API server cannot be reached through any other Service, port-forward path or additional route you did not intend to expose.

Untrusted repository content

The repo-server runs Helm and Kustomize on repository content, so a repository that a user can change can influence what runs inside Argo CD. Access to the endpoint is only one control. Restrict which repositories are registered and who can change them, and review the security documentation before you allow projects to pull from external sources.

Questions teams ask before exposing Argo CD through Gateway API

What drives the effort and cost of exposing Argo CD through Gateway API?

The main drivers are how many hostnames and protocols you must publish, where TLS ends, and how much of the gateway platform already exists in your cluster. A single hostname with passthrough is a small change, while separate web and gRPC routes with termination, certificate automation and per-environment DNS take more design and testing. Costs have two parts: one-time design, build and cutover work, and recurring effort to upgrade the gateway controller and Argo CD routes together. Ask any quote to list the hostnames, TLS mode, controller, number of clusters and the verification steps included.

How long does a Gateway API cutover for Argo CD usually take?

Duration depends on the state of your gateway platform and the change window your organization requires, not on Argo CD alone. Teams with a Gateway controller already running in production usually spend most of the time on DNS, certificates and testing the CLI login path. Teams that still need to install a controller, define GatewayClass and Gateway resources, or agree on a TLS policy should expect design time first. No duration is fixed here. Ask for a timeline in the written scope, with the dependencies you must provide and the rollback steps.

What must our team provide before the engagement starts?

You need to supply access and information that only your organization holds. The usual items are:

Admin access to the target cluster and the namespace where Argo CD runs
Ownership of the DNS zone and the hostnames for the UI and CLI
A certificate source, such as an internal CA or a managed issuer, and rights to renew certificates
The name and version of the Gateway API controller you run, or your choice of controller
A change window and a named approver for the cutover

Confirm each item with your platform and security teams before work starts.

Can our platform team do this in-house?

Yes, if your team already runs Kubernetes, understands Gateway API resources and can test gRPC over HTTP/2. Most in-house work fails at the CLI path rather than the web UI, so confirm that someone can test argocd login against the new route. A partner is useful when the design must be agreed with security, when several clusters need the same pattern, or when staff are short. Compare the internal hours and skills needed against a written, fixed scope, and check whether your controller supports the routes you need before deciding.

How does the choice between TLS termination and passthrough change the work?

With TLS passthrough, the TLSRoute forwards encrypted traffic to Argo CD, so Argo CD must keep its own TLS certificate and the gateway never reads the request. With TLS termination, the gateway holds the certificate and routes plain traffic to Argo CD, which usually needs server.insecure set so the backend does not expect TLS. Termination adds certificate lifecycle work at the gateway and HTTPRoute and GRPCRoute rules for each protocol. Passthrough means fewer moving parts but less control at the edge. The Argo CD ingress guide describes both patterns, and your security team should choose one before design starts.

What breaks most often after moving Argo CD to Gateway API?

The most common failures are the CLI and the web UI disagreeing about protocol. The argocd CLI uses gRPC, so a route that serves only HTTP/1.1 can break argocd login while the browser still works. Other frequent problems are certificate names that do not match the hostname, DNS records left pointing at the old Ingress, and a backend port or protocol annotation that the controller does not honor. Test login, sync, logs and the UI from a client network before cutover, and keep the previous route ready until those checks pass.

Should we keep our existing Ingress running during the move?

Usually yes, for a short overlap. Running the old Ingress and the new Gateway route side by side lets you move DNS in a controlled step and roll back without rebuilding anything. Confirm that the two paths do not compete for the same hostname in a way your DNS or load balancer cannot handle. Remove the Ingress only after the new path has passed login, sync and log checks and your change owner has signed off. Note that the ingress-nginx project is deprecated, so plan its retirement as part of the same change record.

Does DeployOpen certify that our Argo CD exposure meets our compliance requirements?

No. DeployOpen plans and implements the Gateway configuration, documents the TLS mode, routes, access paths and verification results, and prepares the evidence your assessor will ask for. Independent auditors and certification bodies decide whether controls meet a standard. Ask your assessor early which evidence they expect for network exposure, TLS and change records, so the design captures it from the start.

What to confirm in your cluster before choosing Gateway API

Before you write a single HTTPRoute, confirm what your gateway controller actually supports for Argo CD's traffic. The Gateway API defines several route kinds, but controllers differ in which ones they implement and in how they handle the pieces Argo CD depends on. Ask the controller vendor whether HTTPRoute, GRPCRoute and TLSRoute are supported at the API version your cluster runs, whether the controller can terminate TLS and also pass it through on the same listener, and how it treats backend protocols. The Argo CD ingress guide documents the Gateway API configurations the project has in mind, so compare the controller's behavior with that guide rather than with general Gateway API examples.

Next, confirm the points that break the CLI first. The argocd CLI speaks gRPC, so you need to know whether your controller forwards HTTP/2 end to end to the Argo CD server, how it negotiates the protocol with the backend, and whether it accepts the gRPC-web fallback path if your users sit behind proxies that block HTTP/2. Also confirm who manages certificates: whether the controller reads certificates from a Kubernetes Secret you provide, integrates with your certificate manager, and renews them without a restart. Decide early whether the Argo CD server runs with TLS enabled or with server.insecure behind a terminating gateway, because the controller's behavior has to match that choice.

Finally, pin the Argo CD version you will run and check the gateway behavior against that release line, not against the latest tag. The release process ships a minor version four times a year and only patches the three most recent minor versions, so a configuration that works on one line may need adjustment on another. Confirm the Argo CD version against the Argo CD release process and cadence page, then test the chosen routes on a non-production cluster at that exact version. Record the controller version, the Argo CD version and the route manifests together, because the next upgrade will need to repeat these checks.

Limits and open questions for Gateway API publishing

Gateway API publishing for Argo CD depends on the controller you choose, the network design of your cluster and how often your team upgrades. The cards below list six points to confirm before a route goes live, from feature support and IPv6 limits to CLI login after each upgrade. Each item is a check to run in your own environment, not a guarantee.

Controller feature gaps

Not every Gateway API implementation supports HTTPRoute, GRPCRoute and TLSRoute to the depth the Argo CD ingress guide describes. Before you commit, confirm each route kind your design needs in the controller's documentation. Check that the controller can forward to the argocd-server service over the protocol Argo CD expects, and list which routing features are included. Record every gap and decide whether it blocks TLS passthrough or the gRPC path.

IPv6-only clusters

The Argo CD high availability documentation states that IPv6-only clusters are not supported for HA manifests. Those manifests also need at least three nodes because of pod anti-affinity rules. If your gateway design assumes an IPv6-only network, settle the HA topology before building any route. Confirm the cluster's IP stack with your platform team, and verify that the gateway controller's addresses and service endpoints are reachable over the protocol your cluster runs.

GRPCRoute behavior varies by controller

The CLI sends gRPC traffic, so the GRPCRoute must reach argocd-server with the HTTP/2 behavior it expects. Controllers differ in how they handle HTTP/2 to backends, whether backend TLS is re-encrypted, and whether a gRPC route can share a hostname with the web UI. Test the exact controller version you plan to run, including an argocd login from a workstation outside the cluster. Document the controller version that passed, so the result can be repeated later.

Re-test CLI login after upgrades

Argo CD and gateway controllers both change between releases. Argo CD ships a minor release about every three months, and the project patches only the three most recent minor versions, so upgrades arrive regularly. The 2.14 to 3.0 notes changed logs access to require an explicit logs, get permission, which shows that access rules move between versions. Run a login, a sync and a log view from the CLI and UI after every upgrade.

Gateway API version support

Gateway API resources are versioned Kubernetes CRDs, and each controller supports a specific set of versions. Confirm which Gateway API version your controller installs, and whether the route kinds you use are available in the channel you plan to run. Without a named owner for CRD changes, a cluster upgrade can remove or alter routes that worked before. Assign who owns CRD upgrades and ask the vendor for its upgrade notes for each supported version.

Certificate ownership under passthrough

With TLS passthrough, the gateway forwards encrypted traffic, so Argo CD's own certificate must match the hostname clients use. With termination, the gateway holds the certificate and the hop to the backend needs its own trust decision. Confirm who issues, rotates and monitors each certificate, and whether your security team accepts the backend hop when TLS ends at the gateway. Argo CD uses TLS between its own components, so verify the chain end to end before go-live.

Operating the Gateway API endpoint after cutover

Once Argo CD is reachable through HTTPRoute and GRPCRoute, the endpoint becomes a production dependency that needs its own monitoring, change control and rollback path. Start by watching the objects that carry traffic: the Gateway, each HTTPRoute and GRPCRoute, and the TLS certificate referenced by the listener. Confirm that the controller reports each route as accepted and attached to the intended Gateway, and alert on certificate expiry well before it occurs. Check the gRPC path separately from the web UI with argocd login from a workstation and a CI runner, because a route can serve the UI correctly while the CLI's gRPC traffic fails. Confirm with your Gateway API implementation which status conditions it exposes and how it reports listener or certificate errors, since those details vary by controller.

Upgrades need one combined test, not two separate ones. Argo CD minor releases ship on a regular cadence and only the three most recent minor versions receive patch releases, so plan to move Argo CD and your Gateway API controller in the same change window, and rehearse that pairing in a non-production cluster first. Test the web login, the CLI login, a sync that exercises the gRPC API, and TLS behavior under your chosen mode (termination or passthrough). Read the official upgrade notes for each Argo CD minor version before you rehearse, and check that the Gateway API CRD versions your controller expects still match what the cluster serves after the controller upgrade.

Keep a rollback path to the previous Ingress until the Gateway endpoint has run cleanly through at least one full change cycle. Keep the old Ingress object and its ingress controller in place, and document the DNS or load balancer change that switches traffic back, with its owner and the time it takes to propagate in your environment. Store all route manifests, Gateway definitions, certificate references and the argocd-cmd-params-cm settings they depend on in Git, and manage them through a reviewed pull request. Changes then have an author, a reviewer and a revert, and a rollback is a Git revert plus a sync rather than an undocumented edit on the cluster.

How DeployOpen works on this

DeployOpen plans and implements Argo CD publishing inside your own clusters, starting with a written scope that fixes the hostnames, TLS termination point and routes for the UI and CLI. The work is delivered as a fixed-scope engagement with tested routes, documentation and a handover your team can operate.

How we scope

Confirm which Kubernetes Gateway implementation and controller your clusters already run or plan to run
Decide whether TLS ends at the gateway or passes through to Argo CD, and record the reasoning
Agree hostnames, routes for web and gRPC traffic, and the Argo CD settings that change with them
Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts

How we build

Write HTTPRoute, GRPCRoute or TLSRoute manifests that match the agreed termination model
Configure Argo CD's server settings and certificates to match the chosen TLS path
Test the web UI and the argocd CLI login and sync paths against the published hostname
Keep manifests in Git so changes to routing go through the same review as application changes

How we hand over

Deliver the manifests, configuration and a runbook describing each route and certificate
Document the verification steps your team can repeat after upgrades or gateway changes
Walk your engineers through the routing model, including where CLI traffic is handled
Record open items, such as gateway features to confirm with your vendor, in the handover pack

How we support

Ongoing support, upgrades and continuous testing are available as retainers
Review routing and TLS settings when Argo CD minor releases or gateway controller versions change
Confirm that CLI and UI access still works after each planned change, using a written test list
Scope retainer work separately from the original build so responsibilities stay clear

Exposing Argo CD with the Kubernetes Gateway API