Argo CD on OpenShift with Red Hat OpenShift GitOps

Running Argo CD on OpenShift through the Red Hat OpenShift GitOps operator means choosing between the default openshift-gitops instance and scoped instances, then planning support cadence and upgrades. This page sets out how to decide and build it.

On this page

Argo CD on OpenShift with Red Hat OpenShift GitOps: what the operator changes

A platform team running OpenShift that wants GitOps delivery into clusters it controls should start with the Red Hat OpenShift GitOps operator, not with upstream Argo CD manifests applied by hand. The operator uses Argo CD as its declarative GitOps engine and manages the Argo CD installation through an ArgoCD custom resource. That resource is the supported control point for versions, replicas, RBAC, SSO and ingress settings, so changes go through the operator and survive upgrades. Hand-applied upstream manifests bypass that lifecycle, and the team then owns every upgrade step and every drift between the manifests and the operator's expectations.

The operator creates a default Argo CD instance in the openshift-gitops namespace. That instance receives extra permissions for certain cluster-scoped resources, which is why it is the one most teams use first and why it deserves the closest review. Instances created in other namespaces manage only their own namespace by default. Decide early which pattern fits: a single cluster-wide instance for platform-owned deployments, or namespace-scoped instances for team boundaries. Mixing the two without a plan leads to overlapping ownership of the same resources. Confirm the exact permissions granted to the default instance against the Red Hat documentation for your OpenShift GitOps version, since they are the first thing your security reviewers will ask about.

Before building on the operator, confirm three things with Red Hat and your own environment: which OpenShift GitOps release matches your OpenShift Container Platform version, since OpenShift GitOps follows its own release cadence and documents each minor release separately; the support window for that release; and whether your team will need the community Argo CD Operator at all. The community operator's documentation describes the project as effectively dormant, with development moved to the redhat-developer/gitops-operator repository, so new builds should not start on it. The Red Hat OpenShift GitOps 1.15 documentation is the natural next read for the instance model and its defaults.

What you need before installing OpenShift GitOps

OpenShift GitOps is installed and upgraded on its own cadence, so the operator release has to be matched to your cluster before anything else. The cards below cover the access, network paths, Git sources and identity decisions that shape the first install and the instances that follow.

Matched cluster and operator release

OpenShift GitOps releases on a different cadence from OpenShift Container Platform, and its documentation is versioned per minor release. Start by recording your exact cluster version, then confirm in the Red Hat documentation for that release which OpenShift GitOps version is supported on it. Do not assume that the latest operator fits an older cluster, and write the pairing into your change record so the next upgrade starts from a known baseline.

Cluster-admin access for installation

Installing the operator and the default Argo CD instance in the openshift-gitops namespace needs cluster-level rights, because that instance receives extra permissions for certain cluster-scoped resources. Decide who holds that access during installation, who holds it afterward, and whether it is granted through a break-glass process. Narrowing this access later is possible, but the decision affects what the default instance can change on every cluster it manages.

Git repository access

Argo CD reads desired state from your Git hosts, so the repositories, branches and credentials must exist before the first Application syncs. Confirm which repositories the instance needs, whether they are private, and how read-only credentials will be issued and rotated. Repository definitions belong in Kubernetes Secrets, so plan the namespace and the owner of those objects at the same time.

Network paths to target clusters

An Argo CD instance must reach the Kubernetes API of every cluster it deploys to, and your users must reach its web console through an OpenShift route. Map each source and destination, including any firewall, proxy or segmented network between the control cluster and the targets. Ask your network team to confirm these paths before the install, since a blocked API endpoint often looks like a failed sync rather than a network problem.

Identity provider access for SSO

Argo CD can use its bundled Dex or connect directly to an existing OIDC provider, and the admin user should be disabled once SSO is working. Before installation, confirm who can register the Argo CD client in your identity provider, which groups will map to Argo CD roles, and which claim carries those groups. Changes to the claim and RBAC model in Argo CD 3.0 mean these details should be settled against the version you intend to run.

