Coder Legion - Recent posts tagged argocd

How to manage releases and rollbacks with Argo CD in Octopus Deploy

Tue, 23 Jun 2026 12:52:41 +0000

Most teams say they can roll back, but far fewer have actually tried it.

When they actually do, the plan is typically a runbook in a wiki, or the fact that, in theory, we can always revert to the last working commit. When you run Kubernetes, Argo CD is instrumental in keeping your resources in sync.

Argo CD is good at reconciling whatever's in your Git repo to your cluster. When a deploy goes sideways, "roll back" turns into "revert the right commit, in the right repo, without breaking the other applications syncing alongside it", which is fine on paper and miserable in practice.

In this post, we'll explore how to manage releases in Octopus Deploy, how it integrates with Argo CD, and discuss, as well as implement, a rollback.

What Argo CD doesn't do (and why it matters)

Argo CD is great at one job: take whatever's in your Git repo and reconcile a cluster to match it. It'll show you what's drifted, when it last synced, and which resources are unhealthy.

However, what it deliberately doesn't do is anything above the cluster.

There's no concept of a release. Each Application is an independent entity, and its current state is whatever commit HEAD happens to be on. If Tuesday's image tag turns out to be a regression, your options are: revert the commit in Git and wait for the next reconcile, or open the Argo CD UI and sync to a previous revision by hand.

More importantly, the processes around what constitutes a release that can be synced are something Argo simply wasn't built for.

How Octopus manages releases with Argo CD

A release in Octopus is a versioned snapshot of three things:

the deployment process (the steps it runs)
the variables those steps use, and
the package or image versions they reference.

Once a release is created, it's frozen. You can promote 0.0.2 through Development, then Staging, then Production, and each environment receives the same release, not whatever happens to sit at HEAD when you trigger the deployment.

With the Argo CD integration, that release model integrates into your existing GitOps setup. When you deploy a release in Octopus, you can have an Argo CD step that rewrites the image tags in your repo, commits the change with the credentials you've attached, then asks Argo CD to sync. Argo CD keeps doing the reconciliation while Octopus keeps the lifecycle.

Prerequisites

This tutorial assumes you have:

A working Kubernetes cluster (any flavour)
kubectl installed and pointed at the cluster
The GitHub CLI (gh) installed and authenticated (gh auth login). We'll use it to create the demo repo in one command
An Octopus Cloud (or self-hosted) instance, with the Argo CD Gateway installed in the cluster and an Argo CD instance already registered against Octopus. If you haven't done that yet, follow the Connecting AWS EKS Argo CD to Octopus Cloud guide first; the same flow works for any cluster.
A Git Personal Access Token (PAT) scoped to your demo repository, Octopus will use it to push image-tag commits back

Step 1: Create the Octopus project

