I’ve spent more nights than I care to admit staring at a terminal, trying to figure out why a staging environment suddenly "broke" even though no one supposedly touched it.

We’ve all been there, right? a manual edit here, a quick hotfix there, and suddenly your Git repository is no longer a Source of Truth, it’s a historical document of what used to be running.

Without a reliable strategy, Kubernetes deployments quickly descend into a mess of drift, painful rollbacks, and non-existent audit trails. I learned the hard way that simply storing manifests in Git isn't enough. If your cluster isn't actively listening to your code, you're still working with a gap.

GitOps closes that gap. It turns your cluster into a mirror of your repository. If it isn't in Git, it doesn't exist.

In this tutorial, you aren't just going to read about the theory. You’re going to implement a "Zero-Touch" deployment loop from scratch. We’ll use Argo CD, GitHub Actions, and the Argo CD Image Updater to build a system that builds, tags, and deploys your code the second you hit git push.

Table of Contents

1. Prerequisites

2. What GitOps Really Means

3. What is Argo CD and How Does it Implement GitOps?

4. Preparing the Application Source Code and Repo Structure

5. Automating Image Builds with GitHub Actions

6. How to Install and Access Argo CD

7. Understanding the Argo CD Application

8. Deploying the Application Manifest

9. Automating Updates with Argo CD Image Updater

10. Conclusion

Prerequisites

Before you begin, make sure you have the following ready in your environment:

• A GitHub repository: You'll need a repository (for example, my-gitops-demo) to serve as your Single Source of Truth. If you're following this tutorial from scratch, start with an empty repo.

• A DockerHub account: This will act as your Container Registry. You’ll need this to build, push, and store the Docker images that GitHub Actions creates.

• A running Kubernetes cluster: You can use a local solution like Minikube or Kind, or a cloud-managed service like Amazon EKS or GKE.

• Kubernetes tooling: Ensure kubectl is installed and configured to communicate with your cluster.

• Fundamental K8s knowledge: You should be comfortable with basic Kubernetes concepts like Pods, Deployments, and Services.

Note for Readers with Existing Projects

If you already have a project and want to migrate it to this GitOps workflow, you don't need to start over. You can adapt your existing repository by following these three steps:

1. Standardize your manifests: Move all your existing Kubernetes YAML files into a dedicated Kubernetes-manifest/ directory at the root of your project.

2. Containerize your services: Ensure every service you intend to deploy has a Dockerfile in its respective subdirectory (for example, /main-api/Dockerfile).

3. Prepare for automation: Be ready to replace any manual kubectl apply steps in your current CI pipeline with the automated tagging strategy we’ll implement in the next sections.

What GitOps Really Means

At its core, GitOps is an operational framework that uses Git as the single source of truth for your infrastructure and applications. In a traditional setup, you might run kubectl apply -f deployment.yaml from your laptop. This makes it impossible to track who changed what, leading to "snowflake" clusters that no one can reproduce.

GitOps enforces four key principles:

1. Declarative: You describe the desired state (for example, "3 replicas of Nginx"), not the commands to get there.

2. Versioned and immutable: Your entire state is in Git. If a deployment fails, you git revert to a previous known-good state.

3. Pulled automatically: A software agent (Argo CD) pulls the state from Git.

4. Continuously reconciled: The system constantly fixes "drift." If a developer manually changes a service in the cluster, Argo CD will overwrite it to match Git.

What is Argo CD and How Does it Implement GitOps

Before we dive into the setup, let’s define the tool we'll be working with.

Argo CD is a declarative, GitOps' continuous delivery engine built specifically for Kubernetes. As a graduated project of the Cloud Native Computing Foundation (CNCF), it has become the industry standard for managing modern infrastructure.

Think of Argo CD as a persistent watchdog that lives inside your cluster. To understand why it's so powerful, we have to look at how it differs from traditional CI/CD tools like Jenkins or GitHub Actions.

The "Push" vs. "Pull" Model

Traditional tools like the one I mentioned above use a "Push" model. In this setup, an external pipeline sends commands (like kubectl apply) into your cluster. This is risky because you must store sensitive cluster administrative keys inside your external CI tool. If your CI tool is compromised, your cluster is, too.

Argo CD flips this script using a "Pull" model:

• The bridge: It sits between your Git repo (the "Desired State") and your cluster (the "Live State").

• Continuous monitoring: It watches your Git repo 24/7. The moment it detects a new commit, it "pulls" that change and applies it from inside the cluster.

• Self-healing: If someone manually changes a setting in the cluster (known as "drift"), Argo CD detects the discrepancy and automatically overwrites it to match what is written in Git.

This approach is not only more secure, since no cluster credentials ever leave the environment, but it also ensures that your infrastructure is a perfect, predictable mirror of your code.

Preparing the Application Source Code

Before we automate the build, we need actual code in our repository. We'll create two simple microservices: a Main API and an Auxiliary Service.

Repo Structure

Ensure your repository follows this structure exactly. Consistency in naming is vital for the automation to find your files.

GITOPS-ARGOCD-DEMO/
├── .github/workflows/main.yml
├── auxiliary-service/
│   └── Dockerfile
├── main-api/
│   └── Dockerfile
├── Kubernetes-manifest/
│   ├── aux-api.yaml
│   ├── kustomization.yaml
│   └── main-api.yaml
├── application.yaml
└── image-updater.yaml

Create the Dockerfiles

In each service folder, create a simple Dockerfile so our pipeline has something to build.

main-api/Dockerfile

FROM nginx:alpine
RUN echo "<h1>Main API - Version 1.0</h1>" > /usr/share/nginx/html/index.html
EXPOSE 80

auxiliary-service/Dockerfile

FROM nginx:alpine
RUN echo "<h1>Auxiliary Service - Version 1.0</h1>" > /usr/share/nginx/html/index.html
EXPOSE 80

Automating Image Builds with GitHub Actions

In a professional GitOps workflow, your Kubernetes manifests and your application source code often live in the same repository (or linked ones). While Argo CD handles the deployment, you still need a way to turn your code into Docker images. This is where Continuous Integration (CI) comes in.

I have included a GitHub Actions workflow in this demo to automate this. Every time you push code to the main branch, this pipeline builds your images and pushes them to DockerHub.

The CI Pipeline Workflow

Create a file at .github/workflows/main.yml and add the following:

name: Build and Push Image to DockerHub

on:
  push:
    branches:
      - main
    # Skip builds for image updater commits
    paths-ignore:
      - 'Kubernetes-manifest/**'

jobs:
  docker_build:
    name: Build & Push ${{ matrix.service }}
    environment: argocd-demo
    runs-on: ubuntu-latest
    permissions:
      contents: write

    strategy:
      matrix:
        include:
          - service: aux-service
            dockerfile: auxiliary-service/Dockerfile
          - service: main-service
            dockerfile: main-api/Dockerfile

    env:
      DOCKER_USER: ${{ secrets.DOCKERHUB_USERNAME }}
      RUN_TAG: ${{ github.run_number }}

    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ env.DOCKER_USER }}
          password: ${{ secrets.DOCKERHUB_PASSWORD }}

      - name: Build and Push ${{ matrix.service }}
        uses: docker/build-push-action@v6
        with:
          context: .
          file: ${{ matrix.dockerfile }}
          push: true
          tags: \({{ env.DOCKER_USER }}/\){{ matrix.service }}:${{ env.RUN_TAG }}
          cache-from: type=gha,scope=${{ matrix.service }}
          cache-to: type=gha,mode=max,scope=${{ matrix.service }}

Pro tip: The paths-ignore section is critical. Later, the Argo CD Image Updater will write changes back to the Kubernetes-manifest/ folder. Without this ignore rule, your pipeline would trigger itself forever in an infinite loop.