Upstream and Red Hat version differences

The Red Hat operator packages Argo CD with its own defaults, so behavior can differ from upstream manifests you may have read elsewhere. Before you copy settings from upstream guides, confirm the Argo CD version bundled with your OpenShift GitOps release and check how RBAC, repository configuration and resource tracking are handled there. Treat upstream examples as starting points to verify, not as drop-in configuration.

Default instance or scoped instances: how to choose

The operator creates a default Argo CD instance in the openshift-gitops namespace, and Red Hat grants it extra permissions for certain cluster-scoped resources. That makes it the natural home for platform-owned components such as cluster configuration, operators, namespaces and shared cluster services. Ownership normally sits with the platform team, which controls the instance's configuration and its access.

  • Owner: the platform or cluster administration team, not application teams.
  • Scope: cluster-wide resources are reachable, so the instance can manage objects outside any single namespace.
  • Use for: cluster bootstrap, operator subscriptions and shared platform add-ons.
  • Access: restrict who can edit the Argo CD custom resource and its projects, since that is effectively cluster administration.
  • Upgrades: the instance follows the OpenShift GitOps operator channel, so plan its updates with the cluster.

Before you rely on it, confirm with Red Hat documentation which cluster-scoped permissions the default instance holds for your OpenShift GitOps version, and who in your organization is allowed to change its Git source repositories.

How to install and configure the OpenShift GitOps instance

This sequence takes an OpenShift cluster from a bare operator subscription to a working GitOps instance that pulls from your repositories, deploys to the clusters you register, and no longer relies on the built-in admin login.

  1. Subscribe to the OpenShift GitOps operator

    A cluster administrator installs the Red Hat OpenShift GitOps operator from OperatorHub, choosing a channel that matches the OpenShift GitOps minor release your support plan covers. The operator is versioned separately from OpenShift Container Platform, so confirm the pairing in the release documentation before you choose a channel. Done means the ClusterServiceVersion reports Succeeded and the operator pod is running in its install namespace.

  2. Verify the default instance in openshift-gitops

    The operator creates a default Argo CD instance in the openshift-gitops namespace, and that instance receives extra permissions for certain cluster-scoped resources. Confirm the instance's server, repo-server and application controller pods are ready, and record which cluster-scoped permissions it holds so the platform team knows its blast radius. Done means the instance reports healthy and you can log in through the route the operator exposes.

  3. Create namespace-scoped instances where teams need them

    For team-owned deployments, create an additional Argo CD instance in its own namespace. By default such an instance manages only its own namespace, so it cannot deploy cluster-scoped resources unless you grant that deliberately. Decide per team whether the default instance or a namespace-scoped instance owns each application, and write that decision down before onboarding. Done means the new instance is healthy and a test Application in its namespace syncs successfully.

  4. Define repositories as Kubernetes Secrets

    Register each Git repository as a Kubernetes Secret labeled for Argo CD repository use, holding the URL and read-only credentials, rather than adding it to a ConfigMap. Argo CD 3.0 removed repository configuration from argocd-cm, so this is the only supported path on current versions. Store the Secrets in the instance namespace and restrict who can read them. Done means Argo CD lists the repository as successfully connected and a test Application pointing at it reports a fetched revision.

  5. Register target clusters

    Add each destination cluster to the instance using a cluster Secret that carries the API server address and credentials scoped to what that instance may deploy. Use the cluster-scoped permissions the default instance already holds only where needed, and prefer namespace-limited credentials for team clusters. Confirm the credentials are not logged or shown in the UI, since Argo CD redacts them from responses. Done means the cluster shows a Successful connection status and a test sync to a sandbox namespace completes.

  6. Configure SSO and map groups to roles

    Connect the instance to your identity provider, either through the bundled Dex with a connector or through a direct OIDC integration, then map provider groups to Argo CD roles in RBAC. In Argo CD 3.0 and later, Dex-based RBAC uses the federated_claims.user_id claim, so check that claim in a test login. Done means a test user from each intended group signs in and sees only the projects and applications their role allows.

  7. Disable the built-in admin user

    Once SSO and at least one local administrator work, set admin.enabled to false in the instance configuration so the built-in admin account can no longer sign in. Keep a break-glass procedure documented that your platform team has tested, since disabling the account removes the fallback login. Done means a login attempt as admin is rejected and an SSO administrator can still create and sync an Application.

