Serving Argo CD under a subpath with Istio

Serving Argo CD under a subpath with Istio: when teams need it

If your platform team already runs Istio and wants Argo CD on a shared hostname under a path such as /argocd, you need matching settings in three places: the Istio Gateway, the VirtualService that routes to Argo CD, and the Argo CD server itself. The Gateway accepts the hostname and listens for traffic, the VirtualService matches the prefix and rewrites it, and Argo CD must know it is being served from that prefix so the pages, redirects and API calls it generates point to the right URLs. Missing any one of these produces a UI that loads but breaks on login, asset requests or redirects, which is a common reason teams abandon the path-based design.

The Argo CD ingress guide documents Istio Gateway and VirtualService setups for a subpath such as /argocd. The server side uses --rootpath and/or --basehref: --rootpath tells the API server which prefix it sits under, and --basehref sets the base path the web UI uses for its assets. The CLI needs a separate setting, --grpc-web-root-path, because it reaches Argo CD over gRPC-web and must send requests under the same prefix. Subpath hosting differs from a root-hostname publish because every path the browser or CLI builds must carry the prefix, and rewrite rules at the proxy must strip it without breaking Argo CD's own routing. Confirm the exact flag combination against the guide for your Argo CD release before you configure it, since the flags are set on the server deployment.

DeployOpen plans the routing design, implements the Gateway, VirtualService and Argo CD settings in your own cluster, and verifies the result: UI login, asset loading, the CLI over gRPC-web, and behavior when the prefix is changed or a certificate is renewed. Before the build starts, confirm with your network and platform owners whether the hostname is shared with other services, where TLS terminates, and whether other tools on the same gateway already use the /argocd prefix, since path collisions are easier to avoid at design time.

What breaks when Argo CD moves under a path

Serving Argo CD under a prefix changes how the browser, the CLI and the gateway each build addresses. The five points below are where subpath setups most often fail, and each one maps to a setting or check described in the ingress guide.

UI assets and redirects

The web UI loads scripts, styles and redirects using paths that the browser resolves from the site root unless Argo CD knows it sits under a prefix. Without that knowledge, asset requests can land outside /argocd and the page can load incompletely. Set basehref and/or rootpath as the ingress guide describes for subpath setups, then open the UI at /argocd and confirm that every asset request carries the prefix.

Login callbacks on the wrong path

Single sign-on sends users to an identity provider and then back to a callback URL. If the external URL Argo CD uses omits the prefix, the return trip can miss the route and the login fails after the password step. Confirm which setting the ingress guide ties to the external address, register the full subpath callback with your identity provider, and test a sign-in from a fresh browser session.

CLI gRPC calls miss the prefix

The argocd CLI talks to the API server over gRPC, a path the browser UI does not use. A route that forwards only web traffic leaves CLI calls on the wrong path, so login and application commands fail while the UI still works. Set --grpc-web-root-path to the same prefix as the route, then run a CLI login against the public hostname and path.

Rewrites that strip or keep the prefix

An Istio VirtualService can remove the prefix before forwarding or pass it through unchanged. Argo CD must be configured for the behavior the route actually produces, so the rootpath setting has to match the rewrite. A mismatch can work for one path and fail for another. Write the match, the rewrite and the Argo CD settings in one change, and review them together in a single Git commit.

Verification covers only the homepage

Teams often confirm that the homepage loads and stop there. A subpath change touches static assets, redirects, SSO callbacks and gRPC calls, and each can fail on its own. Build a short test list before cutover: UI load, asset load, SSO login, CLI login and one application sync. Keep the list in your change record so the next gateway change or upgrade repeats the same checks.

Which subpath settings fit which publish pattern

This table compares the three Argo CD settings that control a subpath, plus the Istio rewrite choice, and shows what each one changes. Read each row against the pattern you plan to publish, then confirm the exact behavior in the Argo CD version you deploy, because the ingress guide is the reference for how these settings combine.

