Manual Deployments to Argo CD GitOps Blueprint

What and Why

Manual deployments to Kubernetes are deploys run by hand: engineers apply manifests with kubectl, run ad-hoc Helm upgrades, or trigger imperative scripts from a laptop or a CI job that pushes directly into the cluster. The cluster's real state diverges from any file in Git, rollbacks are guesswork, and there is no audit trail of who changed what or when. Outages caused by undocumented manual changes are common and hard to diagnose.

GitOps with Argo CD fixes this by making Git the single source of truth. A declarative description of the desired cluster state lives in a Git repository; Argo CD runs inside the cluster, continuously reconciles the cluster toward that state, and reports drift between desired and live state. Deploys become pull requests, and rollbacks become Git reverts. This gives a complete, reviewable history of every change and a clear, fast recovery path.

Phases

Assessment. Catalogue every deployable workload, the current deploy mechanism, and where configuration lives today. Identify environments (dev, staging, production), the clusters behind them, and the secrets each needs. Record manual steps that are not yet codified, and note any out-of-band changes that have crept into running clusters. Establish a baseline for deployment frequency and recovery time.

Design. Choose a repository layout. A common pattern is one config repo per team or a monorepo of environment overlays using Kustomize or Helm. Decide on the app-of-apps or ApplicationSet pattern to manage many applications and many clusters from a single definition. Plan secret handling with Sealed Secrets, External Secrets Operator, or a Vault integration so plaintext secrets never enter Git. Define the promotion flow between environments and the branch or directory structure that represents it.

Bootstrap. Install Argo CD, wire up single sign-on and role-based access control (RBAC), and create the first Application pointing at the config repo. Validate sync, health checks, sync waves, and automated versus manual sync policies. Configure notifications so the team sees sync failures.

Migration. Move workloads in waves, lowest-risk first. For each app, render its current live state into declarative manifests, commit them, and let Argo CD adopt the resources. Enable self-heal and pruning only after a confidence period so a mistaken commit cannot wipe resources prematurely. Connect CI so image builds update the config repo (a tag bump committed by the pipeline) rather than deploying directly.

Hardening. Turn on automated sync with self-heal, configure sync waves and resource hooks for ordered rollouts (databases before apps), and add drift alerts. Lock down who can merge to the config repo, since merge equals deploy, and require reviews and status checks. Add Argo Rollouts for canary or blue-green strategies on critical services.

Key Risks and Mitigations

• Configuration drift during adoption. Live resources may not match committed manifests. Use Argo CD's diff view to reconcile before enabling auto-sync, and import real state with tools like kubectl get -o yaml cleaned of runtime fields.
• Secret handling. Plaintext secrets must never be committed. Adopt External Secrets Operator or Sealed Secrets, scan the repo history, and rotate any secret that ever appeared in plaintext.
• Blast radius. A bad merge can roll out everywhere at once. Use sync waves, progressive rollouts, environment-scoped Applications, and branch protection with required reviews on the config repo.

Recommended Tooling

Argo CD for reconciliation, Helm or Kustomize for templating, External Secrets Operator for secret injection, and a CI system (GitHub Actions or similar) to build images and update the config repo. Pair with Argo Rollouts for canary and blue-green strategies and Argo CD Notifications for alerting.

Success Metrics

Measure deployment frequency, mean time to recovery (MTTR) via Git revert, change failure rate, and time-to-detect for drift. GitOps should raise frequency while lowering failure rate.

Prerequisites

A working Kubernetes cluster, container images in a registry, a Git host with branch protection, single sign-on for Argo CD, and a chosen secrets management approach.