DOCSEARCHbyAlgolia
Submit Docs

Argo CD Diff Preview

repository·main·Indexed 20 days ago

https://github.com/dag-andersen/argocd-diff-preview

A tool that provides accurate Kubernetes manifest diffs for GitOps workflows by leveraging Argo CD's rendering engine. It allows developers to visualize the impact of changes in Helm or Kustomize templates within Pull Requests. The tool supports three rendering modes (cli, server-api, and repo-server-api) and can be run locally via Docker or integrated into GitHub Actions.

Tokens
56.6K
Snippets
93
Records
136
Agent score
72%

What's inside argocd-diff-preview

  1. Overview of Argo CD Diff Preview

    main

    Argo CD Diff Preview is a tool that renders the diff between two branches in a Git repository by using Argo CD itself to generate the manifests. This ensures that the diff is as accurate as possible, especially when using templating tools like Helm or Kustomize. It functions similarly to Atlantis for Terraform, providing a clear view of proposed changes in Pull Requests.

    Key capabilities include:

    • Accurate diffs: Uses Argo CD's own rendering engine.
    • Isolation: Supports running with ephemeral clusters so no access to production clusters is required.
    • Speed: Can connect to pre-installed Argo CD instances to skip cluster creation.
    • Flexibility: Supports private repositories, Helm charts, multi-source applications, and ApplicationSets.
    • Filtering: Includes smart filtering for applications and --diff-ignore to filter out noisy changes like version bumps.

  2. Limitations of Lockdown Mode

    main

    When running in Lockdown Mode (namespace-scoped), be aware of the following constraints:

    • UI Status: Applications will appear with an "Unknown" status in the Argo CD UI because the application controller lacks permission to access the destination namespaces.
    • ApplicationSets: Certain ApplicationSet generators that require cluster-wide access may fail to function correctly.

  3. Configure Multi-repo diffs with two key rules

    main

    To successfully run argocd-diff-preview across multiple repositories, follow these two rules:

    Rule 1: Match --repo to the PR repository

    The --repo flag must match the repository where the Pull Request was opened. This allows the tool to correctly redirect the targetRevision of applications to the PR branch. The tool only redirects applications whose spec.source.repoURL matches this flag.

    Rule 2: Always clone the Application Repository

    The /base-branch and /target-branch directories inside the container must contain the Application Repository (the one containing the Argo CD manifests), regardless of which repository is running the pipeline. This is because the tool looks for Application and ApplicationSet manifests in these folders.

  4. Compatibility with Argo CD ApplicationSets

    main

    The tool supports most ApplicationSet generators, though behavior varies by generator type:

    • List, Git, Matrix, and Merge generators: Fully supported with no reported issues.
    • Cluster generator: Supported, but you must add ClusterSecrets to the secrets folder.
    • Plugin generator: Supported in theory but not explicitly tested. Requires proper Config Management Plugin (CMP) installation.
    • Pull Request generator: Supported in theory but not explicitly tested.
    • SCM Provider and Cluster Decision Resource generators: Not tested.

  5. Understand the three render methods and RBAC requirements

    main

    The argocd-diff-preview tool supports three rendering modes, which dictate how manifests are generated and what Kubernetes RBAC configuration is required in the test cluster.

    ModeCluster RolesDescription
    cliEnabledUses the argocd CLI to render manifests.
    server-api (default)DisabledUses the Argo CD REST API directly.
    repo-server-api (experimental)DisabledCalls the Argo CD repo-server gRPC API directly.

    When switching between modes that require different RBAC configurations (e.g., moving from cli to server-api), the test harness automatically deletes and recreates the cluster.

  6. Understand the Argo CD Diff Preview output format

    main

    The Argo CD Diff Preview generates a summary and detailed diffs of changes within an Argo CD environment.

    Summary Section

    The output begins with a high-level summary of changes, categorized by status:

    • Added: New resources being introduced (e.g., + level-1c-staging-app (+8) indicates a new resource with 8 lines of changes).
    • Modified: Existing resources that have changes (e.g., ± level-1a-app (+13) indicates 13 lines added, or ± level-1b-app (+1|-1) indicates 1 line added and 1 line removed).

    Detailed Diff Section

    Each resource change is presented in a collapsible section containing:

    1. Resource Header: The name of the resource and its parent (e.g., level-1a-app (parent: root-app)).
    2. Resource Type and Location: The specific Kubernetes kind and namespace (e.g., Application: argocd/level-2c-app or ConfigMap: default/level-1b-config).
    3. Unified Diff: A standard diff block showing exactly what changed:
      • + lines: New content being added.
      • - lines: Content being removed.
      • (space) lines: Unchanged context.

  7. Interpret Diff Preview summary and resource changes

    main

    The output uses specific notation to describe changes:

    • Deleted: Resources that will be removed from the cluster.
    • Modified: Resources that exist but have changes in their specification (e.g., image tag updates, port changes, or replica count changes).
    • Renames: If a resource shows old-name -> new-name with the note Application name changed, but rendered resources are unchanged, it indicates a metadata change rather than a functional resource change.

    Example summary format:

    Deleted (1):