Setting or choice	What it controls	When it applies	What to confirm in your Argo CD version
rootpath	The path prefix Argo CD expects in incoming requests and uses when generating its own links	The UI is served under a subpath such as /argocd and the gateway forwards the prefix to Argo CD	Confirm the exact value your version expects and whether the gateway keeps or strips the prefix
basehref	The base URL the web UI uses for its static assets and client-side routes	The browser loads the UI under a subpath and asset or route links break without it	Confirm it matches rootpath and that the UI loads from the browser after login
grpc-web-root-path	The path prefix the argocd CLI adds when it talks to the API over gRPC-web	Engineers log in with the CLI through the same subpath used by the browser	Confirm the CLI flag value on a test login from a workstation outside the cluster
Istio rewrite: strip prefix	Removes the subpath before the request reaches the Argo CD server	Argo CD runs with its own root path and does not need to see the prefix	Confirm which of rootpath or basehref you still need, since the prefix is no longer in the request
Istio rewrite: keep prefix	Passes the full path, including the subpath, to the Argo CD server unchanged	Argo CD is configured to expect the prefix in every request	Confirm the rootpath value matches the prefix exactly, including the leading slash
Gateway and VirtualService match	Which host and path prefix the Istio Gateway accepts and routes to Argo CD	Argo CD shares a host with other services under different paths	Confirm the match and routing rules do not catch other applications on the same host
TLS at the gateway	Where TLS ends for browser and CLI traffic	The gateway terminates TLS and forwards to Argo CD over the cluster network	Confirm how the server runs with TLS on, and that the CLI trusts the certificate chain
Verification after change	Confirms that UI, assets, login and CLI all work under the subpath	Every time the subpath, Argo CD version or gateway configuration changes	Confirm the test steps your team runs, including a CLI login and an application sync under the subpath

Setting up the Istio Gateway and VirtualService for /argocd

This sequence takes Argo CD from a working in-cluster install to a UI and CLI reachable under /argocd through an Istio Gateway and VirtualService, with each access path checked before you move on. The result is one subpath entry point that the browser, the SSO callback and the CLI all use consistently.

Confirm install method and Argo CD version
Record how Argo CD was installed (plain manifests, Kustomize, or the Helm chart) and the exact version running in the cluster, then check that version against the upgrade and release notes before changing anything. Also confirm which Istio version and gateway deployment mode your cluster uses, because the Gateway selector labels and TLS secret location depend on them. You are done when you can state the Argo CD version, the install method, and the namespace and labels of the Istio ingress gateway pods. Ask your platform team to confirm these, since the ingress guide sets the subpath flags but does not replace your own environment details.
Set rootpath and basehref in server configuration
Update the Argo CD API server configuration so it knows it is served under /argocd. Set the server's rootpath to /argocd and the basehref to /argocd, using the settings the ingress guide documents for subpath deployments (the flags are set through the argocd-server deployment arguments or the argocd-cmd-params-cm ConfigMap, depending on your install method). Restart the API server and confirm the pod rolls out cleanly. The check is that the server logs show the configured root path on startup and that a direct port-forward to the server still responds, which confirms the change did not break the internal service.
Define the Gateway and TLS secret
Create an Istio Gateway resource in the Argo CD namespace (or the namespace your platform uses for gateways) that listens on your hostname over HTTPS and references a Kubernetes TLS Secret holding your certificate and key. Use the certificate source your organization requires, whether an internal CA or a managed issuer, and confirm the certificate's subject covers the hostname. Apply the Gateway and check that the gateway pods pick up the listener. The check is that the TLS handshake to the hostname returns your expected certificate chain, which you can confirm with a standard TLS client before adding any routing.
Define the VirtualService with prefix match and rewrite
Create a VirtualService bound to the Gateway that matches the prefix /argocd and forwards traffic to the argocd-server Service on its HTTP port. Configure the rewrite so the path prefix is handled the way the ingress guide describes for your chosen setup, keeping the subpath consistent with the rootpath and basehref values from earlier. Apply the resource and confirm Istio reports the configuration as valid. The check is that a request to the hostname at /argocd returns the Argo CD login page HTML, and that a request to a path outside the prefix does not reach Argo CD.
Set the CLI grpc-web root path
Configure the argocd CLI to use the subpath for its gRPC-web traffic by setting the grpc-web root path flag to /argocd, and make sure the gRPC-web route is reachable through the same gateway and prefix. Without this, the CLI sends requests to paths the VirtualService does not match. Test the flag from a workstation that is not inside the cluster network. The check is that the CLI reaches the server version endpoint through the public hostname, which confirms the grpc-web path matches the routing you built.
Verify login, assets, SSO callback and CLI login
Run a final acceptance pass through the public hostname. Sign in as a local user or through your configured SSO provider, confirm the browser loads the stylesheets, scripts and images from under /argocd rather than the root path, and confirm the SSO redirect returns to a URL under /argocd. Finally, log in with the CLI and run a read-only command such as listing applications. Note that the SSO redirect URL registered with your identity provider must match the subpath address exactly, so check it against your provider's configuration. The sequence is complete when all four checks pass from a client outside the cluster.

