DevopsTechnology

Kubernetes CI/CD with Argo CD: A GitOps Deployment Guide

Updated on
9 min read

Kubernetes CI/CD combines automated build and test pipelines with a dependable way to release declarative changes to a cluster. Argo CD handles the delivery side: it watches configuration in Git, compares that desired state with Kubernetes, and can synchronize the cluster when they differ. This guide explains the architecture, safe promotion and rollback practices, and a practical starting configuration.

What Is Kubernetes CI/CD with Argo CD?

Kubernetes is the container orchestration platform that runs workloads; CI/CD is the process that validates and delivers changes. Argo CD is a declarative continuous-delivery controller for Kubernetes. It treats a Git repository as the desired configuration for an application and reports how that configuration compares with the live cluster.

In a common GitOps workflow, a CI system builds and tests application code, publishes an immutable image, and proposes a change to the deployment configuration. After review and merge, Argo CD observes that configuration and reconciles the cluster. This separates artifact creation from deployment while keeping the production change reviewable in Git.

Why Separate CI and CD?

A pipeline that pushes directly to a cluster needs credentials capable of changing production resources. Those credentials can be difficult to scope and rotate, and the resulting change may not be represented by a reviewed configuration commit. Direct pushes can also leave the cluster different from the files the team believes it deployed.

With GitOps, the CI system can focus on tests and artifact publishing while the in-cluster delivery controller reads approved desired state. Git history, pull requests, and policy checks provide a record of intended changes. This does not make a deployment automatically safe: the repository still needs access controls, validation, and a tested recovery plan. The OpenGitOps principles describe the broader declarative and continuously reconciled model.

How Argo CD Works: Architecture and Reconciliation

An Argo CD Application resource connects a source (such as a Git repository and directory) to a destination cluster and namespace. Argo CD’s repository service fetches the source and renders supported configuration such as plain Kubernetes manifests, Kustomize overlays, or Helm charts. Its application controller compares the rendered resources with live Kubernetes objects and reports differences and health.

Code change -> CI tests and image build -> image registry -> reviewed configuration change in Git -> Argo CD renders and compares desired state -> sync applies resources -> Kubernetes controllers converge workloads -> health and metrics verify the rollout.

Argo CD can refresh application state as repository changes arrive; a webhook can reduce the time before a refresh, while periodic refresh remains useful. A detected difference makes an application OutOfSync. A sync operation applies the desired resources, but application health is evaluated separately: a successful apply does not prove that the new version serves traffic correctly.

By default, a sync is an explicit operation. Automated sync can apply repository changes without a person pressing the sync button. prune allows Argo CD to delete managed resources removed from the source, and selfHeal allows it to correct live changes that diverge from Git. These options change the impact of a bad commit or an accidental edit, so enable them deliberately and protect the source branch.

Kubernetes Deployments then manage ReplicaSets and Pods according to their rollout strategy and readiness checks. Argo CD reports the state of those resources; it is not itself a traffic-splitting or progressive-rollout controller. For cluster control-plane fundamentals, see Kubernetes architecture explained.

Components and Delivery Patterns

Approach How it delivers Advantages Trade-offs
Argo CD A controller in or near the cluster reconciles one or more Git sources to Kubernetes resources. Application-oriented view, diff and health status, UI and CLI, and support for multiple configuration formats. Requires operating and securing the controller; repository layout and permissions need care.
Flux Kubernetes controllers reconcile Git sources and resources through declarative APIs. Composable controllers and a Kubernetes-native configuration model. Teams should assess the interfaces and operational model that fit their platform.
Push-based CI deployment A pipeline authenticates to the cluster and applies changes directly. Straightforward for a small system or a controlled deployment job. CI holds cluster credentials and deployment state may be less clearly represented by Git.

Argo CD and Flux are GitOps delivery controllers, not substitutes for CI testing. Helm is a packaging and templating format that Argo CD can render; Argo CD’s reconciliation is not the same as using Helm as an imperative release manager. Argo CD’s Helm documentation explains its chart integration.

Use ordinary Kubernetes Deployments for standard rolling updates. For traffic-weighted canaries, blue/green promotion, or metric-driven analysis, a progressive-delivery controller such as Argo Rollouts adds capabilities beyond Argo CD’s resource synchronization.