Note: You must add DOCKERHUB_USERNAME and DOCKERHUB_PASSWORD to your GitHub Repo Settings > Secrets.

How to Install and Access Argo CD

Now that your cluster is running, you can install Argo CD. You'll perform the installation using a standard Kubernetes manifest provided by the Argo project.

Step 1: Create the Namespace and Apply the Manifests

In Kubernetes, it is a best practice to keep your administrative tools separate from your applications. You will create a dedicated namespace named argocd and then apply the official installation script from the Argo project. This script includes all the necessary ServiceAccounts, Roles, and Deployments.

Run the following commands in your terminal:

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

You'll see a long list of resources being created. Wait a minute or two for the pods to initialize. you can verify that all the core components of Argo CD are running.:

kubectl get all -n argocd

Ensure all pods show a status of Running before proceeding.

Step 2: Access the Argo CD User Interface

To access the dashboard, we use a technique called port forwarding. Since the Argo CD server is running inside the cluster's private network, your browser can't see it yet. Port forwarding creates a secure 'tunnel' between a port on your local machine (8080) and a port on the cluster service (443). This allows you to interact with internal services without exposing them to the public internet.

Run the following command:

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

You can now open your browser and navigate to https://localhost:8080. Your browser may warn you that the connection is not private because of a self-signed certificate. You can safely click "Advanced" and proceed to the site.

Step 3: How to Log In

The default username for Argo CD is admin. The password is autogenerated during the installation process and is stored securely as a Kubernetes secret.

To retrieve this password, open a new terminal tab (so the port-forwarding keeps running) and run:

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

Copy the output and use it as the password to log into the dashboard.

Understanding the Argo CD Application

An Argo CD Application is a Custom Resource (CRD) that acts as a "contract" between your Git repo and your cluster. It defines:

• repoURL & path: This tells Argo CD exactly which Git repository to watch and which folder inside that repo contains your YAML manifests.

• destination: This defines where the app should live. We use https://kubernetes.default.svc to point to the local cluster where Argo CD is installed.

• syncPolicy: This is the heart of GitOps. By setting automated with selfHeal: true, we tell Argo CD to automatically fix the cluster if someone manually changes something (drift). The prune: true setting ensures that if you delete a file in Git, it also gets deleted in the cluster.

The Application Manifest

Create application.yaml in your project root:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: gitops-argocd-demo
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPO_NAME>.git
    targetRevision: HEAD
    path: Kubernetes-manifest
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd-demo-ns
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true

Deploying the Application Manifest

Now we'll define our Kubernetes resources in the Kubernetes-manifest/ folder.

main-api.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: main-deployment
  namespace: argocd-demo-ns
spec:
  replicas: 1
  selector:
    matchLabels:
      app: main-api
  template:
    metadata:
      labels:
        app: main-api
    spec:
      containers:
      - name: main-service
        image: <YOUR_DOCKERHUB_USERNAME>/main-service:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: main-service-lb
  namespace: argocd-demo-ns
spec:
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 80
  selector:
    app: main-api

aux-api.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aux-deployment
  namespace: argocd-demo-ns
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aux-service
  template:
    metadata:
      labels:
        app: aux-service
    spec:
      containers:
      - name: aux-service
        image: <YOUR_DOCKERHUB_USERNAME>/aux-service:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: aux-service
  namespace: argocd-demo-ns
spec:
  ports:
  - port: 80
    targetPort: 80
  selector:
    app: aux-service

Push and Sync

Step 1: Apply the Application Manifest

Use kubectl to deploy this manifest into the argocd namespace:

kubectl apply -f application.yaml -n argocd

Step 2: Push to Your Repository

To trigger the initial deployment and ensure Argo CD stays in sync with your source of truth, add, commit, and push your latest changes to the GitHub repository you configured in the manifest:

git add .
git commit -m "initial argo application deployment"
git push origin main

Step 3: Verify the Result in Argo CD

Once you push your changes, head over to your Argo CD dashboard. You'll see the gitops-argocd-demo application appear. After the initial sync, the dashboard will display a healthy, green status indicating that your live cluster state perfectly matches your Git repository.

Note: As you can see in the screenshot above, Argo CD provides a visual representation of how your Kubernetes objects – Services, Deployments, and Pods – are related and confirms they are "Synced" with your Git repo.

Automating Updates with Argo CD Image Updater

Now that we have automated the deployment, let’s solve the final manual hurdle: automatically updating image tags in our manifests whenever a new build is pushed to DockerHub.

Step 1: Install ArgoCD Image Updater

Install the Image Updater into the argocd namespace:

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

Verify the pod is running:

kubectl get pods -n argocd | grep image-updater

Note: Version 1.1+ uses a CRD-based approach (ImageUpdater custom resources) instead of the annotation-based approach used in older versions. This guide covers the CRD method.

Step 2: Create a GitHub Personal Access Token

The Image Updater needs Git credentials to push write-back commits to your repository.

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Tokens (classic)

2. Click Generate new token

3. Select the repo scope (full control of private repositories)

4. Copy the generated token

Step 3: Create the Git Credentials Secret

Store the GitHub credentials as a Kubernetes secret in the argocd namespace:

kubectl -n argocd create secret generic git-creds \
  --from-literal=username=<YOUR_GITHUB_USERNAME> \
  --from-literal=password=<YOUR_GITHUB_PAT>

Replace <YOUR_GITHUB_USERNAME> and <YOUR_GITHUB_PAT> with your actual values.

Step 4: Add a Kustomization File to Your Manifests

The Image Updater uses Kustomize's images field to write updated tags. If your Kubernetes-manifest/ directory contains plain YAML files, you'll need to wrap them with a kustomization.yaml file.

Create a kustomization.yaml file:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - main-api.yaml
  - aux-api.yaml

How it works: When the Image Updater detects a new tag, it appends an images section to this file:

images:
  - name: <YOUR_GITHUB_USERNAME>/main-service
    newTag: "12"
  - name: <YOUR_GITHUB_USERNAME>/aux-service
    newTag: "12"

Kustomize then overrides the image tags at deploy time, without modifying your original deployment YAML files.

We use Kustomize here because it allows the Image Updater to manage image tags in a separate, clean way. Instead of the Updater 'messing' with your original main-api.yaml file, it simply updates the kustomization.yaml file. Argo CD then uses Kustomize to merge those changes during deployment.

Step 5: Create the ImageUpdater Custom Resource

Create image-updater.yaml in your project root:

apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata:
  name: gitops-argocd-demo-updater
  namespace: argocd
spec:
  commonUpdateSettings:
    updateStrategy: newest-build
    allowTags: "regexp:^[0-9]+$"
  applicationRefs:
    - namePattern: "gitops-argocd-demo"
      writeBackConfig:
        method: "git:secret:argocd/git-creds"
        gitConfig:
          branch: main
          writeBackTarget: "kustomization:."
      images:
        - alias: main-service
          imageName: <YOUR_DOCKERHUB_USERNAME>/main-service
        - alias: aux-service
          imageName: <YOUR_DOCKERHUB_USERNAME>/aux-service

This ImageUpdater resource is the "brain" of our automated tagging system. Here is what the specific fields are doing:

updateStrategy:

• newest-build: It tells the updater to always look for the most recent image version in DockerHub based on creation time.

writeBackConfig: This is where the magic happens. It uses the git-creds secret we created to authorize the updater to 'write' back to your repository.

writeBackTarget:

• kustomization: We are telling the updater specifically to modify the kustomization.yaml file in the manifests folder rather than touching the deployment files directly.

