Understanding Argo CD: Kubernetes GitOps Made Simple

What Is Argo CD?

Argo CD is a Kubernetes-native continuous deployment (CD) tool. Unlike external CD tools that only enable push-based deployments, Argo CD can pull updated code from Git repositories and deploy it directly to Kubernetes resources. It enables developers to manage both infrastructure configuration and application updates in one system.

Argo CD offers the following key features and capabilities:

Manual or automatic deployment of applications to a Kubernetes cluster.
Automatic synchronization of application state to the current version of declarative configuration.
Web user interface and command-line interface (CLI).
Ability to visualize deployment issues, detect and remediate configuration drift.
Role-based access control (RBAC) enabling multi-cluster management.
Single sign-on (SSO) with providers such as GitLab, GitHub, Microsoft, OAuth2, OIDC, LinkedIn, LDAP, and SAML 2.0
Support for webhooks triggering actions in GitLab, GitHub, and BitBucket.

This is part of an extensive series of guides about Kubernetes.

GitOps with Argo CD

GitOps is a software engineering practice that uses a Git repository as its single source of truth. Teams commit declarative configurations into Git, and these configurations are used to create environments needed for the continuous delivery process. There is no manual setup of environments and no use of standalone scripts—everything is defined through the Git repository.

A basic part of the GitOps process is a pull request. New versions of a configuration are introduced via pull request, merged with the main branch in the Git repository, and then the new version is automatically deployed. The Git repository contains a full record of all changes, including all details of the environment at every stage of the process.

Argo CD handles the latter stages of the GitOps process, ensuring that new configurations are correctly deployed to a Kubernetes cluster.

At a high level, the Argo CD process works like this:

A developer makes changes to an application, pushing a new version of Kubernetes resource definitions to a Git repo.
Continuous integration is triggered, resulting in a new container image saved to a registry.
A developer issues a pull request, changing Kubernetes manifests, which are created either manually or automatically.
The pull request is reviewed and changes are merged to the main branch. This triggers a webhook which tells Argo CD a change was made.
Argo CD clones the repo and compares the application state with the current state of the Kubernetes cluster. It applies the required changes to cluster configuration.
Kubernetes uses its controllers to reconcile the changes required to cluster resources, until it achieves the desired configuration.
Argo CD monitors progress and when the Kubernetes cluster is ready, reports that the application is in sync.
ArgoCD also works in the other direction, monitoring changes in the Kubernetes cluster and discarding them if they don’t match the current configuration in Git.

How does Argo CD make it happen?

GitOps agent—Argo CD is responsible for pulling updated code from Git repositories and deploying it directly to Kubernetes resources. It manages both infrastructure configuration and application updates in one system.
Custom Resource Definitions (CRD)—Argo CD operates in its own namespace within a Kubernetes cluster. It provides its own CRDs that extend the Kubernetes API and make it possible to define the desired application state in a declarative way. Based on the instructions in a Git repo or a Helm repo, Argo CD uses its CRDs to implement the changes within its dedicated namespace.
CLI—Argo CD offers a powerful CLI that lets you create YAML resource definitions with a few simple commands. For example, the Argo CD app create command lets you specify a few flags and create a valid Application object that describes your application, with no need to write YAML by hand.
User Interface—Argo CD is unique in that it offers a convenient web-based UI that lets you do the same thing, define an application and ask Argo CD to create the relevant YAML configurations. It also lets you visualize the resulting Kubernetes configuration in terms of pods and containers. While some may think using a UI is not “true” GitOps, that is not really true, because the UI is not used to directly control the cluster, only as an easier way to create the declarative configuration.

Source: Argo CD

Multi-tenancy—Argo CD has strong support for multiple teams working on different projects in the same Kubernetes environment. Argo CD CRDs can be restricted to only read source repositories that belong to a certain project, and can be set to deploy applications to a specific cluster and namespace. Each CRD instance can also have its own role-based access control (RBAC) settings.
Leveraging existing tools—many organizations have already invested in declarative configurations based on YAML, Helm charts, Kustomize, or other systems. Argo CD aims to leverage these existing investments rather than replace them. It can use any of these formats to automatically create the relevant CRD definitions.

Learn more in our detailed guide to Argo CD and Terraform

TIPS FROM THE EXPERT

