Home · About · Services · Industries · Projects · Products · Process · Blog · Glossary · FAQ · Contact
GitOps with Argo CD for a small cluster: a practical setup A practical GitOps setup for a small Kubernetes cluster: repository layout, Argo CD applications, secrets handling and promotion from staging to production.
A product team runs a small Kubernetes cluster with staging and production namespaces. Deployments happen when an engineer runs kubectl apply from their laptop, using manifests from whichever branch they have checked out. One Friday, a hotfix goes to production with a staging database URL, because the engineer’s local copy had an uncommitted change. Nobody can say exactly what is running in the cluster, or who changed it last.
GitOps fixes this by making a Git repository the only source of truth for what runs in the cluster. An agent inside the cluster, here Argo CD, watches the repository and applies changes, then keeps the cluster matching Git. People change the cluster by merging pull requests, not by running kubectl. For a small team, the setup takes a day or two: a config repository with Kustomize overlays, Argo CD installed in the cluster, one Application per environment, and a promotion flow based on pull requests.
What changes when you adopt GitOps The workflow shifts in a few specific ways.
Deployments are pull requests. Reviewing, approving and auditing a release uses the same tools as reviewing code. The cluster pulls changes. CI no longer needs cluster admin credentials, which removes a sensitive secret from your pipeline. Drift is visible. If someone changes a resource by hand, Argo CD shows it as out of sync and can revert it. Rollback is a revert commit. The previous state is in Git history. Rebuilding a cluster is repeatable. Point a fresh Argo CD at the same repository and it recreates everything it manages. What does not change: you still build and test container images in CI. GitOps covers deploying them, not building them.
Repository layout Keep application source code and deployment configuration in separate repositories. Application CI then updates the config repository with new image tags, and the config history reads as a clean deployment log.
For a small cluster, Kustomize with a base and one overlay per environment is enough. Helm also works with Argo CD, but Kustomize keeps plain YAML visible and diffs readable.
k8s-config/
apps/
api/
base/
deployment.yaml
service.yaml
ingress.yaml
kustomization.yaml
overlays/
staging/
kustomization.yaml
patch-replicas.yaml
config.env
production/
kustomization.yaml
patch-replicas.yaml
config.env
worker/
base/ ...
overlays/ ...
argocd/
projects/
product.yaml
applications/
api-staging.yaml
api-production.yaml
worker-staging.yaml
worker-production.yaml
root.yamlThe production overlay sets the image tag, replica count and environment-specific configuration:
# apps/api/overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: production
resources:
- ../../base
images:
- name: registry.example.com/api
newTag: "1.14.2"
patchesStrategicMerge:
- patch-replicas.yaml
configMapGenerator:
- name: api-config
envs:
- config.envPin images to immutable tags or digests, never latest. A GitOps repository with latest tags no longer describes what is running.
Installing Argo CD Install Argo CD into its own namespace using the official manifests, then get the initial admin password.
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d
# access the UI locally, or expose it through your ingress with TLS
kubectl -n argocd port-forward svc/argocd-server 8080:443Pin the manifest URL to a specific release tag in your own records, rather than stable, so upgrades are deliberate. After first login, change the admin password or disable the admin account and configure SSO through Dex or an OIDC provider.
Give Argo CD read-only access to the config repository with a deploy key. It never needs write access.
Defining applications An Argo CD Application connects a path in Git to a destination namespace. Create one per app per environment.
# argocd/applications/api-production.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: api-production
namespace: argocd
spec:
project: product
source:
repoURL: git@github.com:example/k8s-config.git
targetRevision: main
path: apps/api/overlays/production
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=trueprune removes resources deleted from Git. selfHeal reverts manual changes in the cluster. For production, some teams keep automated sync off and click Sync after reviewing the diff. That is a reasonable choice while the team builds confidence.
Rather than applying each Application by hand, use the app of apps pattern. A single root Application points at the argocd/applications folder. Adding a new application is then a matter of committing a new file.
# argocd/root.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: root
namespace: argocd
spec:
project: default
source:
repoURL: git@github.com:example/k8s-config.git
targetRevision: main
path: argocd/applications
destination:
server: https://kubernetes.default.svc
namespace: argocd
syncPolicy:
automated: { prune: true, selfHeal: true }An AppProject restricts what applications in it can deploy, such as which namespaces and which cluster-scoped resources. Use one to prevent a staging application from writing into the production namespace by mistake.
Secrets without committing secrets Plain Kubernetes Secrets are only base64 encoded, so they must not go into Git as they are. Common options for a small cluster:
Sealed Secrets: encrypt secrets with the cluster’s public key. Only the controller in the cluster can decrypt them. Encrypted files are safe to commit. SOPS with age or a cloud KMS: encrypt values in YAML files. Argo CD needs a plugin or a tool like KSOPS to decrypt during rendering. An external secrets operator: store secrets in AWS Secrets Manager, Vault or similar, and commit only a reference to them. Sealed Secrets is the simplest to start with. Back up the controller’s private key, because losing it means re-sealing every secret.
Promotion from staging to production With overlays, promotion is a change to the production overlay’s image tag, made through a pull request.
Application CI builds an image, tags it with the commit SHA or a version, and pushes it to the registry. CI opens a commit or pull request updating the staging overlay with the new tag. Staging syncs automatically. After testing in staging, someone opens a pull request copying the same tag to the production overlay. A reviewer approves, the pull request merges, and Argo CD syncs production. # in CI, after pushing the image
cd k8s-config/apps/api/overlays/staging
kustomize edit set image registry.example.com/api=registry.example.com/api:${GIT_SHA}
git commit -am "api: deploy ${GIT_SHA} to staging"
git pushProtect the main branch so production overlays can only change through reviewed pull requests. The pull request history then becomes your release log, with an author, a reviewer and a timestamp for every production change.
Day-to-day operations Once applications are syncing, a few habits keep the setup healthy.
Watch application health, not just sync status. An application can be in sync with Git and still be degraded, for example when pods crash on start-up. Argo CD reports both. Route notifications for failed syncs and degraded health to the team’s chat channel, using Argo CD Notifications or your existing alerting.
Order dependent resources with sync waves. A database migration Job can run before the Deployment that needs the new schema, by giving it an earlier wave annotation or making it a PreSync hook. This keeps the whole release in Git rather than in a separate manual step.
Handle emergencies through Git as well. When production breaks, the fastest safe action is usually a revert commit on the production overlay. If someone must change the cluster directly during an incident, turn off self-heal for that application first, then bring Git back in line afterwards and re-enable it. Otherwise Argo CD will quietly undo the fix.
Finally, upgrade Argo CD itself on a schedule. Read the release notes, upgrade staging first if you run a separate cluster, and keep the installation manifests in the same config repository so the upgrade is also a reviewed change.
Getting started checklist Create a config repository with a base and an overlay per environment for each application. Pin image tags, and remove latest from all manifests. Install Argo CD, secure the admin account, and give it a read-only deploy key. Define an AppProject per team or product, and an Application per app and environment, managed by a root application. Choose a secrets approach and move every secret out of plain YAML. Automate image tag updates for staging, and promote to production by pull request. Remove cluster admin credentials from laptops and CI once Argo CD is managing everything. That last step is the one that makes GitOps stick. While kubectl apply still works from a laptop, someone will use it under pressure.
Infigini IT Services · GSTIN 05AAIFI1118B1Z3 · 11 Shree Ram Puram Lane No.2, Kanwali Road, Dehradun, Uttarakhand 248001, India · info@infigini.com · +91 95684 87789 · LinkedIn