images: We provide aliases (main-service and aux-service) so the updater knows exactly which images in DockerHub correspond to which containers in our Kubernetes manifests.

Apply the ImageUpdater CR to the cluster:

kubectl apply -f image-updater.yaml -n argocd

Push the kustomization.yaml to your Git repository (the Image Updater clones the repo, so it must exist remotely):

git add Kubernetes-manifest/kustomization.yaml
git commit -m "Add kustomization.yaml for image updater write-back"
git push origin main

Step 6: Verify the Image Updater

Check the Image Updater logs to confirm it's working:

kubectl logs -n argocd deployment/argocd-image-updater-controller --tail=20

Successful output looks like:

msg="Starting image update cycle, considering 1 application(s) for update"
msg="Setting new image to YOUR_DOCKERHUB_USERNAME/main-service:11"
msg="Successfully updated image 'YOUR_DOCKERHUB_USERNAME/main-service:7' to 'YOUR_DOCKERHUB_USERNAME/main-service:11'"
msg="Setting new image to YOUR_DOCKERHUB_USERNAME/aux-service:11"
msg="Committing 2 parameter update(s) for application gitops-argocd-demo"
msg="git push origin main"
msg="Successfully updated the live application spec"
msg="Processing results: applications=1 images_considered=2 images_skipped=0 images_updated=2 errors=0"

Conclusion

You have successfully implemented a professional-grade GitOps loop from scratch. By integrating GitHub Actions, Argo CD, and the Argo CD Image Updater, you’ve bridged the gap between your source code and your live environment.

Think about the workflow you just built:

1. You push code to GitHub.

2. GitHub Actions builds and tags a fresh Docker image.

3. Argo CD Image Updater detects that new tag and automatically commits it back to your Git manifests.

4. Argo CD pulls those changes and reconciles your cluster to the new desired state.

No more manual kubectl apply, no more configuration drift, and no more 2:00 AM mysteries. Your Git repository is now truly the Single Source of Truth. If it isn't in Git, it doesn't exist in your cluster, and that is the ultimate DevOps superpower.

Let’s pause for a moment: what are you trying to learn from your DevOps journey? Are you focusing on GitOps-style deployments, or promotions? This guide will help you tackle all of it – one step at a time.

As a DevOps engineer interested in creating a complete CI/CD pipeline, I wanted more than a basic "hello world" microservice. I was looking for a project where I could start from scratch – beginning with raw source code, writing my own Docker Compose and Kubernetes files, deploying locally, and then adding automation, environment promotion, and GitOps practices step by step.

In my search, I found several GitHub repositories. Most were either too simple to be useful or too complicated and already set up, leaving no room for learning. They often included ready-made Docker Compose files and Kubernetes manifests, which didn't help with learning through hands-on experience.

That’s when I discovered Craftista, a project maintained by Gourav Shah. This wasn’t just another training repo. As described in its documentation:

“Craftista is not your typical hello world app or off-the-shelf WordPress app used in most DevOps trainings. It is the real deal.”

Craftista stood out to me for several reasons:

• It’s a polyglot microservices application, designed to resemble a real-world platform.

• Each service uses its own technology stack – exactly like in modern enterprises.

• It includes essential building blocks of a real e-commerce system:

  • A modern UI built in Node.js

  • A Product Catalogue Service

  • A Recommendation Engine

  • A Voting/Review Service

By the end of this guide, you won’t just have a “hello world” demo – you’ll have a fully functioning CI/CD/GitOps pipeline modeled on a real-world microservices stack. You’ll understand how the pieces fit together, why each tool exists, and how to adapt this workflow to your own projects.

Ready to go beyond hello world and build a production-style pipeline from scratch? Let’s dive in.

Table of Contents

• Prerequisites and What You’ll Learn

• Topics Outside the Scope of This Guide

• What is GitOps?

  • Core Principles of GitOps

• Tools We Are Using in This Guide

  • GitHub Actions

  • Minikube

  • Argo CD

  • Kargo

• How to Structure Repositories for Microservice Applications

  • Why a Polyrepo Fits My Microservice-Service App

  • Git Branching is Anti Pattern to GitOps Principles

• How to Organize Kubernetes Manifests for GitOps

  • Argo CD Folders

  • 2. Argo CD Application Manifests (by Environment)

  • Env Folders

  • Kargo Folders

• How to Deploy and Promote Your Craftista Microservices Application

  • Prerequisites

  • 1. Start Minikube

  • 2. Install Argo CD

  • 3. Access the Argo CD UI

  • 4. Define a “Craftista” Argo CD Project

  • 5. Deploy the Development Environment

  • 6. Manual Promotion (Staging & Prod)

  • 7. Automated Promotion with Kargo

• Further Reading & Resources

• Conclusion

Prerequisites and What You’ll Learn:

Before you progress through this guide, ask yourself:

• Do I understand how semantic tagging improves traceability across environments?

• Can I replicate a multi-environment GitOps setup using Helm and Kubernetes?

• Am I confident in organizing Helm charts and manifests for scalable deployments?

• Do I know how Kargo and Argo CD work together to automate promotions and approvals?

This guide will help you confidently answer those questions by walking you through:

• ✅ An optimized Git branching strategy: using feature branches and a single main branch

• ✅ Semantic Docker image tagging for clean version tracking

• ✅ Helm chart and Kubernetes manifest structuring for multi-environment GitOps

• ✅ CI pipelines using GitHub Actions for build → test → tag automation

• ✅ Full GitOps workflows with Kargo and Argo CD for seamless promotion and delivery

Topics Outside the Scope of This Guide

• Deployment to managed services like EKS, AKS, or GKE is not included. We’ll use Minikube for local development.

• I assume you are already familiar with writing basic Kubernetes manifests. I won’t explain Pods, Services, Deployments, and their YAML structures here.

• I also won’t discuss topics like logging, metrics, tracing, and security hardening.

• This guide does not cover Managing Secrets and ConfigMaps and Implementing Service Discovery.

• And finally, we won’t go over ArgoCD and Kargo installation.

What is GitOps?

GitOps is a modern way to manage applications and infrastructure using Git as the main source of truth. Developers have used Git for a long time to manage and work together on code. GitOps takes this further by including infrastructure setup, deployment processes, and automation.

By keeping everything – from Kubernetes files and Helm charts to infrastructure code and app settings – in Git, teams have a central, version-controlled system that can be tracked. Changes in Git are automatically updated and matched with the target environments by GitOps tools like Argo CD or Flux.

Core Principles of GitOps

• Git as the single source of truth

• Declarative systems

• Immutable deployments

• Centralized change audit

Tools We Are Using in This Guide

GitHub Actions

GitHub Actions is a platform for continuous integration and delivery (CI/CD) that helps automate your build, test, and deployment processes.

In our project, we’ll use it to store our microservice application code. We’ll use GitHub Actions workflows to build and push Docker images to Docker Hub as our Docker registry. We’ll rely on GitHub Actions for continuous delivery.

Minikube

We are deploying our application and ArgoCD locally on Minikube. To simulate promotion between different environments, I am using namespaces.

Argo CD

Argo CD is a declarative GitOps continuous deployment tool for Kubernetes that automates the deployment and synchronization of microservice applications with Git repositories. It follows GitOps principles and uses declarative configurations with a pull-based approach.

Here’s a summary of the flow depicted in the above image:

1. The developer modifies application code and changes are pushed to a Git repository.

2. The CI pipeline is triggered and builds a new container image and pushes it to a container registry.

3. Merge triggers a webhook to notify Argo CD of changes in the Git repository.

4. Argo CD clones the updated Git repository. Compares the desired state (from Git) with the current state in the Kubernetes cluster.