- folder2 (-19)

Modified (3):
± app1 -> app2
± multi-source-app (+2|-2)
± nginx-ingress (+1|-1)

  8. Optimize rendering with the Watch Pattern Annotation

    main

    To speed up manifest rendering in large monorepos, you can use the argocd-diff-preview/watch-pattern annotation to define which file paths trigger a render for a specific application. When files matching these patterns change in a pull request, the application is rendered. Applications are also automatically rendered if their own manifest file changes.

    Key requirements:

    • The annotation must exist in the base branch for filtering to work correctly.
    • The annotation accepts a comma-separated list of file paths or regex patterns.

    For ApplicationSets: You must add the annotation in two places to ensure both the set and its generated applications are covered:

    1. On the ApplicationSet itself (metadata.annotations).
    2. On the template that generates applications (spec.template.metadata.annotations). You can use generator variables like {{ .path.basename }} within the pattern.
    apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    argocd-diff-preview/watch-pattern: |
      examples/helm/charts/myApp/.*,
      examples/helm/values/filtered.yaml

  9. Handle App of Apps patterns in argocd-diff-preview

    main

    The App of Apps pattern involves a parent Application rendering child Application manifests. argocd-diff-preview handles this in two ways depending on how the child applications are stored:

    1. Plain YAML files: If child Application or ApplicationSet manifests are committed as files in your repository, the tool detects them automatically without extra configuration.
    2. Generated manifests: If child applications are generated dynamically (e.g., via Helm or Kustomize inside a parent Application), they are invisible to the file scanner. You must either pre-render them into the branch or use the experimental --traverse-app-of-apps flag.

    Recommendation: Prefer pre-rendering manifests in your CI pipeline over using the traversal flag, as traversal is slower and more limited.

  10. Understand Multi-repo support terminology

    main

    When using argocd-diff-preview in a multi-repo setup, it is important to distinguish between two types of repositories:

    • Application Repository: Contains Argo CD Application and ApplicationSet manifests.
    • Resource Repository: Contains the actual Kubernetes resources (Helm charts, Kustomize overlays, plain YAML) referenced by the applications.

    To trigger diffs for changes in either repository, you must implement a pipeline in both.

  12. Understand the core design principles of argocd-diff-preview

    main

    The argocd-diff-preview tool is designed around three primary principles to ensure reliability and accuracy in Pull Request reviews:

    1. Avoid false negatives at almost all costs: The tool is intentionally pessimistic when selecting and filtering Applications. It prioritizes rendering too many Applications over missing one, ensuring that users can trust that every relevant change is captured in the diff.
    2. Use Argo CD to render manifests: To avoid the complexity of re-implementing Helm, Kustomize, Jsonnet, or custom plugin logic, the tool uses Argo CD itself to perform manifest rendering. This ensures that the diffs accurately reflect how Argo CD will actually interpret the manifests.
    3. Compare desired states, not actual states: Instead of comparing Git manifests against the live state in a Kubernetes cluster, the tool compares the desired state of two Git branches (e.g., main vs. a feature branch).