ArgoCD GitOps Workflow Setup Guide

GitOps simplifies infrastructure management by using Git as the source of truth, ensuring your Kubernetes deployments remain consistent and automated. ArgoCD, a tool designed for Kubernetes, implements GitOps principles by syncing your infrastructure with configurations stored in Git. This approach reduces errors, improves collaboration, and ensures traceability of changes.

Key Highlights:

• GitOps Principles: Declarative configurations, version control, automated pull-based updates, and continuous reconciliation.
• ArgoCD Features: Monitors Git repositories, syncs Kubernetes clusters, supports manifests, Helm charts, and Kustomize.
• Benefits for UK Businesses: Reduced downtime, compliance-friendly audit trails, and streamlined collaboration.

Steps to Get Started:

1. Environment Prep: Set up a Kubernetes cluster (e.g., Minikube, EKS, AKS) and install tools like kubectl and Helm.
2. Install ArgoCD: Deploy ArgoCD to your cluster, access its UI, and configure security settings.
3. Connect Git: Link your Git repository using HTTPS or SSH for secure synchronisation.
4. Set Sync Policies: Automate deployments, enable self-healing, and define sync windows.
5. Monitor and Troubleshoot: Use ArgoCD's dashboard and Prometheus metrics to track and resolve issues.

ArgoCD’s automation ensures your infrastructure stays aligned with Git, helping you save time, reduce costs, and maintain consistency across environments.

GitOps with ArgoCD - Complete hands-on workshop

Prerequisites and Environment Setup

Getting your tools and environment ready is the first step to avoiding setup headaches and saving time.

Required Tools and Resources

To deploy ArgoCD, you'll need a running Kubernetes cluster. This could be anything from a local setup using Minikube to a cloud-managed service like Amazon EKS, Azure AKS, or Google GKE. For production environments, aim for a cluster with at least three nodes to maintain high availability and ensure resources are well-distributed [1].

You'll also need kubectl, the go-to tool for managing Kubernetes clusters. Make sure it's installed and configured with a kubeconfig file (usually located at ~/.kube/config) containing the required authentication details and connection settings.

For production-grade setups, using Helm to install ArgoCD is highly recommended. Helm simplifies managing Kubernetes applications, making it easier to configure and upgrade ArgoCD. Ensure the Helm client is installed and ready to use on your local machine.

If you're working with MicroK8s, enable CoreDNS by running:
microk8s enable dns.

Setting Up the Kubernetes Environment

Once your tools are in place, it's time to configure your Kubernetes environment. First, ensure kubectl has cluster admin permissions. This elevated access is necessary during the initial setup but can be scaled back for daily operations later.

Create a dedicated namespace for ArgoCD to keep its components organised and secure. Check that your cluster can handle the required resources. While ArgoCD isn't overly demanding, it still needs enough CPU and memory to monitor repositories and synchronise applications effectively. Make sure your cluster's networking is configured correctly to allow smooth communication between ArgoCD components and external Git repositories.

To verify everything is working, deploy a simple application to the cluster. This will help you identify any potential issues with networking, DNS, or RBAC configurations.

Preparing the Git Repository

Your Git repository acts as the single source of truth for your infrastructure, so setting it up correctly is crucial. Ensure it contains valid Kubernetes manifests in formats ArgoCD supports, such as YAML files, Helm charts, or Kustomize configurations.

Organise your repository logically. For instance, you could create separate directories for different environments like development, staging, and production. Using a clear structure - such as folders named apps/, infrastructure/, and environments/ - makes navigating and understanding the repository much easier.

Before committing anything, validate your manifests. You can use kubectl's dry-run mode or YAML linting tools to catch errors early.

Set up proper access controls for the repository. ArgoCD requires read access to pull configurations, while your development team will need write access to push changes. Instead of relying on personal credentials, use deploy keys or service accounts for managing access securely.

Finally, test your repository setup by manually applying some configurations to a test cluster. This will help you confirm that your manifests are correct and uncover any dependencies or sequencing issues that could disrupt ArgoCD's ability to synchronise applications.