5. Argo CD applies the necessary changes to bring the cluster to the desired state.

6. Kubernetes controllers reconcile resources until the cluster matches the desired configuration.

7. Argo CD continuously monitors the application and cluster state.

8. Argo CD can automatically or manually revert the changes to match the Git configuration, ensuring Git remains the single source of truth.

Kargo

Kargo manages promotion by watching repositories (Git, Image, Helm) for changes and making the needed commits to your Git repository, while Argo CD takes care of reconciliation. Kargo is built to simplify multi-stage application promotion using GitOps principles, removing the need for custom automation or CI pipelines.

Kargo Components

1. Warehouse: Watches image registries and discovers new container images. Monitors DockerHub for new tags like v1.2.0, v1.2.1, etc., and stores metadata about discovered images.

2. Stage: Defines a deployment environment (Dev, Stage, Prod). When a new image is found by the warehouse, it updates the manifest under env/dev/ with the new image tag. This triggers Argo CD to sync the dev environment.

3. PromotionPolicy: Defines how promotion should happen between stages (for example, auto or manual).

4. Freight: An artifact version to be promoted (for example, a specific container image or Helm chart). When v1.2.1 is discovered by the warehouse, a new Freight is created.

Practical Examples

• A new v1.2.0 image is pushed to DockerHub.

• Kargo detects it via a warehouse and updates the dev environment.

• Once verified (either by tests or metrics), Kargo automatically updates Helm values in the Git repo for staging.

• Argo CD sees the Git change and syncs the new version to staging.

• Manual approval (via Slack or UI) is required to push to production.

Why Kargo is the Perfect Companion to Argo CD

Have you ever had to manually promote versions across environments and wished it were automated? How would integrating Kargo have saved time or prevented errors in your last deployment?

Argo CD excels at GitOps-driven continuous deployment – syncing your Kubernetes cluster with the desired state declared in Git. But it lacks native support for promotion workflows between environments (like dev → staging → production) based on image metadata, test results, or approval gates. This is where Kargo becomes the perfect companion.

Kargo doesn’t replace Argo CD – it extends it. You continue to use Argo CD for syncing and deploying apps, but Kargo adds promotion intelligence and automation.

How to Structure Repositories for Microservice Applications

My example application consists of 4 microservices (frontend, recommendation, catalogues, and voting). Designing your repository structure is very important to start your project. There is a lot of debate between monorepo and multi-service repo.

A monorepo is a unified repository that houses all the code for a project or a set of related projects. It consolidates code from various services, libraries, and applications into a single centralized location.

On the other hand, a polyrepo architecture comprises multiple repositories, each containing the code for a distinct service, library, or application component.

Why a Polyrepo Fits My Microservice-Service App

Imagine you're onboarding a new team to your app. Would you prefer giving them access to an entire monorepo or just the relevant service’s repo? What trade-offs are you willing to accept?”

Well, using a polyrepo approach,

• Teams can work independently on the frontend, recommendations, catalogs, and voting without stepping on each other’s toes.

• Sensitive services remain locked down without complex directory-level rules.

• CI runners operate on a smaller codebase, speeding up checkouts and reducing bandwidth.

• Each service has its own release cadence (for example, catalogues v2.1.0 and voting v1.7.3).

• As your organization grows, new teams can onboard to only the repos they care about.

• Shared libraries can be versioned and published to an internal package registry, then consumed by each service.

Git Branching is Anti Pattern to GitOps Principles

Many teams default to “GitFlow”-style branching – creating long-lived branches for dev, staging, prod, and more. But in a true GitOps workflow, Git is your control plane, and “environments” shouldn’t live as branches.

Instead, you can keep things simple with just:

• A long-lived master (or main) branch

• Short-lived feature branches for code work

How to Organize Kubernetes Manifests for GitOps

This repo shows how you can keep ArgoCD application manifests, environment-specific values, Kargo promotion tasks, Helm charts for each microservice, and CI/CD workflows all in one place. It is organized so that:

1. ArgoCD application manifests live under argocd/, split by environment (for example, dev/, staging/, prod/).

2. Environment-specific overrides (Helm values or Kustomize patches) go under env/.

3. Kargo promotion configurations are grouped under kargo/, defining how new images move between environments.

4. Service Helm charts reside in service-charts/, one chart per microservice.

/microservice-helmcharts/
├── argocd/                # ArgoCD application manifests
│   ├── application/       # Application definitions
│   │   ├── dev/           # Development environment applications
│   │   │   ├── catalogue.yaml
│   │   │   ├── catalogue-db.yaml
│   │   │   ├── frontend.yaml
│   │   │   ├── recommendation.yaml
│   │   │   ├── voting.yaml
│   │   │   └── kustomization.yaml
│   │   ├── staging/       # Staging environment applications
│   │   │   └── [similar structure as dev]
│   │   ├── prod/          # Production environment applications
│   │   │   └── [similar structure as dev]
│   │   └── craftista-project.yaml
│   ├── blog-post.md
│   ├── deployment-guide-blog.md
│   └── repository-structure.md
├── env/                   # Environment-specific configurations
│   ├── dev/               # Development environment values
│   │   ├── catalogue/
│   │   │   └── catalogue-values.yaml
│   │   ├── catalogue-db/
│   │   │   └── catalogue-db-values.yaml
│   │   ├── frontend/
│   │   │   └── frontend-values.yaml
│   │   ├── recommendation/
│   │   │   └── recommendation-values.yaml
│   │   ├── voting/
│   │   │   └── voting-values.yaml
│   │   └── kustomization.yaml
│   ├── staging/           # Similar structure as dev but with image files
│   └── prod/              # Similar structure as staging
├── kargo/                 # Kargo promotion configuration
│   ├── catalogue-config/  # Catalogue service promotion
│   │   ├── catalogue-promotion-tasks.yaml
│   │   ├── catalogue-stages.yaml
│   │   └── catalogue-warehouse.yaml
│   ├── frontend-config/   # Frontend service promotion
│   │   ├── frontend-promotion-tasks.yaml
│   │   ├── frontend-stages.yaml
│   │   └── frontend-warehouse.yaml
│   ├── recommendation-config/ # Recommendation service promotion
│   │   ├── recommendation-promotion-tasks.yaml
│   │   ├── recommendation-stages.yaml
│   │   └── recommendation-warehouse.yaml
│   ├── voting-config/     # Voting service promotion
│   │   ├── voting-promotion-tasks.yaml
│   │   ├── voting-stages.yaml
│   │   └── voting-warehouse.yaml
│   ├── kargo.yaml         # ArgoCD application for Kargo
│   ├── kustomization.yaml # Combines all Kargo resources
│   ├── project.yaml       # Kargo project definition
│   └── projectconfig.yaml # Project-wide promotion policies
├── service-charts/        # Helm charts for each microservice
│   ├── catalogue/         # Catalogue service chart
│   │   ├── templates/
│   │   │   ├── deployment.yaml
│   │   │   └── service.yaml
│   │   ├── Chart.yaml
│   │   └── values.yaml
│   ├── catalogue-db/      # Similar structure as catalogue
│   ├── frontend/          # Similar structure as catalogue
│   ├── recommendation/    # Similar structure as catalogue
│   └── voting/            # Similar structure as catalogue
├── .github/workflows/     # CI/CD workflows
│   └── docker-ci.yml      # Docker image build and push
└── README.md              # Repository documentation

Argo CD Folders

The argocd/ directory contains all of the manifests that Argo CD needs in order to track, group, and deploy your microservices. In this guide, we break that directory into two main pieces:

1. Argo CD Project Definition

2. Argo CD Application Manifests (organized by environment)