Automate secret management: Integrate tools like HashiCorp Vault or AWS Secrets Manager with Argo CD to handle secrets dynamically. This ensures that secrets are securely managed and updated without manual intervention.
Integrate with existing CI pipelines: Use Argo CD in conjunction with CI tools like Jenkins or GitHub Actions to create a seamless CI/CD pipeline. Trigger deployments automatically when new changes are pushed to your Git repository.
Implement policy enforcement: Use tools like Open Policy Agent (OPA) with Gatekeeper to enforce policies on your Kubernetes resources. This ensures that all deployments adhere to organizational standards and best practices.
Utilize Argo Rollouts for advanced deployment strategies: Combine Argo CD with Argo Rollouts to implement advanced deployment strategies such as blue-green, canary, or progressive delivery. This provides more control and reduces the risk of failures during deployment.
Monitor Git repositories for security: Regularly scan your Git repositories for vulnerabilities and misconfigurations. Tools like Snyk or Trivy can be integrated into your pipeline to provide continuous security assessments.

How Argo CD Works

When using Argo CD, you can specify application configuration using several types of Kubernetes manifests, including plain YAML or JSON manifest; Helm charts; Kustomize; and Ksonnet and Jsonnet applications. It is also possible to use any custom configuration management tool as a plugin.

Argo CD automatically deploys the desired state of an application in a specified target environment. Updates are traceable as tags, branches, or pinned specific versions of a manifest at Git commits.

Image Source: Argo CD

Argo CD is a Kubernetes controller, responsible for continuously monitoring all running applications and comparing their live state to the desired state specified in the Git repository. It identifies deployed applications with a live state that deviates from the desired state as OutOfSync. Argo CD reports the deviations and provides visualizations to help developers manually or automatically sync the live state with the desired state.

Argo CD can automatically apply any change to the desired state in the Git repository to the target environment, ensuring the applications remain in sync.

Below we outline the basic components of Argo CD.

API

A gRPC/REST API server exposes the API that components such as the CLI and Web UI consume. It is responsible for:

Managing applications and reports status
Invoking app operations such as user-specified actions, sync, and rollback
Managing cluster and repository credentials stored as Kubernetes secrets
Authenticating and delegating authorization to third-party identity providers
Enforcing RBAC policies
Listening and forwarding Git webhook events

Repository Service

The internal repository service caches the Git repository locally, storing the application manifests. The repository server generates Kubernetes manifests and returns them based on inputs such as the repository URL, application path, revisions (i.e., commits, tags, branches), and any template-specific settings (i.e., Helm values, Ksonnet environments, parameters).

Application Controller

This component is a Kubernetes controller that continuously monitors applications, comparing the target state specified in the Git repository with the current state of each application. The applications controller identifies when an application is OutOfSync and can implement corrections where specified. It invokes hooks defined by the user for application lifecycle events such as PreSync, Sync, and PostSync.

For more information, you can reference the Argo CD project GitHub repository, here.

Learn more in our guide: Argo Kubernetes: Making GitOps Work in Your Kubernetes Clusters

Argo CD Installation

There are several ways to install Argo CD, including core installation, multi-tenant, Kustomize, and Helm chart.

Core Installation

The command for installing Argo CD Core is:

kubectl create namespace argocd

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

To configure the CLI, run this command:

argocd login --core

Core installation is best suited to cluster admins who use Argo CD independently and don’t require multi-tenancy features. This type of installation has the fewest components and is thus easy to set up. It installs lightweight versions of the components and doesn’t support high availability. There is no UI or API server included in the package.

The end-user must have access to Kubernetes to manage Argo CD. To set up core installation, the cluster administrator must configure the Argo CD CLI using the following script:

kubectl config set-context --current --namespace=argocd # change current kube context to Argo CD namespace

argocd login --core

The admin dashboard command also enables access to the Argo CD Web UI.

Core installation manifest packages are available at core-install.yaml. To learn more about the core installation, go here.

Multi-Tenant Installation

Multi-tenant installation is the most popular type of Argo CD installation. It typically serves multiple Dev teams and requires a platform team to maintain it. The API server allows end-users to access Argo CD using the argocd CLI or Web UI. The CLI requires configuration using this command:

argocd login <server-host>

To learn more about how to access the Argo CD Server and multi-tenant installation, go here.

Argo offers two types of installation manifests:

High Availability (HA)—the recommended package for production use, it includes the same components as the standard non-HA installation but is optimized for high availability and resiliency. HA multi-tenant installation manifests are available at ha/install.yaml and ha/namespace-install.yaml . These packages provide multiple replicas for supported components.
Non-HA—this package is not ideal for production use. It is useful for testing and demos during the evaluation period. Non-HA multi-tenant installation manifests are available at install.yaml and namespace-install.yaml. The first manifest package is the standard installation requiring cluster-administrator access and is useful for deploying multiple applications in the cluster where Argo CD runs. The second package only requires namespace-level privileges and is useful for deploying applications in a different cluster, relying exclusively on inputted cluster credentials.