For better collaboration, use clear commit messages, create branches for major changes, and review pull requests carefully. Since every commit to the main branch may trigger a deployment, keeping things organised is key.

Once your repository is structured and validated, you're ready to move on to installing and configuring ArgoCD.

Installing and Configuring ArgoCD

Now that your environment is ready and your Git repository is organised, it's time to install ArgoCD and connect it to your repositories. A proper setup ensures a smooth and reliable GitOps workflow from the beginning.

Installation Steps

Start by creating a namespace and installing ArgoCD with the following commands:

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

This installs ArgoCD's core components, such as the API server, repository server, and application controller. To confirm everything is running as expected, check the pods:

kubectl get pods -n argocd

To access the ArgoCD web interface, use port forwarding:

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

Once set up, open the UI at https://localhost:8080. For production, it's better to configure an ingress controller or load balancer.

The initial admin password is stored as a Kubernetes secret. Retrieve it with this command:

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

If you'd like to manage ArgoCD via the command line, install the ArgoCD CLI. On macOS, you can use Homebrew:

brew install argocd

For Linux, download the binary directly from the ArgoCD releases page. Once installed, log in using the CLI:

argocd login localhost:8080 --username admin --password <retrieved-password>

Don't forget to change the default admin password immediately after logging in to enhance security.

With ArgoCD installed, the next step is connecting it to your Git repositories.

Connecting ArgoCD to Git Repositories

ArgoCD relies on Git repositories to monitor and deploy applications. It's best to use access tokens for authentication.

For GitHub, generate a Personal Access Token (PAT) with repository read permissions. Go to GitHub Settings > Developer settings > Personal access tokens, create a new token, and store it securely.

Add your repository using the ArgoCD CLI, specifying any username and the PAT as the password:

argocd repo add https://github.com/your-org/your-repo --username token --password <your-access-token>

Alternatively, use the web interface. Navigate to Settings > Repositories, click Connect Repo using HTTPS, and provide the repository URL, a username, and the PAT as the password.

For SSH-based access, add the repository using the private key:

argocd repo add [email protected]:your-org/your-repo.git --ssh-private-key-path ~/.ssh/id_rsa

ArgoCD securely stores repository credentials as Kubernetes Secrets within its namespace. This ensures sensitive data, like private keys and tokens, remain protected. The repository server handles these connections without storing credentials directly, and sensitive data is redacted from logs and API responses.

Once your repository is connected, you can create applications. For example:

argocd app create my-app \
  --repo https://github.com/your-org/your-repo \
  --path apps/my-app \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

After establishing the connection, it's time to set up sync policies to streamline deployment workflows.

Configuring Sync Policies and Health Checks

Sync policies define how ArgoCD handles differences between your repository and the cluster. By default, changes detected in Git require manual approval before being applied.

To enable automatic synchronisation for applications, use this command:

argocd app set my-app --sync-policy automated

For added reliability, configure self-healing to automatically fix configuration drift caused by manual changes in the cluster:

argocd app set my-app --auto-prune --self-heal

• --auto-prune: Removes resources from the cluster if they're no longer in Git.
• --self-heal: Reverts manual changes in the cluster to match the Git-defined state.

You can also define sync windows to control when automatic deployments happen. This is especially useful for production environments where deployments may need to avoid peak business hours:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
spec:
  syncWindows:
  - kind: deny
    schedule: '0 9-17 * * MON-FRI'
    duration: 8h
    timeZone: 'Europe/London'

ArgoCD also uses health checks to report the status of your applications. While most Kubernetes resources come with built-in health checks, you can define custom checks for more complex setups. For instance, you can set resource hooks to handle tasks like database migrations, ensuring everything deploys in the correct order.

Monitor the sync status through the web interface or CLI. Applications are marked as Healthy when all resources are running correctly and Synced when the cluster matches the Git repository. If you see an OutOfSync status, it means there are discrepancies that need attention.

For applications with multiple components, you can control the deployment order using sync waves. Add annotations to your manifests like this:

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"