Sign in to Octopus and head to Projects > Add Project.
Give it a name (we'll use argo-demo), pick Kubernetes as the deployment target, and answer Yes to Are you using Argo CD?
Leave the lifecycle on Default Lifecycle.

Creating the argo-demo project.

Hit Create Project.

Step 2: Add the Argo CD step

You'll land on the Process editor.

Click Add Step and filter by Containers and Orchestration > Argo CD in the left sidebar. You'll see two installed step templates:
- Update Argo CD Application Image Tags, which updates an image tag in your manifests and commits the change for Argo CD to sync
- Update Argo CD Application Manifests, which generate manifests from templates using Octopus variables, and commit those.

We'll use the first one for this walkthrough.

The Argo CD category in the step picker. Both templates ship with Octopus once an Argo CD instance is registered.

Step 3: Set up the manifests repository

Argo CD syncs from Git, and Octopus pushes image-tag updates back to that same repo, so before either side has anything to do, we need a repository with a workload manifest in it.

We'll keep the layout small: one Deployment, one Service, and the Argo CD Application that wires the two systems together.

argocd-octopus-demo/
├── application.yaml      # the Argo CD Application (apply once to the cluster)
└── manifests/
    └── app.yaml          # workload Argo CD reconciles from this repo

Create the directory locally:

mkdir -p argocd-octopus-demo/manifests
cd argocd-octopus-demo

Write the workload manifest. We're using nginxdemos/hello:plain-text, a tiny nginx that responds with a text page naming the pod that served the request. It's a single-container app with no state, perfect for proving reconciliation worked end-to-end.

cat > manifests/app.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
  labels:
    app: hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: hello
          image: nginxdemos/hello:plain-text
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 25m
              memory: 32Mi
---
apiVersion: v1
kind: Service
metadata:
  name: hello
spec:
  type: ClusterIP
  selector:
    app: hello
  ports:
    - port: 80
      targetPort: 80
      protocol: TCP
EOF

Initialize the repo, create a public GitHub repo from it, and push the first commit:

git init -b main
git add .
git commit -m "chore: init"
gh repo create <your-org>/argocd-octopus-demo \
  --public \
  --description "Argo CD + Octopus Deploy demo manifests" \
  --source=. \
  --push

With the repo live, we can write the Argo CD Application that points at it.

Step 4: Scope the Argo CD Application with annotations

The Octopus gateway pulls the full list of Argo CD Applications from your cluster, but it doesn't yet know which of them belong to this Octopus project. You can tell it with three annotations on the Argo Application:

argo.octopus.com/project[.<source-name>]
argo.octopus.com/environment[.<source-name>]
argo.octopus.com/tenant[.<source-name>]

The .<source-name> suffix matches spec.source.name on the Application, which lets you scope different sources of a multi-source Application to different Octopus projects.

For our argo-demo project and Development environment, an annotated Application looks like this:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argo-demo
  namespace: argocd
  annotations:
    argo.octopus.com/project.argo-demo-source: argo-demo
    argo.octopus.com/environment.argo-demo-source: development
spec:
  project: default
  source:
    repoURL: https://github.com/<your-org>/argocd-octopus-demo.git
    targetRevision: HEAD
    path: manifests
    name: argo-demo-source
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

The two annotations there tie this Application to the argo-demo Octopus project, scoped to the development environment. The suffix .argo-demo-source matches the spec.source.name field below it.

Apply it:

kubectl apply -f application.yaml

Within a few seconds, the Octopus gateway picks up the new annotations, and the Application appears in the project's deployment preview.

Step 5: Preview the deployment

Back in Octopus, in the Process tab, click on the step you just added.

Octopus has discovered the argo-demo Application via the annotations

Annotations have been discovered, but flags that the source repo is missing Git credentials. Click View Applications to see what was matched.

The deployment preview opens. You should see the argo-demo application listed under the Rollback Argo CD instance, scoped to the Development environment, with the source repo URL underneath.

Step 6: Connect Git credentials

Octopus needs Git credentials so the step can push the new image-tag commit.

Click the Connect Git Credential dropdown next to the repo URL.

Two paths: spin up a new credential in Octopus from a PAT, or reuse one you've already attached to this space

Pick Create a new Git credential (or Connect an existing Git credential if you've already added one to the space).

Once the credential is attached, the warning on the deployment preview clears and the source shows up as ready to update.

Step 7: Configure the step

Back on the step, fill in the rest:

Confirm your step settings look good

The key fields:

Step Name, leave as the default unless you have multiple Argo CD steps in one process.
Container Images, click Add to declare which container image(s) this step should bump. You'll point it at a package/container reference so Octopus knows which image and which feed to pull tags from.
Git Commit Settings, the commit author/email Octopus uses when it pushes the tag update.
Commit Message, supports Octopus variables, so something like chore: bump image to #{Octopus.Action.Package[hello].PackageVersion} is a good default.

Save the step.

Step 8: Create a release

Head to the project dashboard, and you should now see the Create Release prompt.

The project dashboard once the deployment process has at least one step. Hit Create Release.

On the release form, give it a version (Octopus auto-suggests 0.0.1) and click Save.

Create release page

Release notes are optional but recommended for anything you'd want a changelog entry for later.

Step 9: Deploy to Development

Pick Deploy to Development on the release page. Octopus kicks off the deployment, and the task log streams the three sub-steps in real time:

Update Argo CD Application Image Tags, Octopus rewrites the image tag in the manifest and pushes the commit
Triggering Argo CD application syncs, Octopus asks Argo CD to sync the Application
Wait for Argo CD Application Health, Octopus polls the Application until it reports Healthy

When all three turn green, you'll see a completion line in the task log, and a Deploy to Staging… button appears at the top right, ready for the next environment in the lifecycle.

Deployment completes in just over 90 seconds

You can verify the rollout landed on the cluster side too:

kubectl -n default get deploy hello -o \
jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

Step 10: Rolling back: redeploying a previous release

The deploy half of the demo is done. The other half is the one that actually earns its keep: a release that turns out to be bad, and how Octopus takes you back to the previous one without anyone opening a terminal.

To simulate it, hit Create Release again, save as 0.0.3, and deploy it to Development. Imagine the new image is broken (regression, missing env var, whatever). To roll back, head to Releases in the project's left sidebar.

Every release Octopus has ever cut for this project, newest first. Each one is a versioned artifact you can revisit and redeploy. To roll back, open the last known-good release, 0.0.2

Click 0.0.2 to open it, then look at the lifecycle table. The Development row will show its previous deployment with a Redeploy… button.

Click Redeploy…, confirm, and the same three sub-steps run again.

Octopus rewrites the image tag in Git back to the one 0.0.2 used, commits it, asks Argo CD to sync, then waits until the Application reports Healthy.

When the task completes, the project dashboard shows 0.0.2 back in Development.

The dashboard after the rollback shows a healthy application.

When to roll back vs when to roll forward

For this demo, rolling back was a single click. That doesn't mean rolling back is always the right call. Rollbacks have a way of failing that isn't always talked about.

They assume the rest of the system is in a state that the old version can still talk to. Most of the time it is. Sometimes it very much isn't.

Take, for instance, a database. If a bad release adds a new column and your users have been generating data through that path for an hour, rolling the application code back doesn't unwind the schema or the data. The old app meets the new schema and either ignores fields it doesn't know about (best case) or crashes on them (worst case)

Refactoring databases buys you flexibility. If schema changes go in through additive, backward-compatible migrations (add columns nullable, write to both old and new fields for a release cycle, then drop the old in a later release), rollbacks stay safe much longer.

Make rollbacks boring

If you made it this far, you've got the full loop: an Argo CD Application scoped to an Octopus project with annotations, a deploy that flows from a click down through Git into your cluster, and a redeploy that takes you back to a known-good release the same way.

Argo CD keeps reconciling, your manifests stay the source of truth, and Octopus wraps versioning, approvals, audit, and that redeploy button around them. The rollback nobody had tested becomes a button two engineers know how to press.

Beyond manual rollbacks, Octopus enables you to build out full lifecycles on your deployments, so this can all be automated conditionally.

Extend the pipeline to your real environments using the Argo CD integration docs, or if you don't have an Octopus instance yet, start a free trial and run this end-to-end on your own cluster.

ArgoCD Guide: GitOps Continuous Delivery for Kubernetes

Thu, 23 Apr 2026 12:47:43 +0000

ArgoCD has become the de facto standard for GitOps-based continuous delivery in Kubernetes. If you are running production workloads on Kubernetes and still deploying with raw kubectl apply or untracked Helm releases, ArgoCD solves a class of problems you may not even know you have yet. This guide covers everything from core concepts to production-grade configuration.

The Problem ArgoCD Solves

Traditional CI/CD pushes deployments into a cluster. A CI system runs tests, builds an image, and then executes kubectl apply or helm upgrade against the cluster. This model has several structural problems:

Drift goes undetected. Someone applies a hotfix directly to the cluster. Now your Git repository no longer reflects reality, and nobody knows it.
No single source of truth. The cluster state is authoritative, not Git. Your desired state and actual state can diverge silently.
Rollback is painful. Rolling back a bad deployment means re-running old CI pipelines or manually reversing changes, neither of which is fast.
Multi-cluster management compounds the problem. Each cluster becomes a snowflake with its own history of undocumented changes.

GitOps inverts this model. Git is the source of truth. The cluster pulls its desired state from Git and continuously reconciles toward it. ArgoCD is the most mature GitOps operator for Kubernetes, implementing this pull-based model with a production-ready feature set.

How ArgoCD Works: Core Architecture

ArgoCD runs as a set of controllers inside your Kubernetes cluster. The core components are:

Application Controller — Watches both the Git repository and the live cluster state. Computes the diff and drives reconciliation.
API Server — Exposes the gRPC/REST API consumed by the CLI, UI, and external systems.
Repository Server — Generates Kubernetes manifests from source (Helm, Kustomize, plain YAML, Jsonnet).
Redis — Caches cluster state and repository data to reduce API server load.
Dex (optional) — Provides OIDC authentication for SSO integration.

The fundamental unit in ArgoCD is an Application — a CRD that maps a source (a path in a Git repo at a specific revision) to a destination (a namespace in a cluster). ArgoCD continuously compares the desired state from Git with the live state in the cluster and reports on the sync status.

Sync Status vs Health Status

Two orthogonal concepts you need to understand from day one:

Sync Status — Does the live state match what Git says it should be? Values: Synced, OutOfSync, Unknown.
Health Status — Is the application actually working? Values: Healthy, Progressing, Degraded, Suspended, Missing, Unknown.

An application can be Synced but Degraded — the manifests were applied correctly, but a pod is crash-looping. Conversely, it can be OutOfSync but Healthy — someone applied a change directly to the cluster outside of Git.

Installing ArgoCD

The official installation method uses a single manifest. For production, always pin to a specific version:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.11.0/manifests/install.yaml

This deploys ArgoCD in the argocd namespace with full cluster-admin access. For a production HA setup, use the manifests/ha/install.yaml variant, which deploys multiple replicas of the API server and application controller.

Accessing the UI and CLI

The initial admin password is auto-generated and stored in a secret:

argocd admin initial-password -n argocd

For local access, port-forward the API server:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Then log in via the CLI:

argocd login localhost:8080 --username admin --password <password> --insecure

For production, expose the ArgoCD server via an Ingress or LoadBalancer with a proper TLS certificate. If you’re using NGINX Ingress Controller:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: nginx
  rules:
  - host: argocd.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 443

Defining Your First Application

Applications can be created via the UI, the CLI, or declaratively with a YAML manifest. The declarative approach is the recommended one — it means your ArgoCD configuration itself is in Git:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/your-app
    targetRevision: HEAD
    path: k8s/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

Key fields to understand:

targetRevision — Can be a branch name, tag, or commit SHA. For production, pin to a tag rather than HEAD.
path — The directory within the repo containing your Kubernetes manifests.
automated.prune — Automatically delete resources that are no longer in Git. Required for true GitOps but use carefully — it will delete things.
automated.selfHeal — Automatically revert manual changes made directly to the cluster. This is what enforces Git as the single source of truth.

Helm Integration

ArgoCD has native Helm support. It can deploy Helm charts directly from chart repositories or from your Git repository. You can override values per environment:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: prometheus-stack
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://prometheus-community.github.io/helm-charts
    chart: kube-prometheus-stack
    targetRevision: 58.4.0
    helm:
      releaseName: prometheus-stack
      valuesObject:
        grafana:
          adminPassword: "${GRAFANA_PASSWORD}"
        prometheus:
          prometheusSpec:
            retention: 30d
            storageSpec:
              volumeClaimTemplate:
                spec:
                  storageClassName: fast-ssd
                  resources:
                    requests:
                      storage: 50Gi
  destination:
    server: https://kubernetes.default.svc
    namespace: observability

One important nuance: ArgoCD renders Helm charts server-side using its own templating engine, not helm install. This means Helm hooks (pre-install, post-upgrade, etc.) are supported, but the release is not tracked in Helm’s release history. Running helm list will not show ArgoCD-managed releases unless you configure ArgoCD to use the Helm secrets backend.

Projects: Multi-Tenancy and Access Control

ArgoCD Projects provide multi-tenancy within a single ArgoCD instance. They let you restrict which source repositories, destination clusters, and namespaces a team can deploy to. Every Application belongs to a Project.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: platform-team
  namespace: argocd
spec:
  description: Platform team applications
  sourceRepos:
  - 'https://github.com/your-org/*'
  destinations:
  - namespace: 'platform-*'
    server: https://kubernetes.default.svc
  clusterResourceWhitelist:
  - group: ''
    kind: Namespace
  namespaceResourceBlacklist:
  - group: ''
    kind: ResourceQuota

Projects are where you define the boundaries of what each team can do. The default project has no restrictions — never use it for production workloads. Create dedicated projects per team or per environment.

RBAC Configuration

ArgoCD has its own RBAC system layered on top of Kubernetes RBAC. It is configured via the argocd-rbac-cm ConfigMap. Roles are defined per project or globally:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly
  policy.csv: |
    # Platform team has full access to platform-team project
    p, role:platform-admin, applications, *, platform-team/*, allow
    p, role:platform-admin, projects, get, platform-team, allow
    p, role:platform-admin, repositories, *, *, allow

    # Dev team can sync but not delete
    p, role:developer, applications, get, */*, allow
    p, role:developer, applications, sync, */*, allow
    p, role:developer, applications, action/*, */*, allow

    # Bind SSO groups to roles
    g, your-org:platform-team, role:platform-admin
    g, your-org:developers, role:developer

The policy.default: role:readonly ensures that any authenticated user who has no explicit role assignment gets read-only access — a safe default for production.

Multi-Cluster Management

ArgoCD can manage multiple Kubernetes clusters from a single control plane. Register external clusters with the CLI:

# First, ensure the target cluster context is in your kubeconfig
argocd cluster add production-eu-west --name production-eu-west

# Verify registration
argocd cluster list

ArgoCD will create a ServiceAccount in the target cluster and store its credentials as a Kubernetes secret in the ArgoCD namespace. Applications can then target this cluster by name in their destination.server field.

For large-scale multi-cluster setups, consider the App of Apps pattern or ApplicationSets. ApplicationSets are a controller that generates Applications dynamically based on generators — cluster lists, Git directory structures, or matrix combinations:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
  namespace: argocd
spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
  template:
    metadata:
      name: '{{name}}-addons'
    spec:
      project: platform
      source:
        repoURL: https://github.com/your-org/cluster-addons
        targetRevision: HEAD
        path: 'addons/{{metadata.labels.region}}'
      destination:
        server: '{{server}}'
        namespace: kube-system

This single ApplicationSet deploys the appropriate addons to every cluster labeled environment: production, using each cluster’s region label to select the correct path in the repository.

Sync Strategies and Waves

When deploying complex applications with dependencies between resources, you need to control the order of deployment. ArgoCD provides two mechanisms:

Sync Phases

Resources are deployed in three phases: PreSync, Sync, and PostSync. Use Sync Hooks for resources that must complete before the main sync proceeds (database migrations, certificate issuance, etc.):

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: your-app:v1.2.3
        command: ["./migrate.sh"]
      restartPolicy: Never

Sync Waves

Within the Sync phase, waves control ordering. Resources with a lower wave number are applied and must become healthy before resources with higher wave numbers are applied:

# Applied first
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"

# Applied after wave 1 is healthy
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "2"

Notifications and Alerting

ArgoCD Notifications is a standalone controller that sends alerts when Application state changes. It supports Slack, PagerDuty, GitHub commit status, email, and a dozen other providers. Configure it via the argocd-notifications-cm ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.slack: |
    token: $slack-token
  template.app-sync-failed: |
    slack:
      attachments: |
        [{
          "title": "{{.app.metadata.name}}",
          "color": "#E96D76",
          "fields": [{
            "title": "Sync Status",
            "value": "{{.app.status.sync.status}}",
            "short": true
          },{
            "title": "Message",
            "value": "{{range .app.status.conditions}}{{.message}}{{end}}",
            "short": false
          }]
        }]
  trigger.on-sync-failed: |
    - when: app.status.sync.status == 'Unknown'
      send: [app-sync-failed]
    - when: app.status.operationState.phase in ['Error', 'Failed']
      send: [app-sync-failed]

Secret Management with ArgoCD

ArgoCD intentionally has no secret management built in — storing secrets in Git as plain text is never acceptable. The common patterns are:

Sealed Secrets (Bitnami) — Encrypts secrets with a cluster-specific key. The encrypted secret can be committed to Git; only the cluster can decrypt it.
External Secrets Operator — Syncs secrets from Vault, AWS Secrets Manager, GCP Secret Manager, etc. into Kubernetes secrets. The ArgoCD Application manages the ExternalSecret CRD, not the actual secret value.
argocd-vault-plugin — A plugin that replaces placeholder values in manifests with secrets retrieved from Vault at sync time.

The External Secrets Operator approach is the most flexible for teams already using a centralized secrets backend. The Application in ArgoCD deploys ExternalSecret objects, which the ESO controller resolves at runtime without ever touching Git.

Production Best Practices

Run ArgoCD in HA mode. Use manifests/ha/install.yaml with 3 replicas of the API server and multiple application controller shards for large clusters (100+ applications).
Pin image versions. Never use latest for the ArgoCD image itself. Pin to a specific version and upgrade deliberately.
Use the App of Apps pattern for bootstrapping. A single root Application deploys all other Applications. This makes cluster bootstrapping idempotent and reproducible.
Separate ArgoCD config from application config. Store ArgoCD Application manifests in a dedicated gitops repository, separate from application source code.
Enable resource tracking via annotations. Use application.resourceTrackingMethod: annotation in argocd-cm instead of the default label-based tracking, which can conflict with Helm’s own labels.
Set resource limits on ArgoCD controllers. Application controller CPU and memory scale with the number of resources tracked. Monitor and tune accordingly.
Restrict auto-sync in production. Consider requiring manual sync approval for production environments even when using GitOps — or at minimum require a PR approval gate before changes reach the target branch.

ArgoCD vs Flux

Flux v2 is the other major GitOps operator. Both are CNCF projects. The main differences in practice:

Feature	ArgoCD	Flux v2
UI	Built-in web UI	No official UI (use Weave GitOps)
Multi-cluster	Single control plane manages many clusters	Agent per cluster, pull model
ApplicationSets	Native	Kustomization + HelmRelease
Secret management	Plugin-based	SOPS native integration
Learning curve	Steeper (more concepts)	Lower (Kubernetes-native CRDs)
CNCF status	Graduated	Graduated

ArgoCD wins when you need the UI, multi-cluster management from a central plane, or have a large operations team that benefits from the visual application topology view. Flux wins when you want a simpler, purely Kubernetes-native approa

Stop Manually Editing GitOps Files: ArgoCD Image Updater on Kubernetes

Wed, 08 Apr 2026 10:55:08 +0000

Stop Manually Editing GitOps Files: ArgoCD Image Updater on Kubernetes

Every time a developer pushes new code, someone has to manually update the image tag in the GitOps repo. ArgoCD then deploys it. Sound familiar? Let’s fix that.

The Problem

If you’re running ArgoCD with a GitOps setup, you’ve probably experienced this pain:

Developer pushes code
CI (Jenkins/Gitlab) builds and pushes a new image to the registry
Someone (u/me/dev) manually edits the image tag in the GitOps repo
ArgoCD detects the change and deploys it.

What is ArgoCD Image Updater?

ArgoCD Image Updater automatically watches your container registry for new image tags and updates your ArgoCD applications without any manual intervention. When a new image is pushed, it detects the change and triggers a deployment without manual interventions.

Prerequisites

Before we begin, please ensure you have:

An EKS cluster running
kubectl configured
helm installed
A container registry (DockerHub, ECR, GitLab Registry etc.)
A GitHub/GitLab repo for your GitOps values

Step 1 — Install ArgoCD on EKS

First, create the ArgoCD namespace and install it:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

If you see a CRD annotation size error, apply the server-side flag:

kubectl apply --server-side -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Access the ArgoCD UI:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Retrieve the initial admin password by opening another terminal:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d && echo

Use this password to log in.

Step 2 — Understanding the Multisource Pattern

In real-world GitOps setups, ArgoCD applications often use multiple sources:

Source 1 — The Helm chart from a Helm registry (e.g., Bitnami, your internal registry)
Source 2 — The values files from your GitOps repository

This is a clean separation — the chart is versioned independently from your environment configuration.

Here’s what a multisource ArgoCD application looks like:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-sample
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  sources:
    - repoURL: https://charts.bitnami.com/bitnami
      chart: nginx
      targetRevision: 21.0.5
      helm:
        releaseName: nginx-sample
        valueFiles:
          - $values/values/values.yaml
    - repoURL: https://github.com/AlexyPulivelil/gitops-sample.git
      targetRevision: main
      ref: values
  destination:
    server: https://kubernetes.default.svc
    namespace: nginx-sample
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

The values.yaml file typically looks like this:

replicaCount: 1
service:
  type: ClusterIP
  port: 80
image:
  registry: docker.io
  repository: repository/nginix
  tag: "10.0"
  pullPolicy: Always

We are addressing the issue of manually updating these tags on every deployment.

Step 3 — Why ArgoCD Image Updater Old Version Won’t Work Here

(skip this if having single source.)

I tried 0.12.2 initially

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/v0.12.2/manifests/install.yaml

And add annotations to your ArgoCD Application:

annotations:
  argocd-image-updater.argoproj.io/image-list: myapp=myregistry/myapp
  argocd-image-updater.argoproj.io/myapp.update-strategy: latest

And if you check logs you could see

level=warning msg="skipping app 'nginx-sample' of type '' 
because it's not of supported source type"

v0.12.2 does not support multisource ArgoCD applications. It uses annotations on the Application resource and relies on detecting the source type, which fails for multisource apps.

NB: If working on single source, this would be sufficient

This limitation is why we need v1.1.1.

Step 4 — Install ArgoCD Image Updater v1.1.1

v1.1.1 introduces a CRD based approach — instead of annotations on the ArgoCD Application, you create a dedicated ImageUpdater custom resource. This completely solves the multisource problem.

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/v1.1.1/config/install.yaml

Verify the controller is running:

kubectl get pods -n argocd | grep image-updater-controller

Grant the controller permissions to access ArgoCD applications:

kubectl create clusterrolebinding image-updater-binding \
  --clusterrole=cluster-admin \
  --serviceaccount=argocd:argocd-image-updater-controller \
  -n argocd

Note: For production, scope down the permissions using a dedicated ClusterRole instead of cluster-admin.

Step 5 — Create the ImageUpdater CR

This is the key difference in v1.1.1. Instead of annotating your ArgoCD Application, you create a separate ImageUpdater resource:

apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata:
  name: nginx-sample-updater
  namespace: argocd
spec:
  applicationRefs:
    - namePattern: "nginx-sample"
      images:
        - alias: nginx
          imageName: your-registry/nginx-sample-image
          commonUpdateSettings:
            updateStrategy: newest-build
            forceUpdate: true
          manifestTargets:
            helm:
              tag: image.tag
              name: image.repository

What each field means:

namePattern Which ArgoCD application to watch

imageName Which image to monitor in the registry

updateStrategy How to pick the new tag (newest-build, semver, alphabetical)

forceUpdate Update even if image isn't directly referenced in app status

manifestTargets.helm.tag Which Helm value holds the image tag

manifestTargets.helm.name Which Helm value holds the image repository

Apply it:

kubectl apply -f imageupdater-cr.yaml

NB: The apply order should be

# First the ImageUpdater CR
kubectl apply -f argocd/image-updater-cr.yaml
# Then the ArgoCD Application
kubectl apply -f argocd/application.yaml

Now push a new image tag:

docker tag your-dockerhub/nginx:1.0 your-dockerhub/nginx:2.0
docker push your-dockerhub/nginx:2.0

Watch the magic happen in the logs♂️

kubectl logs -f deployment/argocd-image-updater-controller -n argocd

You’ll see

msg="Setting new image to your-dockerhub/nginx:2.0"
msg="Successfully updated image to your-dockerhub/nginx:2.0"
msg="Successfully updated application spec for nginx-sample"
msg="images_updated=1"

Zero manual editing. Fully automated.

Key Features

Multiple Update Strategies:

newest-build Always pick the most recently pushed tag

semver Follow semantic versioning constraints e.g. ~1.29

alphabetical Pick the last tag alphabetically

digest Track by image digest

One CR Per Application:

Each ArgoCD Application gets its own ImageUpdater CR. This gives you fine-grained control — each service can have a different update strategy, different registry credentials, and different tag filters.

Write-back Methods:

argocd (default) Updates ArgoCD application parameters directly via API

git Commits the tag change back to your GitOps repo

For true GitOps, use the git write-back method so every deployment change is tracked in Git.

Limitations

Being transparent about limitations is important before adopting any tool in production:

1. One CR per Application: Every ArgoCD Application needs its own ImageUpdater CR. In large setups with many services these requirements can become a lot of CRs to manage.

2. argocd write-back overrides values.yaml: When using the default argocd write-back method, Image Updater sets a parameter override directly on the ArgoCD Application. This takes priority over your values.yaml file. If you manually edit values.yaml, it won't take effect. Use git write-back to avoid this.

3. Registry rate limiting: Image Updater polls the registry every 2 minutes by default. On DockerHub's free tier this can hit rate limits, especially in teams with many services. Configure credentials or use webhooks for instant updates.

4. newest-build picks by push timestamp If you push tags out of order (e.g., push 9.0 after 10.0), Image Updater will pick 9.0 because they were pushed more recently. Use semver strategy to avoid this.

5. No conflict resolution between multiple CRs If two ImageUpdater CRs accidentally target the same ArgoCD Application, they will continuously overwrite each other, causing the application to flip between versions. ensure that only one CR targets each application.