Choosing where TLS ends for the subpath setup

In this model, the Istio Gateway holds the public certificate and decrypts HTTPS from users and the CLI. The Argo CD API server runs with server.insecure set to true, so it accepts plain HTTP from the gateway. Certificate issuance and rotation happen in one place, which is usually the simplest option for a platform team that already manages gateway certificates.

Certificate ownership: Only the gateway needs a certificate for the public hostname, so renewal touches one resource.
Internal traffic: Traffic between the gateway and the API server is plain HTTP unless you add mesh mutual TLS, so confirm that your mesh policy covers this hop.
Component TLS: Argo CD's own internal components still use TLS, and the security documentation describes this as a separate control from the gateway setup.
CLI path: Confirm that the gRPC and grpc-web routes both terminate at the gateway with the correct subpath settings.
Audit view: Auditors will ask where plaintext exists, so document the hop and any mesh encryption that covers it.

Before choosing this model, confirm with your security team whether plaintext between the gateway and the API server is acceptable in your environment.",

The CLI uses gRPC, and the topic guidance requires --grpc-web-root-path when Argo CD is served under a subpath. Where TLS ends affects whether the CLI can reach the server directly or must fall back to grpc-web over HTTP. Teams often discover the difference only after the browser works and the CLI fails.

Termination at the gateway: The CLI connects over HTTPS to the gateway, and the gateway converts traffic to HTTP for the API server.
Termination inside Argo CD: The CLI negotiates TLS with the API server, so the gateway must not alter the gRPC stream.
Subpath flags: Set --rootpath and --grpc-web-root-path consistently with the chosen model.
Testing: Run a login and a sync from the CLI on a workstation outside the cluster to verify the path.
Automation: Pipelines that call the CLI need the same path and certificate trust, so update their configuration with the chosen model.

Test CLI login and sync from a workstation and a CI runner before handing the setup to users.

Security controls to keep on a shared path

A subpath route puts the Argo CD UI, API and CLI behind one shared entry point, so the controls that matter most sit at the edges: who can log in, which paths are reachable, who can edit routes and which components are exposed. The cards below cover the Argo CD settings and the Istio configuration decisions that connect those edges.

Disable the built-in admin user

The built-in admin account is a standing password-based login that bypasses your identity provider. Once SSO or local users exist, set admin.enabled to false in the argocd-cm ConfigMap so the subpath cannot be used as a back door. Before you disable it, confirm that at least one SSO or local administrator can log in and that the RBAC mapping for that administrator works. Keep a documented break-glass procedure for the case where SSO is down.

Expect JWT-only API authentication

Argo CD authenticates API requests only with JSON Web Tokens, so the gateway should not be expected to add a second login layer that the CLI and automation can satisfy. Test the CLI and any CI jobs through the subpath with real tokens, including tokens issued for automation accounts. Confirm that your gateway forwards the Authorization header unchanged, because stripping or rewriting it breaks API calls in ways that look like permission errors.

Limit the published path

Publish only the prefix Argo CD needs, such as /argocd, and avoid a catch-all match on / or on a wide prefix that other workloads share. In the VirtualService, match the prefix exactly and route it only to the Argo CD server Service. Review whether the gRPC CLI route needs its own narrowly scoped match, and document which paths are reachable from which networks.

Restrict who edits routes

The VirtualService and Gateway define who can reach Argo CD and what they can reach, so changes to them are security changes. Limit create, update and delete rights on these objects to the platform team, and require review through Git for every change. Watch for other teams' VirtualServices that match the same host or prefix, since overlapping routes can send Argo CD traffic to the wrong destination or expose a path you did not intend.

Credentials are redacted from output

Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs. This protects against accidental disclosure through the UI, API or log aggregation, but it does not replace secret hygiene on the cluster. Confirm that your logging pipeline and any gateway access logs do not capture request bodies or authorization headers, since those sit outside Argo CD's redaction.

Treat repo-server exposure separately

Routing controls who reaches the Argo CD UI and API, but the repo-server runs Helm and Kustomize on repository content, which is a separate risk. Publishing the subpath does not expose the repo-server, so keep it as a cluster-internal Service with no gateway route. Review which repositories are trusted and which out-of-tree file references are allowed, because those decisions determine what a compromised or malicious repository can do.