Resources with lower numbers deploy first, ensuring dependencies are ready before dependent services start.

With ArgoCD up and running, you're now equipped to implement a GitOps workflow that keeps your applications aligned with your Git repository.

Setting Up GitOps Workflow with ArgoCD

Once ArgoCD is configured and linked to your repositories, you're ready to create a seamless GitOps workflow. This setup automates deployments, ensuring that changes in your code are reflected in live clusters without manual intervention.

Complete Workflow Process

A GitOps workflow ensures that every step - from committing code to synchronising clusters - is automated. Here's how it works: the CI pipeline builds your application, generates a Docker image, updates the GitOps repository, and prompts ArgoCD to align the cluster's state with the repository.

When developers push code changes, the CI pipeline kicks into gear. It builds the application, runs tests, and creates a Docker image tagged with a unique identifier (often the commit hash). This image is then pushed to a container registry.

Below is an example CI pipeline using GitHub Actions:

name: Build and Deploy
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: |
          docker build -t ghcr.io/your-org/your-app:${{ github.sha }} .
          docker push ghcr.io/your-org/your-app:${{ github.sha }}

      - name: Update GitOps repository
        run: |
          git clone https://github.com/your-org/gitops-repo
          cd gitops-repo
          sed -i 's|image: ghcr.io/your-org/your-app:.*|image: ghcr.io/your-org/your-app:${{ github.sha }}|' apps/production/deployment.yaml
          git commit -am "Update image to ${{ github.sha }}"
          git push

In this setup, the CI pipeline handles building and pushing images, while the GitOps repository stores Kubernetes manifests. ArgoCD monitors the repository and ensures the live cluster state matches what's defined in Git [2].

Once the CI pipeline updates the repository with the new image tag, ArgoCD detects the change during its reconciliation cycle. By default, this happens every three minutes, though you can adjust the interval for quicker updates. During reconciliation, ArgoCD applies the updated manifests automatically, ensuring that the cluster state reflects the latest changes.

ArgoCD’s web interface offers a clear view of the process, showing sync statuses and resource health, which can be invaluable for troubleshooting.

After deployment, it's essential to keep the live cluster in sync with the repository to avoid configuration issues.

Preventing Configuration Drift

Configuration drift occurs when manual changes deviate the cluster state from what's defined in Git. ArgoCD addresses this by continuously monitoring and reverting any unauthorised changes, maintaining consistency.

As discussed earlier, ArgoCD ensures that the declared state in Git matches the live cluster. This real-time synchronisation highlights and resolves configuration drift, supports predictable rollbacks, and keeps the build and deployment pipelines distinct [3].

Monitoring, Troubleshooting, and Cost Management

Keeping a GitOps workflow running smoothly requires effective monitoring, troubleshooting, and a keen eye on costs. ArgoCD offers tools that bring real-time visibility into deployments while helping manage expenses efficiently.

Monitoring and Auditing with ArgoCD

ArgoCD's Application Dashboard is your go-to for monitoring, providing an overview of application statuses in real time. It shows sync statuses like Synced or OutOfSync, health statuses such as Healthy or Degraded, and recent activity logs. This makes it easy to stay on top of your deployment pipeline and quickly spot any issues [6][7].

For deeper insights, ArgoCD integrates with Prometheus, exposing metrics from its core components - Application Controller, API Server, and Repo Server. These metrics help you assess system performance and make informed adjustments. Some key metrics include:

• argocd_app_info: Displays application details.
• argocd_app_reconcile: Tracks reconciliation performance.
• argocd_app_sync_total: Monitors sync history.

ArgoCD also evaluates the health of Kubernetes resources based on specific criteria:

Additionally, the dashboard provides access to detailed event logs, offering a clear view of sync operations and errors. These logs are invaluable for troubleshooting and serve as robust audit trails. For proactive management, you can configure ArgoCD Notifications to send alerts about sync failures, health changes, or successful deployments across multiple channels.

Armed with these tools, you can tackle common issues effectively.

Common Troubleshooting Solutions

