This hands-on tutorial will guide you through implementing GitOps workflows using ArgoCD with Kubernetes. You'll learn three different approaches to manage your applications:

1. Basic ArgoCD setup - Direct deployment from a GitHub repository

2. Environment management with Kustomize - Using overlays for different environments

3. Helm-based deployments - Leveraging Helm charts for more complex applications

All of the project files will be provided. By the end of this tutorial, you'll have practical experience with GitOps principles and understand how to implement continuous deployment pipelines that automatically sync your Kubernetes resources with your Git repositories.

Clone the repository

Clone the repository:

git clone https://github.com/rslim087a/argocd-kubernetes-gitops-tutorial.git

The repository contains all of the project files needed to deploy a Grade Submission API using three GitOps workflows.

What is GitOps?

GitOps is a set of practices where the entire system is described declaratively and versioned in Git. With GitOps:

• Git is the single source of truth for the desired state of your system

• Changes to the desired state are made through pull requests/commits

• Software agents automatically sync the actual state with the desired state

ArgoCD is one of the leading GitOps tools that helps implement these practices for Kubernetes environments.

Setting Up ArgoCD

Let's start by installing ArgoCD in our Kubernetes cluster using Helm.

Installing ArgoCD

Run the following commands to add the Argo Helm repository and install ArgoCD:

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
kubectl create namespace argocd
helm install argocd argo/argo-cd --namespace

Wait for all the ArgoCD components to start:

kubectl get pods -n

Accessing the ArgoCD UI

To access the ArgoCD UI, we'll use port forwarding:

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

Now you can access the ArgoCD UI by visiting https://localhost:8080 in your web browser.

Getting the Initial Admin Password

To retrieve the initial admin password:

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

Use "admin" as the username and the retrieved password to log in to the ArgoCD UI.

Approach 1: Basic GitOps with ArgoCD

In our first approach, we'll set up a direct connection between our Git repository and our Kubernetes cluster.

Understanding the Application Resource

ArgoCD uses an Application custom resource to define which Git repositories to monitor and how to sync them to your cluster.

Here's our first Application resource (argocd/applications/basic-application.yaml):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: grade-submission
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/rslim087a/argocd-kubernetes-gitops-tutorial.git
    targetRevision: HEAD
    path: gitops/basic
  destination:
    server: https://kubernetes.default.svc
    namespace: grade-demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions

Let's break down this configuration:

• name: The name of our application

• source: Defines where ArgoCD should look for our application manifests

  • repoURL: The GitHub repository URL

  • targetRevision: The Git revision to track (HEAD for the latest commit on the default branch)

  • path: The path within the repository where our Kubernetes manifests are located

• destination: Defines where the application should be deployed

  • server: The Kubernetes API server (in this case, the same cluster where ArgoCD is installed)

  • namespace: The target namespace for our application

• syncPolicy: Defines how ArgoCD should sync the application

  • automated.prune: Automatically delete resources that were removed from Git

  • automated.selfHeal: Automatically fix drift between the desired state in Git and the actual state in the cluster

  • syncOptions.CreateNamespace: Create the target namespace if it doesn't exist

Deploying Our First Application

Save the above YAML to a file named basic-application.yaml and apply it:

kubectl apply -f

Now check the ArgoCD UI - you should see your application being synchronized with the Git repository. ArgoCD will create the necessary resources in your cluster based on the Kubernetes manifests in the specified Git repository path.

Forking the Repository and Making Changes

Now let's see GitOps in action by making changes to the repository:

1. Fork the repository https://github.com/rslim087a/argocd-kubernetes-gitops-tutorial to your GitHub account

2. Update your Application resource to point to your forked repository:

source:
  repoURL: https://github.com/YOUR_USERNAME/argocd-kubernetes-gitops-tutorial.git
  targetRevision: HEAD
  path

1. Apply the updated Application resource:

kubectl apply -f