Operating the subpath after go-live

Treat the subpath configuration as part of the Argo CD platform, not a one-time setup. Each Argo CD minor release ships roughly every three months, and only the three most recent minor versions receive patch releases, so a routing configuration that works today will eventually need to move with the platform. Before any Argo CD upgrade, read the release notes for changes to the settings this topic depends on, including server.rootpath, server.basehref and the gRPC-web root path used by the CLI. Then retest the path in a non-production cluster that runs the same Istio version and the same Gateway and VirtualService resources. Confirm the Istio version against the compatibility guidance from your own platform team, since Argo CD routing and Istio routing both change over time.

Keep the Gateway, VirtualService and the Argo CD settings that reference the prefix in Git, managed by the same change process as the rest of your Argo CD configuration. If the Argo CD installation is itself managed by Argo CD, the routing resources belong in that repository too. This makes every prefix change reviewable and gives you a known-good revision to roll back to. After each change, whether it comes from an upgrade, a Helm value change or an Istio update, run a short smoke test that covers three things: the web UI loads under the prefix, a user can sign in through the configured single sign-on flow, and the CLI can log in and run a read-only command such as listing applications. Record the results so the next person can compare them.

Watch for two failure patterns after a prefix change. Redirect loops usually mean the server, the proxy and the browser disagree about the public path, often because a rewrite strips the prefix while server.rootpath still expects it, or because a redirect target omits it. Mixed content appears when the page loads over HTTPS but requests static assets or API calls over an HTTP or unprefixed URL, which browsers block and which can look like a broken login. Check the browser developer tools and the Istio proxy logs during the smoke test, and confirm that the external URL in your identity provider's redirect configuration matches the prefixed address exactly. If your team cannot reproduce a clean result, confirm the expected settings for your Argo CD version against the official ingress guide before changing anything else.

Limits to confirm in your environment

A subpath publish touches the Argo CD version, the Istio release, the install method, the CLI path and your network controls at once. Confirm each of these in your own environment rather than assuming the ingress guide's example carries over unchanged.

Argo CD version and Istio rewrite behavior

Confirm the exact Argo CD minor version you will run, then check that your Istio release handles the path rewrite you need on the VirtualService. Rewrite and header handling differ between Istio releases, so a configuration that works on one cluster can misroute on another. Test the UI assets, API calls and redirects under the subpath, not only the login page. Record the Argo CD and Istio versions together so later upgrades start from a known pair.

SSO callbacks under the subpath

Identity provider redirect URIs and the Argo CD URL setting must match the subpath exactly, including the trailing path segment. If you use bundled Dex or a direct OIDC provider, check the issuer and callback values in both places. A mismatch usually shows up as a login loop or a redirect to the root path rather than an obvious error. Confirm this with the identity team before any user is asked to sign in.

Community Helm chart versus raw manifests

The install method decides where --rootpath, --basehref and the grpc-web root path are set, and whether they land in the argocd-cmd-params-cm ConfigMap or the container arguments. Confirm which values your chart version exposes and whether a chart upgrade overwrites local changes. Keep one source of truth so the path settings do not drift between environments.

CLI access through the gateway

The argocd CLI uses gRPC, and its path handling differs from the browser. Confirm that the CLI can log in and run commands through the same gateway, using the grpc-web root path setting where your routing requires it. Test from a workstation outside the cluster, since a successful in-cluster test does not prove the external route works. Note any CI jobs that also depend on the CLI path.

Single host or multi-host layout

Decide whether the UI, API and CLI share one host with a path prefix or whether gRPC needs its own hostname. Some gateway designs and certificate setups work better with separate hosts, and mixing them late can force a second round of DNS and certificate work. Confirm the layout with your network and certificate owners before writing the VirtualService.

Network policy and mesh mTLS

Check whether your cluster enforces Kubernetes NetworkPolicy or Istio authorization policies that could block traffic between the gateway, the Argo CD server and the repo-server. If sidecar mTLS is strict, confirm how the gateway reaches Argo CD and whether internal component traffic is affected. Ask your platform team to review these policies in a non-production cluster first.

Questions teams ask before serving Argo CD under a path

How much effort does serving Argo CD under a subpath take?

