Configuration
      Back to home
      1. Help Center
      2. Kargo
      3. Configuration

      Managing Kargo Resources Declaratively via Argo CD

      How to Configure Kargo Projects, Warehouses, and Stages to Be Managed by Argo CD

      If you want to manage your Kargo custom resources (like Projects, Warehouses, and Stages) declaratively via GitOps, Argo CD is the right tool to orchestrate them. This guide walks you through the correct setup for integrating Kargo with Argo CD, ensuring resources are synced in the correct order.

      Step-by-Step Configuration

      Step 1: Integrate Kargo with Argo CD

      Before Argo CD can manage Kargo resources, create a Kargo Integration in the Argo CD UI:

      1. Go to Settings → Integrations → + New Integration.

      2. Select Kargo, and input a recognizable name (e.g., kargo-integration).

      3. This integration allows Argo CD to communicate with the Kargo control plane.

      Step 2: Create an Argo CD Application for Kargo Resources

      Use the integration from Step 1 when defining your Argo CD Application. An example definition:

      apiVersion: argoproj.io/v1alpha1
      kind: Application
      metadata:
        name: kargo-resources
        namespace: argocd
      spec:
        project: default
        source:
          repoURL: https://github.com/your-org/kargo-resources-repo.git
          targetRevision: HEAD
          path: kargo
        destination:
          name: kargo-integration # This should match your integration name
          namespace: default
        syncPolicy:
          automated:
            prune: true
            selfHeal: true

      📌 Note: destination.name must match the name of your Kargo integration.

      Example: kargo-prom-stack.yaml

      Step 3: Configure Resource Sync Order with Sync-Waves

      Ensure that the Kargo Project resource has a lower sync wave (e.g., -1) so it gets created before other Kargo resources like Warehouses or Stages.

      Example project.yaml with sync-wave:

      apiVersion: kargo.akuity.io/v1alpha1
      kind: Project
      metadata:
        name: demo-project
        annotations:
          argocd.argoproj.io/sync-wave: "-1"
      spec:
        description: "A demo project for managing environments"

      🔁 The sync wave ensures the Project is created first, triggering the namespace creation required by other Kargo CRs.

      Reference: project.yaml example

      By following the above three steps, you can reliably manage your Kargo lifecycle using Argo CD. This approach enables a fully declarative GitOps pipeline, ensuring environment consistency and automation across your Kargo resources. With this setup, any changes made to your Kargo configurations in the Git repository will be automatically detected by Argo CD, which will then synchronize these changes to the Kargo control plane. This not only simplifies the management of your resources but also minimizes the risk of human error, as the entire process is governed by version-controlled configurations.