Insights · OpenShift
OpenShift GitOps: Declarative Cluster Management with Argo CD
Overview
OpenShift GitOps operationalizes the idea that cluster state should match Git — continuously, audibly, and reversibly. The OpenShift GitOps Operator installs and manages Argo CD on OCP with Red Hat-supported versions, integrated OAuth for the Argo UI, and patterns documented for multi-cluster fleet management. Imperative kubectl apply from laptops becomes the exception, not the rule.
Argo CD watches Git repositories (or Helm, Kustomize, and OCI sources) and reconciles Applications against the API server. Drift appears in the UI and metrics; rollbacks are git revert. On OpenShift, GitOps controllers must respect projects, RBAC, SCCs, and sometimes cluster-scoped operators installed via OLM — repository layout and AppProject boundaries determine whether teams can self-serve safely.
This article covers operator installation, repository structure, ApplicationSet generators for multi-tenant fleets, secrets handling without leaking credentials into Git, and how platform engineering teams gate production syncs with policy and promotion repos.
Need help implementing this?
Talk to engineers who deploy these patterns on OpenShift in production—not generic advisory decks.
Installing the OpenShift GitOps Operator and Bootstrap
Install the OpenShift GitOps operator from OperatorHub into the openshift-gitops namespace (or a dedicated namespace per Red Hat guidance for your OCP version). The operator deploys Argo CD CRDs, the application controller, repo server, and Redis. Configure a GitOpsCluster or ArgoCD custom resource specifying resource limits, ingress routes for the Argo UI, and Dex disabled when corporate OAuth handles authentication.
Bootstrap follows the app-of-apps pattern: a root Application points to a directory containing child Application manifests for cluster infrastructure — namespaces, quotas, network policies, cluster logging, monitoring agents. Platform teams own the root; tenant teams own leaf Applications scoped by AppProject destination namespaces and permitted cluster resources.
Initial sync waves order dependencies — CRDs and namespaces before operators, operators before workloads. Use sync-wave annotations so Argo applies resources in sequence. Without waves, a Deployment may arrive before its Namespace or Secret, causing transient failures that confuse developers into manual fixes.
Document bootstrap repo ownership and branch protection — anyone with merge to main effectively has production deploy rights. Require CODEOWNERS on platform-infra paths and signed commits where policy mandates non-repudiation.
AppProjects, RBAC, and Tenant Isolation
AppProjects restrict which Git repos, destination clusters, and resource kinds an Application may use. A payments-team project might allow only https://github.com/org/payments-* repos and namespaces matching payments-*. Cluster-scoped resources (ClusterRole, SCC bindings) belong in platform AppProjects with tighter approver groups.
Map OpenShift OAuth groups to Argo CD RBAC policies in the argocd-rbac-cm ConfigMap. Developers get read-only UI access to their Applications; platform SREs retain sync and override permissions. Avoid sharing cluster-admin kubeconfigs with Argo — the Argo CD application controller ServiceAccount should carry minimal privileges, elevated only where cluster-scoped installs demand it.
For multi-cluster OpenShift GitOps, deploy an Argo CD instance on a management cluster or use ApplicationSet cluster generators that target spoke API servers via secrets. Red Hat Advanced Cluster Management (ACM) integrates GitOps policies for fleet consistency — evaluate ACM when policy compliance across dozens of clusters matters more than a single Argo instance can enforce alone.
Spoke credentials in cluster secrets should use short-lived tokens or certificate-based kubeconfigs rotated automatically — long-lived static tokens in Git are audit findings waiting to happen.
ApplicationSets and Fleet-Scale Patterns
ApplicationSets generate Applications from generators: Git directory lists, cluster lists, SCM provider discovery, or pull-request previews. A platform team maintaining fifty tenant namespaces uses a Git generator scanning environments/*/namespace.yaml rather than fifty hand-written Application files.
Pull-request preview environments spin up temporary namespaces synced from PR branches — powerful for QA, dangerous without TTL automation and resource quotas. Pair preview generators with Kyverno policies that label and expire namespaces after merge or timeout.
Promotion flows often use separate branches or repos: dev merges auto-sync; staging requires manual sync; production requires approval via CI gate or Argo CD sync windows that block deploys outside maintenance hours. Document which pattern your organization uses — ambiguous promotion causes either reckless auto-sync or paralysis.
ApplicationSet pull-request generators integrate with GitHub or GitLab webhooks — secure webhook endpoints and validate payload signatures to prevent unauthorized preview namespace creation in shared clusters.
Secrets, Policy, and Compliance in GitOps
Never commit cleartext Secrets. Use Sealed Secrets, SOPS with KMS, External Secrets Operator syncing from Vault, or OpenShift secrets injected via CI at sync time. Argo CD supports helm-secrets and kustomize secret generators when configured on the repo server.
Policy-as-code complements GitOps: Kyverno or OPA Gatekeeper validate manifests at admission — blocking latest tags, privileged pods, or missing resource requests before Argo succeeds sync. Some teams run conftest in CI before merge; others rely on admission only. Defense in depth catches policy violations earlier.
Audit trails come from Git history plus Argo CD event logs exported to cluster logging. Change tickets should reference merge SHAs; on-call engineers trace incidents to commits, not mystery drift. OpenShift GitOps shines when compliance auditors ask who changed production and you answer with a PR link.
Repo server credential rotation should be automated — expired deploy keys cause silent sync stalls that look like application bugs. Alert on repository connection test failures from the Argo CD metrics endpoint.
Day-2 OpenShift GitOps Operations and Failure Modes
Monitor Argo CD metrics — sync failures, reconciliation duration, repo server errors — via the platform Prometheus stack. Alert on OutOfSync Applications in production AppProjects lasting beyond SLO thresholds. Common failures include expired Git tokens, renamed branches, and operators that mutate fields causing endless diff loops; use ignoreDifferences judiciously, not as a blanket suppressor.
Disaster recovery: back up Argo CD etcd state and Git remotes; rebuilding Argo from Git is possible if bootstrap manifests live in a highly available repo. Test cluster loss scenarios — spokes should re-register via ApplicationSet cluster secrets stored in vault, not sticky notes.
These OpenShift GitOps practices align with deployment best practices and multi-cluster management — Git becomes the system of record, Argo the reconciler, and OCP the execution surface. Start with one non-production cluster, prove promotion and rollback, then expand fleet-wide.
Version-pin the OpenShift GitOps operator with the same discipline as CVO — operator upgrades can change default Argo CD behavior. Read release notes before approving CSV upgrades in production hubs.
OpenShift GitOps Integration with OLM and Platform Operators
GitOps repos should declare Operator subscriptions and OperatorGroups alongside application manifests — cluster-scoped operators require platform AppProject approval. Sync waves ensure CRDs install before custom resources that depend on them.
OpenShift Pipelines can commit manifest updates back to Git after image builds — close the loop between CI image digest and GitOps desired state. Avoid race conditions where pipeline push and Argo sync collide on the same branch.
Integrate Argo CD notifications with Slack or PagerDuty for sync failure and health degradation — developers see deployment status without cluster credentials. OpenShift GitOps becomes the deployment front door most teams actually use.
Resource hooks and PreSync jobs run database migrations before Deployment sync — document ordering and timeout values so long migrations do not block entire application sync indefinitely.
CI to GitOps Handoff Patterns on OpenShift
CI pipelines should update image digests in Git via PR, not kubectl set image — Argo reconciles after merge. Branch protection ensures two-person review for production digest bumps.
OpenShift Pipelines can open PRs with kustomize image transformer patches — standardize pipeline templates per language stack to avoid bespoke Jenkins glue per team.
Rollback is git revert of digest PR — faster and auditable than imperative rollout undo when GitOps is source of truth.
Document disaster recovery for Git provider outage — local mirrors or secondary remotes prevent total inability to sync during GitHub incidents.
Multi-Tenant GitOps on Shared OpenShift Clusters
Hundreds of namespaces on one cluster need Application-per-namespace with AppProject isolation — never one Application for entire cluster unless platform team owns all resources.
ResourceQuota and LimitRange sync via GitOps prevent tenant A from starving tenant B during bad deploy day.
Self-service namespace onboarding ApplicationSet generates namespace, quota, network policy, and rolebindings from ticket metadata — reduces platform toil.
OpenShift GitOps at tenant scale requires automated testing of rendered manifests in CI — kubeconform catches invalid resources before they hit Argo sync queue.
Explore further
Need help with OpenShift?
Talk to engineers who implement these patterns in production—not generic advisory decks.