> For the complete documentation index, see [llms.txt](https://dinush-chathurya.gitbook.io/kustomize-e-book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinush-chathurya.gitbook.io/kustomize-e-book/gitops-and-ci-cd/10-argocd-integration.md).

# ArgoCD Integration

ArgoCD is a GitOps continuous delivery tool for Kubernetes that synchronizes your cluster state to the desired state defined in Git. In this chapter, we’ll cover how to integrate your Kustomize-based manifests with ArgoCD to achieve automated, auditable, and reliable deployments.

***

## What Is ArgoCD?

* **GitOps Engine**: ArgoCD continuously watches your Git repositories and Kubernetes clusters.
* **Declarative**: You declare the desired application state in Git; ArgoCD ensures the cluster matches it.
* **Self-healing**: If someone manually drifts your cluster, ArgoCD will revert to the Git-declared state.

***

## GitOps Principles

1. **Single Source of Truth**: All desired state lives in Git.
2. **Declarative Descriptions**: Use declarative configs (Kustomize, Helm, plain YAML).
3. **Automated Sync**: ArgoCD pulls changes automatically or on demand.
4. **Auditable Pipelines**: Every change is a Git commit and PR, making rollbacks easy.

***

## Folder Structure for ArgoCD

Your Git repo might look like this:

```yaml
git-repo/
├── apps/
│   ├── base/                  # Kustomize bases for apps
│   │   └── my-service/        # Base resources for my-service
│   │       └── kustomization.yaml
│   └── overlays/              # Environment overlays
│       ├── dev/
│       │   └── my-service/    # Dev-specific resources for my-service 
│       └── prod/
├── argocd/                    # ArgoCD Application definitions
│   ├── base-app.yaml          # “App of Apps” root
│   ├── dev-app.yaml
│   └── prod-app.yaml
└── README.md
```

## Defining an ArgoCD Application

Create an `Application` CRD that points to a Kustomize overlay:

```yaml
# argocd/dev-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/git-repo.git
    targetRevision: main
    path: apps/overlays/dev/my-service
    directory:
      recurse: true
  destination:
    server: https://kubernetes.default.svc
    namespace: dev-namespace
  syncPolicy:
    automated:
      prune: true           # Remove resources no longer in Git
      selfHeal: true        # Automatically revert out-of-band changes
    syncOptions:
      - CreateNamespace=true
```

## Apps of Apps Pattern

For multi-service repos, use a **root “App of Apps”** pattern:

```yaml
# argocd/base-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: all-apps
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/your-org/git-repo.git
    path: argocd/
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
```

Each child YAML (`dev-app.yaml`, `prod-app.yaml`) lives under `argocd/` and is automatically managed by the root.

## RBAC & Multi-Tenant

* **Projects**: Group Applications into ArgoCD `Projects` for isolation.
* **RBAC**: Define who can sync, override, or delete in each project.
* **Namespaces**: Deploy different environments into separate namespaces or clusters.

## Sync & Health Checks

* **Health Checks**: ArgoCD provides built-in health assessments for Deployments, Services, CRDs, etc.
* **Manual vs Automated**: Use manual sync for change review, automated for fast CI/CD.
* **Hooks**: PreSync/PostSync hooks for DB migrations or canary promotions.

## Best Practices

* Lock to a Git branch or tag (`targetRevision`) for stability.
* Use `CreateNamespace=true` to avoid manual namespace creation.
* Enable `prune` and `selfHeal` for true GitOps.
* Organize apps by project for team boundaries.
* Monitor ArgoCD UI and alerts for sync failures.

## Summary

Integrating Kustomize with ArgoCD gives you a powerful GitOps deployment pipeline: automated syncs, self-healing clusters, and full auditability. Next, learn how to build CI/CD workflows around your Kustomize and ArgoCD setup.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://dinush-chathurya.gitbook.io/kustomize-e-book/gitops-and-ci-cd/10-argocd-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.