Here are some typical problems and how to address them:

• Missing target namespaces: Ensure the required namespaces exist or enable CreateNamespace=true in the application configuration.
• YAML manifest errors: Validate your manifests using kubectl --dry-run=client before committing changes.
• RBAC permission issues: Confirm that the ArgoCD service account has the correct cluster roles and role bindings.
• Connectivity problems: Use the dashboard to monitor component health and track cluster connectivity with the argocd_cluster_connection_status metric [5].
• Custom resource checks: Define Lua-based custom health checks to validate business-specific logic beyond Kubernetes' default probes [4].

Consistency in monitoring and troubleshooting not only ensures a stable workflow but also lays the groundwork for managing cloud costs effectively.

Cloud Cost Reduction

GitOps workflows powered by ArgoCD can help cut cloud expenses by enforcing resource limits, scaling policies, and automating environment teardowns. By defining scaling policies in your GitOps repository, you ensure applications scale with demand - avoiding over-provisioning and unnecessary costs.

Resource quotas and limits set through GitOps prevent excessive deployments that could lead to unexpected bills. ArgoCD's drift detection capabilities also play a role by identifying unauthorised changes, such as manually scaled deployments or additional resources created outside the workflow. These changes can be flagged and corrected before they inflate costs.

Hokstad Consulting, known for its expertise in cloud cost engineering, can assist in fine-tuning your GitOps workflows. Their approach has helped organisations achieve cost savings of up to 30–50%, ensuring that your ArgoCD setup not only enhances deployment reliability but also maximises cost efficiency.

The automated nature of GitOps workflows makes it easier to manage both technical and financial aspects. Regularly analysing metrics like sync duration and frequency through ArgoCD's Prometheus integration can uncover opportunities to optimise infrastructure and rightsize applications, keeping your cloud costs in check.

Conclusion

ArgoCD GitOps is reshaping how Kubernetes deployments are managed in the UK, offering a declarative, automated, and secure approach to infrastructure. This reduces errors and ensures greater reliability, making it an essential tool for modern businesses.

Key Takeaways

With ArgoCD's GitOps workflow, operational efficiency gets a major boost while costs become more manageable. Its automated sync feature ensures applications remain aligned with Git repository definitions, effectively eliminating configuration drift - a common source of production headaches. For UK businesses navigating strict compliance requirements, the ability to track and audit every change through Git history is a game-changer.

Real-time monitoring enhances visibility, enabling teams to quickly address issues. When paired with Prometheus metrics, it provides deeper insights into system performance, helping organisations make informed decisions about optimising their infrastructure.

GitOps workflows also bring predictability to cost management. By defining resource limits, scaling policies, and configurations directly in Git, companies can avoid over-provisioning and prevent unauthorised resource usage. Drift detection further ensures manual changes don't lead to unexpected expenses, keeping cloud costs under control.

On the security front, ArgoCD's pull-based deployment model strengthens protection by pulling changes from Git instead of requiring external access to clusters. This reduces potential attack vectors while adhering to the principle of least privilege access.

For businesses looking to implement or refine their GitOps approach, Hokstad Consulting offers tailored solutions and ongoing support.

How Hokstad Consulting Can Help

Hokstad Consulting specialises in optimising ArgoCD GitOps workflows, combining expertise in DevOps and cloud cost management to deliver impressive results. Their clients have seen cloud costs reduced by 30–50%, alongside improvements in deployment speed and reliability.

Their services go beyond initial setup, offering strategic cloud migration, custom automation, and continuous infrastructure monitoring. Whether you're working with public, private, or hybrid cloud setups, Hokstad Consulting crafts solutions tailored to your business needs and compliance standards.

What sets Hokstad apart is their ability to integrate AI-driven automation into GitOps environments. Their expertise in AI strategy, combined with traditional DevOps practices, ensures your infrastructure management evolves with industry trends, giving your business a competitive edge.

Flexible support options are available, designed to align with your unique requirements. Hokstad Consulting is ready to help you take your GitOps workflow to the next level.

FAQs