Skip to content

Onboard an Application into GitOps with Argo CD

This HOWTO shows how to onboard an application into GitOps using Argo CD on an RKE2 cluster in HybridOps.Studio.

You will:

  • Model an application with a clean Git structure for environments.
  • Create an Argo CD Application that points at those manifests.
  • Trigger a deployment by changing Git, not by running kubectl manually.

It aligns with:

1. Objectives

By the end of this HOWTO you will be able to:

  • Structure application manifests in Git for dev / staging / prod (or equivalent).
  • Create an Argo CD Application targeting your RKE2 cluster.
  • Deploy and update the application by changing Git only.
  • Capture basic evidence of GitOps behaviour for HybridOps.Studio.

2. Prerequisites

2.1 Platform

You should have:

  • An RKE2 cluster running, as per Evidence 4.
  • Argo CD deployed and reachable (CLI and/or UI).
  • A container registry you can push images to (or an existing public image).

2.2 Git and repository

  • A Git repository that will hold your application manifests.
  • Access to the HybridOps.Studio repo or a separate demo repo, depending on how you want to present the app.

2.3 Access to Argo CD

  • Argo CD credentials with permission to create Applications in the desired project/namespace.
  • argocd CLI configured, or access to Argo CD UI.

3. Phase 1 – Choose or create a sample application

For the purposes of this HOWTO, you can use:

  • A simple demo API or web app already in HybridOps.Studio, or
  • A public container image such as nginx:stable or a small test app.

Assume a logical application name, e.g. demo-api.

4. Phase 2 – Structure application manifests in Git

  1. Create a base directory

In the repo where you keep deployment manifests, create:

mkdir -p deploy/demo-api/base
mkdir -p deploy/demo-api/overlays/dev
mkdir -p deploy/demo-api/overlays/staging
mkdir -p deploy/demo-api/overlays/prod
  1. Define base manifests

At minimum, create:

  • Deployment
  • Service
  • Namespace (or use a shared one)

under deploy/demo-api/base/. Use a standard K8s pattern with labels like:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-api
  labels:
    app: demo-api
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-api
  template:
    metadata:
      labels:
        app: demo-api
    spec:
      containers:
        - name: demo-api
          image: your-registry/demo-api:1.0.0
          ports:
            - containerPort: 8080
  1. Define overlays

Use your preferred mechanism (for example, Kustomize) or just separate manifests. A simple directory-per-environment layout might contain:

  • A kustomization.yaml that references ../../base.

  • Environment-specific patches (replica count, config, URLs).

  • Commit the structure

Commit and push the changes so Argo CD can track them.

5. Phase 3 – Create an Argo CD Application

  1. Decide on RKE2 target

Determine:

  • The RKE2 cluster/endpoint Argo CD is targeting.

  • The namespace(s) for each environment (demo-api-dev, demo-api-staging, demo-api-prod or similar).

  • Create Application via manifest (recommended)

For one environment (e.g. dev), define:

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

Apply this using kubectl:

kubectl apply -f deploy/demo-api/argo/demo-api-dev-application.yaml

Or create it via Argo CD UI with equivalent settings.

  1. Repeat for other environments

  2. demo-api-staging pointing at overlays/staging.

  3. demo-api-prod pointing at overlays/prod.

Use separate Application objects even if they share the same repo.

6. Phase 4 – Sync and validate

  1. Initial sync

  2. In the Argo CD UI or via CLI (argocd app sync demo-api-dev), trigger a sync.

  3. Confirm that:

    • The namespace is created.
    • Deployment and Service are created.

  4. Check application status

  5. Argo CD should show Healthy / Synced for demo-api-dev.

  6. If there are errors (for example, image pull issues, invalid manifests), inspect logs and fix the manifests in Git.

  7. Capture basic evidence

Store in a proof folder such as:

mkdir -p output/artifacts/apps/demo-api/gitops-onboarding-<date>/

Capture:

  • kubectl get pods -n demo-api-dev output.
  • Argo CD Application status (screenshot or CLI output).

7. Phase 5 – Demonstrate GitOps change and rollback

  1. Change the application via Git

  2. Update the image tag from 1.0.0 to 1.0.1 (or similar) in the base manifests.

  3. Commit and push.

  4. Observe Argo CD reaction

  5. Argo CD will detect the change and either:

    • Auto-sync (if automated is enabled), or
    • Show OutOfSync status and allow you to sync manually.

  6. Verify rollout

  7. Check that the new pods are running with the updated image.

  8. Capture CLI output and/or screenshots into the same output/artifacts/apps/demo-api/gitops-onboarding-<date>/ folder.

  9. Rollback via Git

  10. Revert the change (for example, git revert or editing the tag back).

  11. Push the revert.
  12. Argo CD will again reconcile, rolling back the deployment.

Capture evidence of rollback (status, pod versions).

8. Phase 6 – Tie back to Evidence 4

Document briefly (for your notes or a short internal page):

  • Which repo path is used for the app (deploy/demo-api/...).
  • Which Argo CD Applications represent each environment.
  • Where the proof artefacts are stored.

This helps wiring the onboarding story into:

  • Evidence 4 (GitOps and cluster operations), and
  • Academy content that shows a concrete GitOps onboarding path.

9. Validation checklist

  • [ ] Application manifests structured under deploy/demo-api/ with base + overlays.
  • [ ] Argo CD Application created and pointing at the correct repo path and branch.
  • [ ] Initial sync succeeded and pods are running on RKE2.
  • [ ] A change to manifests in Git triggered a reconciliation and rollout.
  • [ ] Rollback was performed by reverting Git and letting Argo CD reconcile.
  • [ ] Proof artefacts stored under output/artifacts/apps/demo-api/gitops-onboarding-<date>/.

References

Maintainer: HybridOps.Studio
License: MIT-0 for code, CC-BY-4.0 for documentation