ArgoCD Projects

Before you can give Argo CD a set of Applications to manage, it’s often best practice to define a “Project.” A Project in Argo CD serves as a logical boundary around a group of Applications. It can control which Git repos those Applications are allowed to reference, which Kubernetes clusters/namespaces they can target, and even which resource kinds they can manage.

In our example repo, the file craftisia-project.yaml lives at the top of argocd/:

# argocd/craftisia-project.yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: craftisia
  namespace: argocd
spec:
  # 1) Which Git repos are we allowed to pull from?
  sourceRepos:
    - "https://github.com/nitheeshp-irl/microservice-helmcharts"
    # (Or you could use "*" to allow any repo, but this is less secure.)

  # 2) Which clusters/namespaces can these Apps be deployed to?
  destinations:
    - namespace: "*"
      server: "*"    # Allow deployment to any cluster (for a local Minikube demo, this is fine).

  # 3) Which kinds of Kubernetes resources may be created/updated?
  #    (For example, we want Pods, Services, Deployments, Ingresses, etc.)
  #    Argo CD will reject any manifest containing a disallowed kind.
  clusterResourceWhitelist:
    - group: ""            # core API group (Pods, Services, ConfigMaps, etc.)
      kind: Pod
    - group: "apps"        # deployments, statefulsets, etc.
      kind: Deployment
    - group: "networking.k8s.io"
      kind: Ingress
    # (You can list additional resource kinds as needed.)

  # 4) Optional: define role-based access control or sync policies at the project level.
  #    (Not shown here, but you could add roles, namespace resource quotas, etc.)

2. Argo CD Application Manifests (by Environment)

Inside argocd/, there is a subdirectory called application/. We use this to keep all of our Argo CD Application YAMLs, broken out by environment. The high-level layout looks like this:

rCopyEditargocd/
└── application/
    ├── dev/            # “Dev” environment Applications
    │   ├── catalogue.yaml
    │   ├── catalogue-db.yaml
    │   ├── frontend.yaml
    │   ├── recommendation.yaml
    │   ├── voting.yaml
    │   └── kustomization.yaml
    ├── staging/        # “Staging” environment Applications (same names/structure as dev/)
    │   └── […]
    └── prod/           # “Prod” environment Applications (same names/structure as dev/)
        └── […]

Each of those YAML files is a standalone Argo CD Application. An Application tells Argo CD:

1. Which project it belongs to (in our case, craftisia),

2. Where to find its manifests (a Git repo and path),

3. Which Kubernetes cluster and namespace to deploy into, and

4. How to keep itself up to date (that is, sync policies).

Below is a example of the frontend.yaml file for the dev environment:

yamlCopyEdit# argocd/application/dev/frontend.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: frontend-dev
  namespace: argocd
spec:
  project: craftisia

  # 1) Source: Where to find the Helm chart and which values file to use
  source:
    repoURL: https://github.com/nitheeshp-irl/microservice-helmcharts
    targetRevision: main
    path: service-charts/frontend       # Helm chart folder for the frontend service
    helm:
      valueFiles:
        - ../../env/dev/frontend/frontend-values.yaml

  # 2) Destination: Which cluster & namespace to deploy into
  destination:
    server: https://kubernetes.default.svc    # (Assumes Argo CD is running in-cluster)
    namespace: front-end-dev                   # A dedicated namespace for “dev” frontend

  # 3) Sync Policy: Automate synchronization and enable self-healing
  syncPolicy:
    automated:
      prune: true          # Delete resources that are no longer in Git
      selfHeal: true       # If someone manually changes live resources, revert to Git state
    syncOptions:
      - CreateNamespace=true  # If the namespace doesn’t exist, Argo CD will create it

You would repeat a similar pattern under argocd/application/staging/ and argocd/application/prod/ – each environment has its own frontend.yaml, catalogue.yaml, and so on, but each will point to a different values file under env/staging/… or env/prod/… and likely deploy into a different namespace (for example, front-end-staging, front-end-prod).

Env Folders

The /env directory is a critical part of our GitOps implementation, containing all environment-specific configurations for our microservices. Each environment (dev, staging, prod) has its own subdirectory containing service-specific configurations. These contain general Helm chart values like resource limits and replica counts and container image repository and tag.

image:
  repository: nitheesh86/microservice-frontend
  tag: 1.0.11

replicaCount: 2

resources:
  limits:
    memory: "512Mi"
  requests:
    cpu: "100m"
    memory: "128Mi"

Kargo Folders

Our Kargo setup is organized in the /kargo directory with several key components:

/kargo/
├── catalogue-config/           # Catalogue service promotion configuration
│   ├── catalogue-promotion-tasks.yaml  # Defines how to update catalogue images
│   ├── catalogue-stages.yaml           # Dev, staging, prod stages for catalogue
│   └── catalogue-warehouse.yaml        # Monitors catalogue image repository
├── frontend-config/            # Frontend service promotion configuration
│   ├── frontend-promotion-tasks.yaml   # Defines how to update frontend images
│   ├── frontend-stages.yaml            # Dev, staging, prod stages for frontend
│   └── frontend-warehouse.yaml         # Monitors frontend image repository
├── recommendation-config/      # Recommendation service promotion configuration
│   ├── recommendation-promotion-tasks.yaml  # Image update workflow
│   ├── recommendation-stages.yaml           # Environment stages
│   └── recommendation-warehouse.yaml        # Image monitoring
├── voting-config/              # Voting service promotion configuration
│   ├── voting-promotion-tasks.yaml     # Image update workflow
│   ├── voting-stages.yaml              # Environment stages
│   └── voting-warehouse.yaml           # Image monitoring
├── kargo.yaml                  # ArgoCD application for Kargo installation
├── kustomization.yaml          # This file - combines all resources
├── project.yaml                # Defines the Kargo project
└── projectconfig.yaml          # Project-wide promotion policies

Stage Configurations: Kargo uses the concept of "stages" to represent our deployment environments. Each stage defines:

• Which freight (container images) to deploy

• The promotion workflow to execute

• Environment-specific variables

Warehouse Configuration: The warehouse monitors our container registry for new images.

Promotion Tasks: Promotion tasks define the actual workflow for promoting between environments.

How to Deploy and Promote Your Craftista Microservices Application

Now I'll explain how to deploy your Craftista microservices application using Argo CD.

Prerequisites

• A local Kubernetes cluster: We’ll use Minikube for local development.

• kubectl and helm: Ensure both are installed and configured.

• Git Clone of the microservice-helmcharts Repo:

    git clone https://github.com/nitheeshp-irl/microservice-helmcharts.git
    cd microservice-helmcharts
  

1. Start Minikube

Start Minikube with the specified resources:

minikube start --memory=4096 --cpus=2
kubectl config use-context minikube

Adjust --memory and --cpus as needed for your machine.

2. Install Argo CD

Create a namespace:

kubectl create namespace argocd

Apply the official install manifest:

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

3. Access the Argo CD UI

Port-forward the server:

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

Login:

• Username: admin

• Password:

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

Open your browser at http://localhost:8080.

4. Define a “Craftista” Argo CD Project

Scope Repos, Clusters, and Namespaces:

kubectl apply -f argocd/application/craftista-project.yaml

You should see:

project.argoproj.io/craftista created

5. Deploy the Development Environment

Create Argo CD applications:

kubectl apply -f argocd/application/dev/

Argo CD will:

• Clone the microservice-helmcharts repo.