Which upstream settings change on OpenShift

This table maps the upstream Argo CD settings you may already know to where OpenShift GitOps expects them. Read each row as a starting point: the operator owns and reconciles these objects, so confirm each key and resource name against the documentation for your exact OpenShift GitOps minor release before you change anything.

SettingUpstream Argo CDOpenShift GitOps
Repository definitionsRepositories defined as Kubernetes Secrets, since Argo CD 3.0 removed repository entries from argocd-cmStill Secrets in the instance namespace, but confirm whether the operator reconciles or overwrites them when the instance is reconciled
SSO group to role mappingpolicy.csv in argocd-rbac-cm, with Dex RBAC keyed on the federated_claims.user_id claimSet through the instance custom resource's RBAC section, so confirm the field path and claim handling in your release
Resource tracking methodAnnotation-based tracking is the default from Argo CD 2.14 to 3.0 onwardConfirm the tracking method the operator sets on the default instance and whether a namespace-scoped instance inherits it
Admin useradmin.enabled set to false in argocd-cm once SSO or local users existConfirm whether the instance custom resource exposes this setting and whether the operator re-enables the built-in admin
Config overridesEdited directly in argocd-cm, argocd-rbac-cm and argocd-cmd-params-cmExpressed as spec fields on the ArgoCD custom resource, which the operator renders into those ConfigMaps
Instance scopeOne cluster-wide or namespace-scoped install, defined by manifest choiceDefault instance in openshift-gitops with extra cluster-scoped permissions; other instances manage only their own namespace by default
Upgrade cadenceMinor release every three months, with patches for the three most recent minorsOperator releases follow a separate cadence from OpenShift, so match the operator channel to your cluster version

How support cadence affects Argo CD upgrades on OpenShift

Upgrades on OpenShift are governed by two clocks that do not match. Red Hat OpenShift GitOps releases on its own cadence, separate from OpenShift Container Platform, and its documentation is versioned per minor release. Upstream Argo CD, which the operator embeds as its engine, ships a minor release roughly every three months, and only the three most recent minor versions receive patch releases. A cluster that stays on an older operator channel can therefore fall outside the upstream patch window even while the operator itself is still supported. Before planning any move, confirm the operator minor release your cluster is on, the Argo CD version it bundles, and the end of support date stated in the Red Hat documentation for that release.

The largest step change in recent history is the 2.14 to 3.0 transition, and it bundles several changes that break existing setups. Update and delete RBAC now apply only to the application itself, so policies that relied on broader effects will stop working. Access to pod logs requires an explicit logs, get permission. Annotation-based resource tracking is the default, which changes how Argo CD recognizes resources it owns. Repository configuration was removed from the argocd-cm ConfigMap, so every repository must be defined as a Kubernetes Secret, and Dex-based RBAC keys off the federated_claims.user_id claim. For each of these, inventory the affected AppProject and RBAC policies, repository definitions and SSO group mappings, then test them against a non-production instance running the target operator version.

Pin the operator subscription to a named channel and version, and promote changes through environments only after the RBAC, repository and sync checks pass. Also note the state of the community Argo CD Operator. Its documentation describes the project as effectively dormant, with development moved to the redhat-developer/gitops-operator repository. Teams that installed the community operator should plan a migration to the Red Hat operator rather than expecting upstream fixes there. Confirm the exact migration path and any custom resource differences with Red Hat support before you schedule the change, since an untested move can leave applications without a managing controller during the switch.

