{"id":155,"date":"2026-03-08T05:22:11","date_gmt":"2026-03-08T05:22:11","guid":{"rendered":"https:\/\/blog.rebalai.com\/en\/2026\/03\/08\/setting-up-argocd-for-gitops-a-step-by-step-tutori\/"},"modified":"2026-03-18T22:00:08","modified_gmt":"2026-03-18T22:00:08","slug":"setting-up-argocd-for-gitops-a-step-by-step-tutori","status":"publish","type":"post","link":"https:\/\/blog.rebalai.com\/en\/2026\/03\/08\/setting-up-argocd-for-gitops-a-step-by-step-tutori\/","title":{"rendered":"Setting Up ArgoCD for GitOps: What Actually Works in Production"},"content":{"rendered":"

I pushed a broken Helm chart on a Friday afternoon last October. Not my finest moment. The cluster had three microservices<\/a> that needed coordinated config updates, I was in a hurry, and I did what I<\/a> always did: SSH into the jump box, run a bunch of kubectl apply -f<\/code> commands, and hope for the best. The deploy<\/a> partially succeeded, partially failed, and I spent the next two hours reverse-engineering what state the cluster was actually in versus what I<\/a> thought I’d applied.<\/p>\n

That was the last time I managed Kubernetes<\/a> deployments that way.<\/p>\n

Our team is small \u2014 four engineers, two clusters (staging and prod), maybe 15 microservices<\/a> across them. Not massive scale, but enough complexity that “just apply the YAML manually” stopped being a viable strategy months before I finally admitted it. ArgoCD<\/a> on DigitalOcean<\/a>” rel=”nofollow sponsored” target=”_blank”>ArgoCD<\/a> was something I’d been circling for a while, read a dozen tutorials about, and kept putting off because it looked complicated. Setting it up properly took me about two weeks of<\/a> on-and-off work. This post is what I<\/a> wish had existed during that time.<\/p>\n

\n

Why kubectl apply Gets Messy Fast<\/h2>\n

The core problem isn’t kubectl apply<\/code> itself \u2014 it’s the gap between what you think your cluster looks like and what<\/a> it actually<\/a> looks like. Every manual apply command is an undocumented change. Someone runs kubectl edit<\/code> to fix something urgent at 2am (speaking from experience), and now your Git repo and your cluster have silently diverged. You won’t notice until something breaks.<\/p>\n

GitOps flips the deployment model: your Git repository is the single source of truth for cluster state, and instead of pushing changes directly to the cluster, you push to Git and let the cluster pull them in. ArgoCD<\/a> watches a repo, compares what’s there to what’s running, and either alerts you about drift or automatically syncs the cluster back to match.<\/p>\n

There are other tools in this space \u2014 Flux is the main alternative, and honestly, Flux has a more “Kubernetes<\/a> on DigitalOcean<\/a>” rel=”nofollow sponsored” target=”_blank”>Kubernetes<\/a>-native” feel if you’re already deep in the<\/a> operator pattern. I went with ArgoCD<\/a> because the web UI is genuinely useful, the team could see app health at a glance without knowing the CLI, and there’s a large enough community that most weird issues I hit had an existing GitHub issue or discussion. Your mileage may vary.<\/p>\n

\n

Installing ArgoCD Without Shooting Yourself in the<\/a> Foot<\/h2>\n

ArgoCD v2.11 is what I<\/a>’m running as of this writing. The install is actually<\/a> pretty straightforward \u2014 the tricky part is the configuration decisions that come right after.<\/p>\n

# Create the namespace first\nkubectl create namespace argocd<\/a>\n\n# Install using the stable manifest\nkubectl apply -n argocd<\/a> -f https:\/\/raw.githubusercontent.com\/argoproj\/argo-cd\/v2.11.0\/manifests\/install.yaml\n\n# Wait for all pods to be Running \u2014 this takes 2-3 minutes\nkubectl wait --for=condition=available --timeout=300s deployment\/argocd-server -n argocd<\/a>\n<\/code><\/pre>\n
Once that’s done, you need to get to the UI. For local dev or initial setup, port-forwarding works fine:<\/p>\n
kubectl port-forward svc\/argocd-server -n argocd 8080:443\n<\/code><\/pre>\n
The initial admin password is auto-generated and stored in a secret:<\/p>\n
kubectl -n argocd get secret argocd-initial-admin-secret \\\n  -o jsonpath="{.data.password}" | base64 -d; echo\n<\/code><\/pre>\n
Log in at https:\/\/localhost:8080<\/code> with username admin<\/code>. First thing you should do after logging in is change that password. Second thing: delete the initial secret. The docs<\/a> tell you<\/a> this, but I glossed over it the first time.<\/p>\n
For Production<\/a> Workloads” rel=”nofollow sponsored” target=”_blank”>Production<\/a> Workloads” rel=”nofollow sponsored” target=”_blank”>production<\/a>, you’ll want a proper ingress instead of port-forwarding. I use ingress-nginx with cert-manager for TLS, and there’s a small but important detail \u2014 ArgoCD serves its API and UI over HTTPS by default, and if your ingress is also doing TLS termination, you’ll get a redirect loop unless you either disable TLS on the ArgoCD server or configure the ingress to pass through to HTTP. The ArgoCD docs cover both options. I went with the --insecure<\/code> flag on the argocd-server deployment plus TLS termination at the<\/a> ingress, which is the more common setup.<\/p>\n
One thing I didn’t anticipate: resource limits. By default ArgoCD doesn’t set CPU\/memory limits, and in a busy cluster the repo-server pod can get quite hungry when it’s rendering a lot of Helm charts. I ended up adding limits after argocd-repo-server got OOMKilled on a day we were doing a lot of syncs. Add resource requests and limits to your deployment if you’re running this anywhere near production<\/a>.<\/p>\n
\n
Defining Your First Application (Where the Real Decisions Are)<\/h2>\n
ArgoCD’s core concept is the Application<\/code> custom resource \u2014 a Kubernetes<\/a> object that tells ArgoCD “watch this Git repo at this path, and deploy<\/a> it to this cluster\/namespace.” Here’s a minimal example for a Helm chart:<\/p>\n
apiVersion: argoproj.io\/v1alpha1\nkind: Application\nmetadata:\n  name: my-api\n  namespace: argocd\n  # This finalizer causes ArgoCD to cascade-delete all managed resources\n  # when you delete this Application object \u2014 omit it if you want the\n  # workloads to survive Application deletion\n  finalizers:\n    - resources-finalizer.argocd.argoproj.io\nspec:\n  project: default\n  source:\n    repoURL: https:\/\/github.com\/your-org\/your-repo\n    targetRevision: HEAD\n    path: deployments\/my-api\n    helm:\n      valueFiles:\n        - values.yaml\n        - values-prod.yaml  # environment-specific overrides\n  destination:\n    server: https:\/\/kubernetes.default.svc  # in-cluster\n    namespace: production<\/a>\n  syncPolicy:\n    syncOptions:\n      - CreateNamespace=true\n    automated:\n      prune: true      # delete resources removed from Git\n      selfHeal: true   # revert manual cluster changes\n<\/code><\/pre>\n
The syncPolicy.automated<\/code> section is where people get tripped up \u2014 including me. selfHeal: true<\/code> means if someone manually edits a resource in the<\/a> cluster, ArgoCD will overwrite it back to match Git within a few minutes. This is usually what you want (it’s the whole point), but it can cause confusion if your team isn’t fully bought into the workflow yet. I’d recommend setting it to manual sync at first \u2014 just syncPolicy: {}<\/code> with no automated block \u2014 so you can watch how ArgoCD detects drift before letting it auto-correct.<\/p>\n
prune: true<\/code> is similarly powerful. If you remove a resource from your Git repo, ArgoCD will delete it from the cluster. I left this off initially because deleting production<\/a> resources automatically felt scary, and I wanted to review the prune operations manually first. Reasonable caution, in retrospect.<\/p>\n
The actual progression I’d suggest: start with no automated sync policy. Merge some changes to Git. Watch ArgoCD report “OutOfSync” in the<\/a> UI. Click sync manually. Get comfortable with what it’s showing you. After a week of that, turn on automated sync without prune. After another week, consider prune \u2014 but only if your team is actually<\/a> disciplined about removing stale resources from the repo.<\/p>\n
\n
Sync Policies, Health Checks, and the Stuff That Bit Me<\/h2>\n
ArgoCD has built-in health checks for common Kubernetes<\/a> resources \u2014 Deployments, StatefulSets, Services, Ingresses. It knows a Deployment is “Healthy” when its rollout finishes. That’s more useful than it might sound: you can see at a glance whether your deploy<\/a> actually completed or just got submitted to the API server.<\/p>\n
For custom resources (CRDs that ArgoCD doesn’t understand natively), it defaults to “Healthy” as soon as the resource exists \u2014 which is wrong if your custom resource has its own status conditions. You can write custom health check scripts in Lua if you need this. I needed it for a CertificateRequest resource from cert-manager, and the Lua API is actually<\/a> not bad once you figure out the shape of the object you’re working with.<\/p>\n
Here’s a mistake that genuinely cost me an afternoon. I had a Helm chart that generated some resources conditionally based on values. When I first synced it, ArgoCD showed the app as Synced and Healthy. Great. Then I changed a value that should have removed one of those conditional resources. I committed, pushed, ArgoCD synced \u2014 and the old resource was still there. Took me a while to realize: I hadn’t enabled prune: true<\/code>, and the old resource was just sitting there, orphaned, not causing any obvious issues but also not matching my intent.<\/p>\n
The other thing that surprised me was how ArgoCD handles Helm hooks. By default, ArgoCD runs Helm hooks during sync \u2014 and it treats the hook’s success or failure as part of the sync result. If you have a pre-upgrade<\/code> hook that runs a database migration and it fails, your entire sync fails and ArgoCD reports the app as degraded. This is actually<\/a> the correct behavior, but I’d been used to running migrations separately, and this forced me to think more carefully about hook design. Worth testing in staging first before you find out in prod.<\/p>\n
One more thing: private Git repos. You’ll need to add your repo credentials to ArgoCD via the UI (Settings \u2192 Repositories) or via a secret. For GitHub, I use a deploy<\/a> key (read-only SSH key) per repo \u2014 works reliably. Some teams use a GitHub App for broader access, which is probably the better call if you’re managing a lot of repos, but I haven’t gotten there yet.<\/p>\n
\n
Multi-Cluster and App-of-Apps (Once You Outgrow the Basics)<\/h2>\n
The setup I described above works fine for a few apps on one cluster. When I added a second cluster (staging), things got more interesting.<\/p>\n
ArgoCD runs in one cluster and can manage resources on other clusters. You register external clusters using the CLI:<\/p>\n
argocd cluster add my-staging-context --name staging\n<\/code><\/pre>\n
This installs a ServiceAccount and ClusterRole in the<\/a> target cluster, and stores the credentials in the<\/a> ArgoCD namespace. Which brings up an access control question: who can tell ArgoCD to deploy<\/a> to prod? By default, anyone with access to the argocd namespace can add clusters and deploy<\/a> anywhere. ArgoCD Projects let you restrict which repos can deploy<\/a> to which clusters \u2014 I set up separate projects for staging and prod with different teams having sync access to each.<\/p>\n
The “App of Apps” pattern is something I’d been skeptical of \u2014 sounds like needless indirection \u2014 but once we had 12+ applications, it made sense<\/a>. You create one Application that points to a directory of other Application manifests. ArgoCD syncs that, which creates all the child Applications, which then sync their actual workloads. The whole cluster state is defined declaratively in Git, including which applications exist. Removing an app means deleting its Application manifest from the repo, and ArgoCD handles the cleanup.<\/p>\n
I’m not going to pretend I have this perfectly figured out. The bootstrapping problem \u2014 how do you deploy<\/a> ArgoCD itself using ArgoCD? \u2014 is a real philosophical puzzle I resolved by keeping the ArgoCD install in a separate “platform” repo managed by Terraform. Maybe there’s a cleaner way.<\/p>\n
\n
What I’d Actually Recommend<\/h2>\n
If you’re starting from scratch with a small-to-medium Kubernetes<\/a> setup: install ArgoCD, point it at your existing Helm charts or plain manifests, and run in manual sync mode for two to four weeks. The sync diff view alone \u2014 seeing exactly what would change before you apply it \u2014 is worth the setup cost.<\/p>\n
Don’t turn on automated sync with self-healing and pruning on day one. Get your team comfortable with the mental model first. GitOps requires discipline: every cluster change goes through Git, full stop. If half your team is still running kubectl edit<\/code> for quick fixes, automated sync will feel hostile rather than helpful.<\/p>\n
The web UI is genuinely good for cluster visibility, but the real value I’ve gotten is audit trail and rollback. Every deployment is a Git commit. Rolling back is git revert<\/code>. Knowing exactly what changed between two states is git diff<\/code>. After years of<\/a> kubectl apply chaos, that’s worth a lot.<\/p>\n
One last thing: spend some time on the ArgoCD notifications controller if you want Slack or email alerts on sync failures. It’s a separate component, slightly under-documented, but once it’s set up you get instant alerts when an app goes OutOfSync or Degraded. The alternative is watching the UI all day, which nobody actually does.<\/p>\n
The two-week investment was worth it<\/a>. The Friday afternoon I pushed a bad config last month, I reverted the Git commit, ArgoCD detected the change within 30 seconds, and the old version was back up in<\/a> under two minutes. That’s the version of the story I prefer.<\/p>\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
I pushed a broken Helm chart on a Friday afternoon last October. Not my finest moment.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[1],"tags":[],"class_list":["post-155","post","type-post","status-publish","format-standard","hentry","category-general"],"_links":{"self":[{"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/posts\/155","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/comments?post=155"}],"version-history":[{"count":25,"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/posts\/155\/revisions"}],"predecessor-version":[{"id":514,"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/posts\/155\/revisions\/514"}],"wp:attachment":[{"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/media?parent=155"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/categories?post=155"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.rebalai.com\/en\/wp-json\/wp\/v2\/tags?post=155"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}