• Render each Helm chart with its env/dev/*-values.yaml.

• Create Deployment, Service, and so on in your dev namespaces.

• Continuously reconcile desired vs. actual state.

Monitor your progress:

argocd app list
argocd app get frontend-dev

6. Manual Promotion (Staging & Prod)

Edit the image tag or other values:

• env/staging/<service>/<service>-values.yaml

• env/prod/<service>/<service>-values.yaml

Commit and push the changes:

git add env/staging env/prod
git commit -m "Promote v1.2.0 → staging & prod"
git push

Argo CD will detect the Git change and automatically sync your staging and prod applications (if automated sync is enabled).

7. Automated Promotion with Kargo

First, install Kargo:

kubectl apply -f kargo/kargo.yaml

Configure promotion tasks, stages, and warehouse:

kubectl apply -k kargo/

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - project.yaml
  - projectconfig.yaml
  - catalogue-config/catalogue-warehouse.yaml
  - catalogue-config/catalogue-stages.yaml
  - catalogue-config/catalogue-promotion-tasks.yaml
  - frontend-config/frontend-warehouse.yaml
  - frontend-config/frontend-stages.yaml
  - frontend-config/frontend-promotion-tasks.yaml
  - recommendation-config/recommendation-warehouse.yaml
  - recommendation-config/recommendation-stages.yaml
  - recommendation-config/recommendation-promotion-tasks.yaml
  - voting-config/voting-warehouse.yaml
  - voting-config/voting-stages.yaml
  - voting-config/voting-promotion-tasks.yaml

How the GitOps Pipeline Works

1. Developer Opens a Pull Request: The journey begins when a developer opens a pull request on one of the microservice repos. This signals that new code (feature, bugfix, config change) is ready to be integrated.

2. CI (GitHub Actions)

   • CI: Lint → Test → Build & Tag: A single workflow job lints the code, runs unit/integration tests, builds the Docker image, and applies a semantic tag (for example, v1.2.0).

   • CI OK? (Decision):

     • If No, the pipeline stops and the developer is notified to fix errors.

     • If Yes, the newly built image is pushed to the container registry (DockerHub, ECR, and so on).

3. Kargo

   • Warehouse discovers new image tag: Kargo’s Warehouse component continuously watches your registry. As soon as it sees the new tag, it records that image metadata.

   • Update env/dev values → Git: Kargo automatically commits an update to env/dev/<service>/…-values.yaml, pointing the dev Helm values file to the new image tag. This Git commit will drive the next step.

4. GitOps (Argo CD)

5. • Argo CD sync dev: Argo CD sees the Git change in the dev values file and pulls it into the cluster, reconciling the actual dev namespace with the desired state.

     • Dev deployment healthy? (Decision):

       • If No, Argo CD can optionally roll back and notifies the team (via Slack, email, etc.) of the failed dev rollout.

       • If Yes, it’s time to promote to staging.

     • Update env/staging values → Git: Kargo (or you, if manual) commits the same image tag into env/staging/<service>/…-values.yaml.

     • Argo CD sync staging: Argo CD deploys that change to the staging namespace.

     • Staging approval granted? (Decision):

       • If No, Kargo waits (and optionally notifies) until a manual gate is lifted.

       • If Yes, the final promotion commit is made: updating env/prod/<service>/…-values.yaml.

     • Argo CD sync prod → End: Argo CD applies the production change, completing the pipeline from commit all the way to live production rollout.

Pipeline Summary

1. Developer opens PR → CI tests and builds → Docker image pushed

2. Kargo Warehouse detects new tag → Git commit to env/dev

3. Argo CD syncs dev → Health check → (if successful) commit to env/staging

4. Argo CD syncs staging → Approval → commit to env/prod

5. Argo CD syncs prod → Live deployment complete

Every stage must pass its health or approval check before the next begins, ensuring that only thoroughly tested and validated code makes it into production.

Conclusion

Building a real-world CI/CD pipeline isn’t just about getting code from your laptop into a Kubernetes cluster – it’s about creating a repeatable, auditable, and reliable system that scales with your team and your application complexity.

In this guide, we walked through how I built a complete GitOps-based promotion pipeline using GitHub Actions, Argo CD, and Kargo, all driven by a hands-on microservices project: Craftista. From the first code commit to automated environment promotion, we leveraged industry best practices like semantic versioning, declarative infrastructure, and environment-based GitOps directories.

What makes this approach powerful is not just the tools but also the principles. By treating Git as the single source of truth, and using Kargo to automate what was traditionally a manual and fragile promotion process, we gain predictability and control over our deployments. Argo CD ensures that what’s in Git is always what’s running in our clusters, while Kargo eliminates human error in multi-stage rollouts.

If you’re tired of overly abstract “hello world” DevOps tutorials and want to get your hands dirty with something that feels real, Craftista offers the perfect sandbox. This pipeline reflects how teams operate in production – polyglot services, independent deployments, environment promotion gates, and GitOps as the operational backbone.

Whether you're a DevOps engineer sharpening your skills, or a platform team setting standards for internal development, I hope this tutorial provided the clarity and inspiration to build your own commit-to-production pipeline – step by step, with confidence.

Further Reading & Resources

• Argo CD Documentation

• Kargo Docs

• GitHub Actions Docs

• How to Model Your GitOps Environments and Promote Releases between Them

• Craftista Repo

This arrangement might work well in early days, but as a company grows and their needs become more specialized, the simplicity of a single account might start to show its limitations. The demand for dedicated environments will start to increase, and soon, that company may need to create new AWS accounts for specific functions like security, DevOps, and billing.

With each new account, the complexity of managing security policies and logging across the entire infrastructure grows exponentially. The cloud architects for these companies will then realize that they need a more centralized and streamlined approach to manage this expanding digital presence.

Enter AWS Organizations

AWS Organizations is a service designed to streamline AWS account management. This powerful tool allows you to group multiple AWS accounts under a single umbrella. With AWS Organizations, you can easily create organizational units, apply service control policies, and manage permissions across all accounts. This not only simplifies the process but also enhances security and compliance.

The billing processes of AWS Organizations have also been optimized through the centralization of payments and the generation of comprehensive expense reports for each account. This improved clarity in financial management makes it easier for companies to allocate resources in a more efficient manner and strategize for future expansion.

AWS Organizations can help your team consistently enforce security policies, enable logging across all accounts, and streamline administrative tasks. Cloud infrastructure is now a well-organized, secure, and efficient machine, ready to support a company's ambitions for years to come.

In this article, we’ll discuss what it means to have a multi-account setup and how it works. I’ll walk you through everything from the deployment architecture to creating an Organizational Unit and beyond.

Table of Contents

• Components of Multi-Account Setup

• How to Automate a Multi-Account Strategy

• AWS Organization Structure

• Deployment Architecture

• OverView of CI/CD Components

• CI/CD Deployment Process Explained

• How to Automate Landing Zone Creation

• How to Create an Organizational Unit

• How to Automate Attaching Control Tower Control to the OU

• Conclusion

Components of Multi-Account Setup

First, let's take a detailed look at the various components that make up an AWS multi-account strategy:

• AWS Control Tower

• Landing zone

• AWS OU

• AWS SSO

• Control Tower Controls

• Service control policies (SCPs)

What is AWS Control Tower?

AWS Control Tower is a comprehensive service that enables you to set up and manage a multi-account AWS environment efficiently. It’s designed based on best practices from AWS experts and adheres to industry standards and requirements.

By using AWS Control Tower, you can ensure that your AWS environment is secure, compliant, and well-organized, facilitating easier management and scalability.

Features of AWS Control Tower:

• Cloud IT can be confident that all accounts are in line with company-wide regulations, and distributed teams may create new AWS accounts quickly.

• You can enforce best practices, standards, and regulatory requirements with preconfigured controls.

• You can automate your AWS environment setup with best-practice blueprints. These blueprints cover various aspects such as multi-account structure, identity and access management, as well as account provisioning workflow.

• It lets you govern new or existing account configurations, gain visibility into compliance status, and enforce controls at scale.

What is a Landing Zone in AWS?

A landing zone helps you quickly set up a cloud environment using automation, including preconfigured settings that follow industry best practices for ensuring the security of your AWS accounts.

The starting point serves as a foundation for your company to efficiently initiate and implement workloads and applications, ensuring a secure and reliable infrastructure environment.

There are two choices for creating a landing zone. First, you can use the AWS Control Tower dashboard. Second, you can build a custom landing zone. If you are new to AWS, I recommend using AWS Control Tower to create a landing zone.

If you opt for creating a landing zone via the Control Tower dashboard, the following will be implemented in your landing zone:

• A multi-account environment with AWS organizations.

• Identity management through the default directory in AWS IAM Identity Center.

• Federated access to accounts using IAM Identity Center.

• Centralized logging from AWS CloudTrail and AWS Config stored in Amazon Simple Storage Service (Amazon S3).

• Enabled cross-account security audits using IAM Identity Center.

What is an AWS Organizational Unit?

Using multiple accounts allows you to better support your security goals and company operations.

AWS Organizations enables policy-based management of multiple AWS accounts. When you create new accounts, you can arrange them in organizational units (OUs), which are groupings of accounts that provide the same application or service.

Advantages of Using OUs:

• Accounts are units of security protection. Potential hazards and security threats can be contained within one account without affecting others.

• Teams have different assignments and resource needs. Setting up different accounts prevents teams from interfering with one another, as they might do if they used the same account.

• Isolating data stores to an account reduces the number of people who have access to and can manage the data store.

• The multi-account concept allows you to generate separate billable items for business divisions, functional teams, or individual users.

• AWS quotas are set up per account. Separating workloads into different accounts gives each account an individual quota.

What is AWS IAM Identity Center?

The AWS IAM Identity Center provides a centralized solution for managing access to multiple AWS accounts and business applications.

This method offers a single sign-on feature that allows employees to access all assigned accounts and applications from a single credential.

The personalized web user portal provides a centralized view of the user's assigned roles in AWS accounts.

For a uniformed authentication experience, users can sign in using the AWS Command Line Interface, AWS SDKs, or the AWS Console Mobile Application with their directory credentials.

You can also set up and oversee user IDs in IAM Identity Center's identity store, or you can connect to your existing identity provider, such as Microsoft Active Directory, Okta, and so on.

Control Tower Controls (Guardrails)

Controls are predefined governance rules for security, operations, and compliance. You can select and apply them enterprise-wide or to specific groups of accounts.

Controls can be detective, preventive, or proactive and can be either mandatory or optional.

• First, we have detective controls (for example, detecting whether public read access to Amazon S3 buckets is allowed).

• Next, preventive controls establish intent and prevent deployment of resources that don’t conform to your policies (for example, enabling AWS CloudTrail in all accounts).

• Finally, proactive control capabilities use AWS CloudFormation Hooks to proactively identify and block the CloudFormation deployment of resources that are not compliant with the controls you have enabled. For example, developers cannot create S3 buckets that are capable of storing data in an unencrypted state at rest.

Service Control Policies (SCP)

SCPs are a feature of the organization that allows you to set the maximum permissions for member accounts within the organization.

There are many functions and features of an SCP:

• If an SCP denies an action on an account, no entity in the account can perform that action, even if its IAM permissions allow it.

• Prevents stopping or deletion of CloudTrail logging.

• Prevents deletion of VPC flow logs.

• Prohibits AWS accounts from leaving the organization.

• Prevents AWS GuardDuty changes.

• Prevents resource sharing using AWS Resource Access Manager (RAM) either externally or across environments.

• Prevents disabling the default Amazon EBS encryption.

• Prevents Amazon S3 unencrypted object uploads.

• And prevents IAM users and roles in the affected accounts from creating certain resource types if the request doesn't include the specified tags.

How to Automate a Multi-Account Strategy

Now that you’re familiar with the key concepts of a Multi-Account Strategy in AWS, let’s dive deeper into the practical parts.

In the coming subsections, we’ll cover how you can set up an AWS Control Tower, create a landing zone, and automatically create organizational units (OUs). I’ll also walk you through how to configure Control Tower controls—often known as guardrails—to uphold security, compliance, and governance over your AWS environment.

Once we finish this deployment, we will have a solution that includes the following components:

• Creates an AWS Organizations OU named Core within the organizational root structure.

• Creates and adds two shared accounts to the Security OU: the Log Archive account and the Audit account.

• Creates a cloud-native directory in IAM Identity Center, with ready-made groups and single sign-on access.

• Applies all required preventive controls to enforce policies.

• Applies required detective controls to identify configuration violations.

AWS Organization Structure

We will create and implement the following organizational structure. You can add or modify OUs as per your requirements.

Deployment Architecture

I will be using Terraform Cloud and GitHub Actions for automating the entire process. This architecture applies to all three components, including core accounts, landing zones, and organizational unit (OU) creation and controls.

Overview of CI/CD Components

1. GitHub Actions

GitHub Actions is a CI/CD platform that lets you automate your build, test, and deployment pipeline. You can create workflows that automatically build and test every pull request to your repository, ensuring code changes are verified before merging.

GitHub Actions also lets you deploy merged pull requests to production, streamlining the release process and reducing errors.

Using GitHub Actions enhances your development workflow, improves code quality, and speeds up the delivery of new features and updates.

2. Terraform Cloud

Terraform Cloud is a platform by HashiCorp for managing and executing your Terraform code. It offers tools and features that enhance collaboration between developers and DevOps engineers, making teamwork more efficient.

With Terraform Cloud, you can simplify and streamline your workflow, making it easier to handle complex infrastructure tasks and deployments. The platform also provides strong security features to protect your code and infrastructure, keeping your product secure throughout its lifecycle.

CI/CD Deployment Process Explained

DevOps engineers are responsible for writing the Terraform code and then creating a pull request. I have added several test cases for my Terraform code in the terraform-plan.yml file, which runs only on the feature branch.

• Check environment variables: Ensures all required environment variables are set.

• Checkout Code: Uses the actions/checkout action to check out the repository.

• Verify Checkout: Verifies that the checkout was successful.

• Validation: Verifies the Terraform code for any syntax errors. Pull requests contain proposed changes in code, allowing team members to review and merge them into the master branch. Once pull requests are merged with the master branch, all test cases are rerun, and the landing zone is created through Terraform Cloud

What to Know Before Setting up Control Tower

Before beginning the process of setting up for AWS Control Tower, it is important to have a clear understanding of what limitations are associated with Control Tower and consider some key points.

• When setting up a landing zone, it is important to choose your home region. Once you have made a selection, you won’t be able to change your home region.

• If you intend to establish a control tower on an existing AWS account that is already a part of an existing organizational unit (OU), you won’t be able to use it. In order to proceed, you’ll need to create a new AWS account that is not associated with any organizational Unit (OU).

• As part of the Control Tower creation process, you’ll need to create mandatory accounts such as the Log Archive Account and Audit Accounts. Account-specific emails are required.

• In order to set up the Landing Zone in the Management Account, it is essential to ensure that you have subscribed to the following services in the management account:

  • S3, EC2, SNS, VPC, CloudFormation, CloudTrail, CloudWatch, AWS Config, IAM, AWS Lambda

• The AWS Control Tower baseline covers only a few services with limited customization options: IAM Identity Center, CloudTrail, Config, some configuration rules, and some SCPs in AWS Organizations.

• Implementing IAM Identity Center is limited to the management account of an organization.

• AWS Control Tower implements concurrency limitations, allowing only one operation to be performed at a time.

• Note that certain AWS Regions do not support the operation of some controls in AWS Control Tower. This is because the specified Regions lack the necessary underlying functionality to support the required operations.

How to Create a Control Tower

Creating a Control Tower means setting up a landing zone. AWS landing zone requires creating two new member accounts: the Audit account and the Log Archive account. You will need two unique email addresses for these accounts.

We will manage this process using Terraform modules. To keep things simple and clear, we will divide the project into several modules. One module will create the two core accounts. Another module will handle the setup of the landing zone. The final module will create Organizational Units (OUs) and apply Control Tower controls to ensure governance and compliance.

How to Automate Landing Zone Creation

When you run this code, the Core OU and two accounts are created under the Core OU. I have mentioned two repositories for each component: one for deploying the AWS resources like the landing zone, OU, and Control Tower Controls and another for the Terraform module.

A Terraform module is a set of standard configuration files in a specific directory. Terraform modules group resources for a specific task, which reduces the amount of code needed for similar infrastructure components.

I have imported both the core account creation and landing zone creation modules into the same main.tf file. This is necessary because the landing zone creation depends on the core account module. Including them together ensures all dependencies are managed properly and the deployment process is efficient.

This method also simplifies the project structure and helps avoid potential issues from managing these components separately.

The AWS Control Tower CreateLandingZone API needs a landing zone version and a manifest file as input parameters. Below is an example LandingZoneManifest.json manifest.

{
   "governedRegions": ["us-west-2","us-west-1"],
   "organizationStructure": {
       "security": {
           "name": "CORE"
       },
       "sandbox": {
           "name": "Sandbox"
       }
   },
   "centralizedLogging": {
        "accountId": "222222222222",
        "configurations": {
            "loggingBucket": {
                "retentionDays": 60
            },
            "accessLoggingBucket": {
                "retentionDays": 60
            },
            "kmsKeyArn": "arn:aws:kms:us-west-1:123456789123:key/e84XXXXX-6bXX-49XX-9eXX-ecfXXXXXXXXX"
        },
        "enabled": true
   },
   "securityRoles": {
        "accountId": "333333333333"
   },
   "accessManagement": {
        "enabled": true
   }
}

This module sets up the AWS landing zone using landingzone_manifest_template. The landing zone version and admin account ID are given through variables. This module also creates several IAM roles required for the landing zone setup.

I defined a local variable landingzone_manifest_template, which is a JSON template for setting up the landing zone. This JSON template has several important settings:

provider "aws" {
  region = var.region
}

locals {
  landingzone_manifest_template = <<EOF
{
    "governedRegions": ${jsonencode(var.governed_regions)},
    "organizationStructure": {
        "security": {
            "name": "Core"
        }
    },
    "centralizedLogging": {
         "accountId": "${module.aws_core_accounts.log_account_id}",
         "configurations": {
             "loggingBucket": {
                 "retentionDays": ${var.retention_days}
             },
             "accessLoggingBucket": {
                 "retentionDays": ${var.retention_days}
             }
         },
         "enabled": true
    },
    "securityRoles": {
         "accountId": "${module.aws_core_accounts.security_account_id}"
    },
    "accessManagement": {
         "enabled": true
    }
}
EOF
}

module "aws_core_accounts" {
  source = "https://github.com/nitheeshp-irl/terraform_modules/aws_core_accounts_module"

  logging_account_email  = var.logging_account_email
  logging_account_name   = var.logging_account_name
  security_account_email = var.security_account_email
  security_account_name  = var.security_account_name
}

module "aws_landingzone" {
  source                  = "https://github.com/nitheeshp-irl/blog_terraform_modules/aws_landingzone_module"
  manifest_json           = local.landingzone_manifest_template
  landingzone_version     = var.landingzone_version
  administrator_account_id = var.administrator_account_id
}

• Governed Regions: Specifies the regions governed by the landing zone.

• Organization Structure: Defines the security structure with a dedicated security account.

• Centralized Logging: Configures logging, specifying the account ID and retention policies for logs.

• Security Roles: Specifies the account ID for security roles.

• Access Management: Enables access management.

• Core Accounts: The core accounts code, also defined in the same file, is what sets up essential AWS accounts for logging and security.

You can find the full code here: https://github.com/nitheeshp-irl/aws-landing-zone.

How to Create an Organizational Unit

When you run this code, different organizational units (OUs) are created according to the specifications in the variable file.

Once the landing zone setup is finished, we can create an OU as per our business requirements. This will take the OU name from the variable file and create the OU.

aws_region = "us-east-2"

organizational_units = [
  {
    unit_name = "apps"
  },
  {
    unit_name = "infra"
  },
  {
    unit_name = "stagingpolicy"
  },
  {
    unit_name = "sandbox"
  },
  {
    unit_name = "security"
  }
]

You can see the code here:

• AWS Organizational Units (OUs) Terraform Repo

• AWS Organizational Units Terraform Module Path

How to Automate Attaching Control Tower Control to the OU

Once you have created the OU units using the above repository, this repository will apply Control Tower controls to the OUs.

After creating the required objects, you can attach controls to the OU if you need them. Here is the main.tf file:

provider "aws" {
  region = var.region
}

module "aws_controls" {
  source = "https://github.com/nitheeshp-irl/blog_terraform_modules/awscontroltower-controls_module"

  aws_region = var.aws_region
  controls   = var.controls
}

We used Terraform modules to create AWS resources.

Here are the control variables:

aws_region = "us-east-2"


controls = [
  {
    control_names = [
      "AWS-GR_ENCRYPTED_VOLUMES",
      "AWS-GR_EBS_OPTIMIZED_INSTANCE",
      "AWS-GR_EC2_VOLUME_INUSE_CHECK",
      "AWS-GR_RDS_INSTANCE_PUBLIC_ACCESS_CHECK",
      "AWS-GR_RDS_SNAPSHOTS_PUBLIC_PROHIBITED",
      "AWS-GR_RDS_STORAGE_ENCRYPTED",
      "AWS-GR_RESTRICTED_COMMON_PORTS",
      "AWS-GR_RESTRICTED_SSH",
      "AWS-GR_RESTRICT_ROOT_USER",
      "AWS-GR_RESTRICT_ROOT_USER_ACCESS_KEYS",
      "AWS-GR_ROOT_ACCOUNT_MFA_ENABLED",
      "AWS-GR_S3_BUCKET_PUBLIC_READ_PROHIBITED",
      "AWS-GR_S3_BUCKET_PUBLIC_WRITE_PROHIBITED",
    ],
    organizational_unit_names = ["infra", "apps"]
  }
]

You can see the code here:

• Terraform Repo for Creating control tower controls

• Terraform Module for creating Control Tower Controls

Conclusion

Navigating a multi-account strategy in AWS can be challenging, but with AWS Control Tower and a structured approach, it becomes manageable.

Using AWS Control Tower, your team can ensure that their AWS environments are secure, compliant, and well-organized. The automated setup, governance at scale, and centralized management through AWS Organizations provide a strong foundation for cloud infrastructure.

Implementing a landing zone through AWS Control Tower offers a secure and standardized starting point, allowing for quicker deployment and better governance. Using organizational units (OUs) segregates accounts based on business needs, improving security and operational efficiency. AWS IAM Identity Center simplifies access management, providing a unified authentication experience across multiple accounts and applications.

Service Control Policies (SCPs) help keep things secure and compliant by making sure all resources follow the organization's rules. Terraform Cloud and GitHub Actions make it easier to deploy resources, offering a smooth CI/CD pipeline for managing infrastructure changes.