Hardening the OpenShift GitOps instance

The default instance in openshift-gitops holds broad reach into the cluster, so hardening starts with who can sign in and what the instance can touch. The cards below cover identity, cluster privilege, repo-server exposure, credential storage and Secret access, which together decide how much damage a compromised repository or account could cause.

Disable the built-in admin user

The admin account is meant for first-time setup only. Once SSO or local users work, set admin.enabled to false in the Argo CD configuration so password login through the built-in account stops. Before you flip it, confirm that at least one SSO group maps to an administrator role and that a second person can sign in, so you do not lock yourself out of the instance. Record the change in your change system, because it alters how operators reach the cluster.

Limit cluster-scoped permissions

The default instance in openshift-gitops receives extra permissions for certain cluster-scoped resources, which is why it can reach further than an instance you create in another namespace. List what it actually manages, then decide whether it needs those rights or whether a separate, namespace-scoped instance should handle team workloads. Review the service account bindings after each operator upgrade, since the grants come from the operator and can change with its release.

Control repo-server exposure

The repo-server runs Helm and Kustomize against repository content, so a malicious chart, overlay or out-of-tree file reference can read or influence what Argo CD renders. Restrict which repositories are registered, require review on the branches Argo CD tracks, and avoid plugins that run untrusted scripts. Confirm which Helm or Kustomize options are enabled for each Application, and check the pod's network and service account permissions against what rendering actually needs.

Store repository and cluster credentials as Secrets

Argo CD 3.0 removed repository definitions from the argocd-cm ConfigMap, so repositories must live in Kubernetes Secrets. Use the same pattern for cluster credentials and keep the manifests that create those Secrets out of plain Git history. Confirm with your platform team that etcd encryption at rest is enabled on the OpenShift cluster, because Kubernetes stores Secrets unencrypted in etcd by default and the GitOps credentials would otherwise sit there in readable form.

Restrict Secret list and watch access

Any identity that can list or watch Secrets in the Argo CD namespace can read every repository and cluster credential stored there. Grant Secret access only to the Argo CD service accounts that need it, and keep human roles at get or none for those objects. Audit RoleBindings and ClusterRoleBindings that cover the openshift-gitops namespace, and check that no broad group inherits list or watch rights through a wildcard role. Repeat the audit after any operator or SSO group change.

Common failures on OpenShift GitOps and how to fix them

This table pairs six failures teams commonly hit when running Argo CD through Red Hat OpenShift GitOps with the cause and fix for each. Read each row against your own instance and confirm the behavior in the OpenShift GitOps documentation for your installed minor version before changing anything.

FailureLikely causeFix to confirm and apply
Instance stuck after an operator upgradeThe operator moved to a new minor version and the Argo CD instance it manages has not finished reconciling, or a manually edited resource conflicts with the operator's desired stateCheck the operator and instance status conditions, review the operator release notes for your target minor version, and remove or reconcile manual edits to operator-managed resources before retrying the upgrade
Applications OutOfSync after resource tracking changesAnnotation-based resource tracking is the default in Argo CD 3.0, so resources labeled under the older tracking method no longer match and appear as driftConfirm the tracking method on the instance, plan a controlled sync of affected applications, and check the upgrade notes for the tracking setting before changing it
Sync denied by RBAC after moving to 3.0Update and delete permissions now apply only to the application itself, and reading logs needs an explicit logs, get permission, so older policies no longer cover the actions teams performAudit the policy.csv entries for each project role, add explicit logs, get rules where needed, and test the sync and log actions with a non-admin account
Repositories not found after moving out of argocd-cmArgo CD 3.0 removed repository configuration from the argocd-cm ConfigMap, so repositories defined there are no longer readRecreate each repository as a Kubernetes Secret labeled for repository use, verify the instance reads it, and remove the stale entries from argocd-cm
Default instance permissions blocking a namespace-scoped teamThe default instance in openshift-gitops has extra permissions for certain cluster-scoped resources, and teams often assume a namespace instance has the same reachConfirm which instance owns each application, scope the namespace instance to its own namespace, and keep cluster-scoped changes on the platform instance under platform team control
SSO group mismatchThe group claim from the identity provider does not match the group names in Argo CD role mappings, or Dex-based RBAC expects the federated_claims.user_id claim after the 3.0 changeDecode a test login token to confirm the claim names and values, update the role mappings to match exactly, and test one user per role before rolling out