Real-World Use Cases

  • Application releases: CI builds an image, and a reviewed change updates the image reference in a deployment repository. Argo CD deploys the merged configuration.
  • Environment promotion: Separate overlays or configuration revisions represent development, staging, and production. Promote a tested image digest through a reviewed change instead of rebuilding a different artifact for each environment.
  • Cluster configuration: Platform teams can manage namespaces, policies, and shared services declaratively, with projects and repository permissions limiting which sources can target which destinations.
  • Drift detection: Teams can spot a manual change that diverges from the declared configuration and decide whether to restore the Git state or commit the intended change.

These workflows are useful when teams need repeatable releases and an auditable desired state. They are less suitable when a change must happen outside the repository by design, when the team cannot safely operate a delivery controller, or when a workload’s release process depends on irreversible actions that cannot be represented and validated declaratively.

Practical Guide: A Safe Argo CD Workflow

For a disposable learning cluster, the upstream installation guide documents the supported installation choices. A manifest-based quick start looks like this:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl port-forward svc/argocd-server -n argocd 8080:443

The port-forward is for local access, not a production exposure pattern. For a production installation, pin and review a release, configure trusted TLS and identity, protect the Argo CD namespace, and follow the project’s operational guidance.

An Application can point Argo CD at a directory containing Kubernetes manifests. Replace the example repository, branch, and path with values from your own configuration repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: storefront-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/platform-config.git
    targetRevision: main
    path: apps/storefront/overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: storefront-dev
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

This example assumes the repository is accessible to Argo CD and the selected project permits that source, destination, and resource set. For a first test, review the diff and sync manually before enabling automation. With prune enabled, removing a resource definition from the configured path can delete the corresponding managed resource; protect important data and test the behavior in a non-production namespace.

A practical release sequence is:

  1. CI runs unit, integration, manifest, and policy checks. It builds the application once and publishes an immutable image tag or digest.
  2. Automation or a maintainer updates the image reference in the environment’s configuration and opens a pull request. Review the rendered change and any environment-specific settings.
  3. After required checks and approval, merge the pull request. Argo CD refreshes the source and reports whether the application is in sync and healthy.
  4. Verify the actual rollout using application health, Kubernetes events, service-level metrics, and a smoke test. Pause promotion if the health checks fail.
  5. To recover from a bad configuration change, revert the Git commit and let Argo CD reconcile the reverted state. Confirm that the prior image is still available and that database or external side effects are reversible.

Useful diagnostics include argocd app get storefront-dev for application status, argocd app diff storefront-dev for the desired/live difference, and kubectl -n storefront-dev get deploy,pods for workload state. When automated sync is enabled, use Git as the normal change and rollback interface instead of applying a one-off correction to the live object.

Keep credentials out of manifests. Do not commit plaintext Kubernetes Secret values to an ordinary Git repository. Use an external secret manager or a reviewed encrypted-secret workflow, and keep decryption credentials outside the repository with narrowly scoped access. Limit Argo CD project sources, destinations, and resource permissions; also protect repository branches and restrict who can change application configuration. If your workloads require Windows nodes, account for node scheduling and image compatibility as described in the Windows containers guide.

For a broader comparison of rollout approaches, including when to use rolling, blue/green, or canary delivery, see Kubernetes deployment strategies.

Common Misconceptions

  • “Argo CD builds and tests my code.” It delivers Kubernetes configuration. CI remains responsible for tests, image creation, and supply-chain checks.
  • “GitOps guarantees the cluster is always correct.” Controllers can fail, permissions can be insufficient, and a desired state can itself be unhealthy or unsafe. Reconciliation and health reporting make discrepancies visible; they do not replace monitoring or review.
  • “A green sync means the release is good.” Sync status describes configuration application, while health, readiness, service-level indicators, and user-facing tests describe runtime behavior.
  • “Rollback is just pressing a button.” With automated sync enabled, a Git revert is the durable way to restore a previous desired state. A rollback cannot undo incompatible database migrations, external side effects, or a removed image.
  • “prune and selfHeal are harmless defaults.” Pruning can delete resources and self-healing can overwrite a deliberate live edit. Understand resource ownership and test these controls before enabling them broadly.
  • “Argo CD provides canary traffic shifting.” It synchronizes resources. Use a service mesh, ingress capability, or a progressive-delivery controller when releases need weighted traffic and metric-based promotion.
TBO Editorial

About the Author

TBO Editorial writes about the latest updates about products and services related to Technology, Business, Finance & Lifestyle. Do get in touch if you want to share any useful article with our community.