The effort depends mainly on how much Istio your platform already runs and how many access paths you need to support. A single Gateway and VirtualService that serves the web UI under a path such as /argocd is a contained change. The work grows when you also need the CLI, SSO callbacks and a second hostname. Four factors drive the scope:

Istio maturity: whether your team already manages Gateways, VirtualServices and sidecar injection in production.
SSO: whether the identity provider redirect URLs must change to match the new path.
CLI use: whether engineers use the argocd CLI through the gRPC-web root path.
Hostnames: whether the UI lives on one host or several.

Ask for these four inputs to be written into the scope before any quote is produced.

Can our in-house team set up Argo CD under a path alone?

Yes, if the team already operates Istio and Argo CD and can test changes in a non-production cluster first. The configuration itself is small: the server needs the rootpath and basehref settings that match the path, and the CLI needs the grpc-web root path. The risk lies in proxy rewrites, redirect loops and login callbacks that only fail after a change reaches users. A team without recent Istio experience usually benefits from an outside review of the Gateway and VirtualService rules before go-live. Your team keeps ownership of the cluster, and a fixed-scope engagement can cover only the parts you choose to hand over.

What do we need to provide before the work starts?

Plan to provide access and decisions rather than hands-on time from every team. You will typically need:

Cluster access: a kubeconfig or a deployment pipeline account with rights to the Argo CD namespace and the Istio resources.
DNS: a record for the hostname that will front the Gateway.
Certificates: a certificate and key for that hostname, or confirmation of the issuer your platform uses.
A change window: a time when routing can be switched and rolled back.
SSO administration: someone who can add the new redirect URLs to the identity provider.

Confirm the names and owners of each item early, because DNS and identity changes often take longer to approve than the cluster change itself.

How long does a subpath setup take?

The duration depends on scope, so no fixed figure applies. A UI-only setup on a cluster with working Istio is shorter than a setup that includes SSO, CLI access, several hostnames and a staged cutover. The agreed timeline belongs in the written scope, which lists deliverables, environments, test steps and the dates on which each depends on your approvals. Ask any provider to name the dependencies that could move the schedule, such as DNS approval, identity provider changes or the availability of a change window.

What does a quote for this work depend on?

A quote follows from the written scope rather than from a standard price. DeployOpen does not publish a price list. The main inputs are the number of environments, whether SSO and CLI access are included, the state of the existing Istio configuration, the number of hostnames and the testing and handover expected. Ask for the quote to separate one-time implementation work from any recurring support, and to list which items the client must supply. Compare quotes on the same scope rather than on headline totals.

Does DeployOpen support the subpath setup after go-live?

Yes, ongoing support is available as a retainer. A retainer can cover Argo CD upgrades, checks after Istio or Argo CD version changes, and fixes to routing or SSO settings. Upgrades matter here because path-related settings can change between releases, so each upgrade should be checked against the routing you built. Confirm in writing what the retainer covers, how requests are raised and how quickly changes are scheduled, since these terms are set in the agreement and not assumed.

How DeployOpen scopes and delivers an Argo CD subpath publish

DeployOpen treats a subpath publish of Argo CD as a small, testable change to routing and Argo CD settings, applied inside your own cluster and reviewed against your gateway standards. We agree the scope in writing first, then build and verify the path for both the web UI and the CLI before handover.

How we scope

Confirm the Istio version, Gateway and VirtualService ownership, and the chosen subpath such as /argocd before any work starts.
Record whether TLS ends at the Istio ingress gateway and which hostname the UI and CLI will use.
Agree in writing which Argo CD settings change, including rootpath, basehref and the CLI grpc-web root path.

How we build

Set the Argo CD server rootpath and basehref values in the deployment configuration under version control.
Write the Gateway and VirtualService rules, including the prefix match and any proxy rewrite the path requires.
Test UI login, asset loading, API calls and CLI login through the subpath in a non-production cluster first.

How we hand over

Deliver the manifests or Helm values, routing definitions and a short runbook covering each setting and why it exists.
Document the verification steps so your team can repeat the UI and CLI checks after any gateway or Argo CD upgrade.
Walk through the configuration with your platform and security engineers so ownership of each resource is clear.

How we support

Engagements are fixed-scope, so changes after handover are scoped as separate written work.
Ongoing support, upgrades and continuous testing are available as a retainer if you want DeployOpen to keep the path working.
Ask us to confirm which Argo CD and Istio versions your retainer covers before upgrades begin.