Questions buyers ask before running OpenShift GitOps

What drives the cost of running Argo CD on OpenShift with OpenShift GitOps?

The main cost drivers are the number of clusters the instances must reach, how many OpenShift GitOps instances you need, and how much identity and Git integration is involved. Each additional cluster adds registration, RBAC and network-path work. Each instance adds its own configuration, backup and upgrade testing. SSO through an existing identity provider, the repository access model, and the disaster recovery design also add scope. Ongoing costs come from operating the instances, testing each operator release and handling new minor versions. Ask any quote to split one-time build work from recurring support, and to list the clusters, instances and integrations it covers.

How long does an OpenShift GitOps implementation take?

Duration depends on scope, not on a fixed template. The schedule is set by how many clusters and instances are in scope, how quickly your identity and Git owners respond, and how much upgrade and recovery testing you require. Because OpenShift GitOps releases on its own cadence and documents each minor release separately, the operator version you target affects the plan. Most engagements are fixed-scope, so the written scope and timeline are agreed before work starts. Ask for the milestones, the client dependencies behind each one, and what happens if a dependency slips.

What access and people do we need to provide?

Expect to provide cluster-admin or equivalent access to the OpenShift clusters where the operator and instances will run, because the default instance in the openshift-gitops namespace receives extra permissions for certain cluster-scoped resources. Git owners must confirm repository structure, branch rules and the credential model. Identity administrators must provide the SSO connection details and group mappings. Platform owners should approve the instance layout and the backup location. Name one decision-maker for scope changes, since those change cost and timeline in a fixed-scope agreement.

Can our internal platform team run OpenShift GitOps on its own?

Often yes, if the team already runs OpenShift and understands Git-driven delivery, but the work is not only installation. The team must own operator upgrades, instance configuration, RBAC and projects, SSO and disaster recovery testing, and the response when an application stays OutOfSync. Upgrade notes for Argo CD major versions change RBAC behavior and resource tracking, so someone must read and test those notes before each change. Assess your team on those skills and on available time. An internal team can run it alone when those responsibilities are staffed and documented.

Which Argo CD and OpenShift GitOps differences should our engineers check first?

Start by confirming which instance manages which namespaces. The default instance in openshift-gitops has extra permissions for certain cluster-scoped resources, while instances created elsewhere manage only their own namespace by default. Next, compare the operator's configuration with the upstream Argo CD manifests your team may have read, because settings and resource names can differ. Check the RBAC model, since Argo CD 3.0 changed update and delete permissions to apply to the application itself and requires an explicit logs permission for log access. Confirm the Argo CD version the operator ships and read its documentation for that release.

When does a fixed-scope engagement fit, and when is a retainer better?

A fixed-scope engagement fits when the clusters, instances, identity integration and recovery goals are known and can be written down before work starts. It suits a first rollout or a defined migration into OpenShift GitOps. A retainer fits when the platform keeps changing, for example with regular operator upgrades, new clusters or continuous testing of the delivery path. Many organizations combine both: a fixed-scope build followed by a support arrangement for upgrades and operations. Ask for the scope boundaries, the upgrade testing included, and the response expectations written into either agreement.

What should a quote for OpenShift GitOps include?