Kustomize Installation

It is also possible to install Argo CD manifests using Kustomize. Organizations using this option should maintain the manifest as a remote resource and use Kustomize patches to apply customizations.

kind: Kustomization

namespace: argocd
resources:
- https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/ha/install.yaml

Helm Installation

Argo CD can also be installed via Helm chart. Open source community-maintained Helm charts are available at argo-helm/charts/argo-cd.

Learn more in our detailed guide to Using Argo CD with Helm Charts.

Argo CD Best Practices

Here are some best practices for effectively adopting Argo CD.

Separating Source Code and Configuration Repositories

It is best to use separate Git repositories for Kubernetes manifests and application source code. Maintaining separation between source code and config repos makes them more manageable, enabling modification of one without affecting the other. For example, developers can scale up replicas in a deployment specification without triggering a new application build.

Another reason to keep repos separate is to maintain cleaner logs for auditing purposes. Separate repos help reduce the noise from regular development activity and make it easier to trace the Git history. It is also more secure to separate access to source code and Kubernetes manifests, given that different individuals might handle each. This separation helps restrict commit access and prevents developers from accidentally misconfiguring the application.

Microservices applications often include services that use different versioning and release cycles, so it is preferable to store the manifests in separate components. For automated CI pipelines, pushing config changes to a single Git repository may initiate a build job loop and trigger infinite Git commits.

Selecting a Suitable Number of Deployment Configuration Repositories

It is important to consider how many repos should house an organization’s deployment configurations. Organizations have varying requirements based on their scale and complexity.

Generally, small companies that don’t rely heavily on automation, and where all employees are trusted, can use a mono-repo. Mid-sized companies that use some automation should use a repository for each team, while larger organizations that require greater control and rely significantly on automation should use repositories for each service.

Teams can often manage themselves if they have their own repository. Each team can decide who has release access, so there is no need for a central team that gives write access to each team, which may create a release bottleneck.

Testing Manifests Before Each Commit

Software engineers often commit changes to manifests and allow the GitOps agent to try deploy the application, thus validating the changes. Testing changes before pushing them to a manifest helps prevent the introduction of issues into pre-production.

Typically, the agent uses a Helm chart or other template to generate the manifests. Engineers can run commands locally to test their manifests before they commit any changes.

Preventing External Changes to Manifests

Configuration drift has long been an issue for production deployments. Configuration differences between the target machines of a CI/CD deployment can cause it to fail. Developers sometimes use staging environments to test applications before deploying them to production. A staging environment should ideally have the same configuration as the production environment, ensuring that any tests reflect the real conditions of the live application.

However, teams often change Kubernetes clusters using ad-hoc commands, not part of the CI/CD process. These changes contribute to configuration drift and impact application deployments. For example, an application might pass all the testing in the staging environment but fails when deployed to production.

Argo CD helps prevent configuration drift and maintain state traceability by using Git as a single source of truth for all current and past deployments. The Git history enables retrospective investigation. However, all manifest changes must go through Argo CD to maintain a clean history. If, for example, a developer uses kubectlto make changes directly, Argo CD can detect this and mark the application as OutOfSync.

Argo CD offers an auto-sync capability that, when enabled, eliminates configuration drift for Kubernetes applications. It is important to ensure that all changes to a manifest are committed to the Git repository. Kustomize and Helm support different manifests for a single commit, so developers using these should pin the dependencies to specific commits.

Learn More in the Manning Report: GitOps with ArgoCD

Software teams that adopt GitOps deploy more often, have fewer regressions, and recover from failures more quickly. GitOps works, as evidenced by many success stories we at Codefresh have seen firsthand. Learn more about GitOps in an in-depth guide by Alexander Matyushentsev, one of the founders of the Argo project. Argo is the world’s fastest-growing and most popular open-source GitOps tool in the world today. Users love it, and that is the reason Codefresh has based its enterprise platform on the beloved tool.

Learn to practice GitOps with Argo CD in the Manning Report: GitOps with Argo CD

See Additional Guides on Key Kubernetes Topics

Together with our content partners, we have authored in-depth guides on several other topics that can also be useful as you explore the world of Kubernetes.