1. In your GitHub repository, navigate to gitops/basic/grade-submission-api-deployment.yaml and modify the number of replicas from 3 to 5

2. Commit the change

Within a minute or two, ArgoCD will detect the change and automatically scale your deployment from 3 to 5 replicas. You can verify this with:

kubectl get pods -n

This demonstrates the core GitOps principle: changes to your infrastructure are made through Git, and ArgoCD automatically applies these changes to your cluster.

Approach 2: Environment Management with Kustomize

As your application grows, you'll typically need different configurations for different environments (development, staging, production). Kustomize helps solve this problem by allowing you to maintain a base configuration and create overlays for environment-specific changes.

Understanding Kustomize Structure

The repository has a Kustomize setup with:

• base/: Contains the base resources (deployment, service)

• overlays/dev/: Contains development-specific configuration (1 replica)

• overlays/prod/: Contains production-specific configuration (3 replicas)

Deploying the Development Environment

Modify the repoURL for the Application inside argocd/applications/kustomize-application.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: grade-submission-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/YOUR_USERNAME/argocd-kubernetes-gitops-tutorial.git
    targetRevision: HEAD
    path: kustomize/overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: grade-demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions

Apply it:

kubectl apply -f

In the ArgoCD UI, you'll see that this application is deployed with the dev- prefix and just 1 replica, as specified in the dev overlay.

Switching to Production Configuration

Now let's create another Application resource for our production environment. Call the file: kustomize-prod-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: grade-submission-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/YOUR_USERNAME/argocd-kubernetes-gitops-tutorial.git
    targetRevision: HEAD
    path: kustomize/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: grade-demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions

Save this as kustomize-prod-application.yaml and apply it:

kubectl apply -f

Now you have both dev and prod versions of your application running simultaneously in the same namespace, with different configurations managed through Kustomize overlays.

Making Changes with Kustomize

Try modifying the replica count in one of the overlay patch files in your GitHub repository. ArgoCD will automatically detect and apply the changes to the appropriate environment.

This demonstrates how Kustomize and ArgoCD together provide a powerful way to manage multi-environment deployments with GitOps principles.

Approach 3: Helm-Based Deployments

For more complex applications, Helm provides powerful templating capabilities and release management. ArgoCD has native support for Helm charts.

Understanding the Helm Chart Structure

The repository contains a Helm chart for our Grade Submission application in the helm/grade-submission directory. This includes:

• Chart.yaml: Basic information about the chart

• values.yaml: Default configuration values for the chart

• templates/: Directory containing Kubernetes resource templates

Deploying with Helm

Modify the repoURL for the Application inside argocd/applications/helm-application.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: grade-submission-helm
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/YOUR_USERNAME/argocd-kubernetes-gitops-tutorial.git
    targetRevision: HEAD
    path: helm/grade-submission
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: grade-helm-demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions

Apply it:

kubectl apply -f

In the ArgoCD UI, you'll see that ArgoCD renders the Helm templates and applies the resulting resources to your cluster.

Customizing Helm Values

Now let's make a change to the Helm values. In your GitHub repository, modify the helm/grade-submission/values.yaml file to change replicaCount from 2 to 4.

After committing this change, ArgoCD will detect it and update your deployment to use 4 replicas instead of 2.

This demonstrates how ArgoCD can work with Helm charts to provide GitOps workflows for more complex applications.

Conclusion

In this tutorial, you've learned how to implement GitOps principles using ArgoCD with Kubernetes in three different ways:

1. Basic GitOps: Direct synchronization from a Git repository. This approach is simple and works well for small projects

2. Kustomize-based GitOps: Managing multiple environments with overlays. This approach excels at managing multiple environments with shared base configurations

3. Helm-based GitOps: Using Helm charts for more complex applications. Helm provides powerful templating and packaging for complex applications

Kubernetes Training

If you find these guides helpful, check out our Kubernetes Training course