A useful quote lists each cluster and OpenShift GitOps instance in scope, the identity provider integration and group mapping, the repository and credential model, and the backup and disaster recovery design. It should state which upgrade testing is included, how operator versions will be validated, and what documentation and handover you receive. Separate one-time build work from recurring support. Confirm which client-side tasks are assumed, such as access grants and approvals, and what changes if those tasks are late. DeployOpen does not publish a price list, so the quote follows from the written scope.

Does running OpenShift GitOps help with compliance evidence?

Argo CD's Git-based change flow, projects, RBAC and sync history can support the change and configuration management evidence that auditors test, but the platform alone does not satisfy a control. DeployOpen prepares systems, controls and evidence for compliance assessments; it does not issue audit reports, attestations or certifications. Ask your auditor which evidence they expect, such as approval records, access reviews and recovery test results, and confirm that the design captures them. Independent auditors and certification bodies make the final determination.

Official Red Hat and Argo CD documentation to read first

Start with the Red Hat OpenShift GitOps 1.15 documentation, specifically the *Understanding OpenShift GitOps* guide, before you touch a cluster. OpenShift GitOps is an operator that uses Argo CD as its engine, and it creates a default Argo CD instance in the openshift-gitops namespace with extra permissions for certain cluster-scoped resources. Instances you create elsewhere manage only their own namespace by default. Your platform team needs to decide which of these models fits each cluster, and that guide is where the operator's own boundaries are defined. Confirm the operator version you will run against your OpenShift Container Platform release, because OpenShift GitOps follows its own release cadence and its documentation is versioned per minor release.

Next, read the Argo CD upgrade notes for 2.14 to 3.0. Several changes there affect an OpenShift rollout directly: update and delete RBAC now apply only to the application itself, reading logs requires an explicit logs, get permission, and annotation-based resource tracking is the default. Repository configuration also moved out of the argocd-cm ConfigMap and into Kubernetes Secrets, and Dex-based RBAC now uses the federated_claims.user_id claim. If your existing policies were written before 3.0, review them against these notes before you copy them into an OpenShift instance.

Then read the Argo CD user management and security documentation together. The user management guide recommends using the built-in admin user only for initial setup and disabling it with admin.enabled set to false once local users or SSO are configured. The security guide covers JSON Web Token authentication for API requests, TLS between Argo CD components, and the fact that the repo-server runs Helm and Kustomize on repository content, which makes untrusted repositories a real exposure. Use these pages to set your SSO, RBAC and repository trust decisions before the first sync runs.

How DeployOpen scopes and delivers OpenShift GitOps

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For Argo CD on OpenShift, we start from a written scope that settles which OpenShift GitOps instances exist, what they manage and who operates them, before any cluster change is made.

How we scope

  • Inventory the OpenShift clusters, the default openshift-gitops instance and any namespace-scoped instances the teams need.
  • Document which cluster-scoped resources each Argo CD instance may manage and who approves changes to those permissions.
  • Agree the OpenShift GitOps version, its support window and the upgrade path in the written scope before work starts.

How we build

  • Configure SSO, RBAC and AppProject boundaries for each team, then test that access matches the agreed model.
  • Define repository access through Kubernetes Secrets in the GitOps namespace and verify that Git credentials stay redacted in logs.
  • Test sync, rollback and disaster recovery of applications on a non-production cluster before any production cutover.

How we hand over

  • Deliver runbooks covering instance layout, RBAC mappings, repository onboarding, upgrade steps and recovery procedures.
  • Walk your platform and security teams through the Git-based change flow, admin account policy and alert ownership.
  • Record configuration, decisions and open risks in the written deliverables so your team can operate the setup without us.

How we support

  • Support is available as a retainer for patching, OpenShift GitOps upgrades and troubleshooting on a running installation.
  • Retainer scope, response expectations and upgrade coverage are agreed in writing, and we confirm them with you before signing.
  • Confirm with Red Hat which OpenShift GitOps release matches your OpenShift version, since the two release on different cadences.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.