Introduction to dag-andersen/argocd-diff-preview

This slide was presented at an internal company event.

Transcript

1. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 1 Introduction to dag-andersen/argocd-diff-preview Mar 11, 2026 Yuya Koda
2. AbemaTV, Inc. All Rights Reserved Yuya Koda I work primarily with Google Cloud, managing infrastructure across ABEMA and building CI/CD systems. I spend a lot of time writing YAML, JSON, HCL, and Go. Outside of work, I enjoy coffee. 2 Profile ponkio_o
3. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved Who here uses Argo CD? ✋ 3
4. AbemaTV, Inc. All Rights Reserved Background 4
5. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 5 Argo CD and Diff Argo CD provides a UI that shows the diff between the state in Git and the actual resources. If automatic sync is disabled, you can review the diff in the UI and apply the changes manually.
6. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 6 Argo CD and Sync Policy Argo CD has an option that automatically reconciles differences between Git and the actual resources. This ensures the actual state always matches the state defined in Git. To implement GitOps properly, it’s generally recommended to enable this option.
7. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 7 Self-Heal and Diff When the Self-Heal option is enabled, synchronization occurs immediately after a change is merged into the tracked branch (especially when using webhooks). As a result, it becomes difficult to review the diff before applying changes manually. “I want to see the Argo CD diff at the PR stage.”
8. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved Isn't the GitHub PR diff enough? 🤔 8
9. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 9 Kubernetes Manifests vs GitHub PR Diff If you're using plain YAML manifests (e.g., deployment.yaml), the GitHub PR diff reflects the resource changes directly. However, in practice manifests are often generated or transformed, for example: • Kustomize ◦ Applies patches to YAML ◦ The final rendered manifest isn't visible in the PR diff • Helm ◦ Packages and renders manifests ◦ Version upgrades may introduce changes that are not obvious in the PR diff Therefore, PR file diffs alone are not sufficient. You need to compare the fully rendered manifests.
10. AbemaTV, Inc. All Rights Reserved dag-andersen/argocd-diff-preview 10
11. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 11 dag-andersen/argocd-diff-preview dag-andersen/argocd-diff-preview is a tool that allows you to view manifest diffs between branches directly in a PR. The key feature is that it shows diffs after manifests are rendered by Argo CD, not just file diffs. https://github.com/dag-andersen/argocd-diff-preview
12. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 12 How argocd-diff-preview Works argocd-diff-preview runs an ephemeral Kubernetes cluster with Argo CD in CI to render manifests and show the exact diff that would appear after deployment. See How it works for more details.
13. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 13 Execution Model Advantages This execution model provides several benefits: • No impact on existing clusters 👍 • Runs in isolated environments, so parallel executions do not affect performance 👍 • Manifest rendering is offloaded to Argo CD 👍👍 ◦ No need to implement rendering logic ◦ Supports Helm, Kustomize, Jsonnet, CMP, etc. However, since it needs to create a cluster, install Argo CD, and generate the diff, it typically takes around 60 seconds or more.
14. AbemaTV, Inc. All Rights Reserved Performance Optimization 14
15. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved Reusing Clusters 15
16. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 16 Connecting to a Preinstalled Argo CD Cluster The main overhead in argocd-diff-preview comes from cluster creation and Argo CD setup, so reusing an existing cluster with Argo CD already installed can reduce runtime by 60 ~ 90 seconds. https://dag-andersen.github.io/argocd-diff-preview/reusing-clusters/connecting/
17. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved Rendering Methods 17
18. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 18 Rendering Methods argocd-diff-preview supports three methods for rendering manifests with Argo CD. • CLI (Default / Default < v0.2.0) ◦ Uses the argocd app manifests command ◦ This method is simple and flexible but slower when rendering manifests • Server API (Recommended / Default >= v0.2.0) ◦ Fetches manifests directly from the Argo CD API without using the CLI ◦ Good balance between speed and compatibility • Repo Server API (Experimental) ◦ Directly calls the Repo Server gRPC API ◦ This method is the fastest and does not require polling, but it has some limitations and is still experimental.
19. AbemaTV, Inc. All Rights Reserved Other Useful Features 19
20. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 20 Generator Support It supports various Generators available in Argo CD (like ApplicationSets). This is possible precisely because of its model of using an actual Argo CD instance. https://dag-andersen.github.io/argocd-diff-preview/faq/#does-the-tool-work-with-applicationsets
21. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 21 Application Selection Rendering all Applications every time is time-consuming, so you can filter target Applications using annotations (e.g., argocd-diff-preview/watch-pattern). https://dag-andersen.github.io/argocd-diff-preview/application-selection/
22. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 22 Filter Diff Output A convenient feature for when you "want to see the diff, but maybe not the CRD diffs." You can ignore specific resource diffs using API Group, Kind, and Name. https://dag-andersen.github.io/argocd-diff-preview/filter-output/
23. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 23 Markdown Output The tool doesn't natively post comments to PRs, so you need to post the outputted Markdown file using another method. ABEMA uses the suzuki-shunsuke/github-comment. It is very useful as it allows us to hide old comments. https://dag-andersen.github.io/argocd-diff-preview/output/#markdown
24. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 24 HTML Output GitHub PR comments have a 65,536 character limit, so large diffs might not fit. The tool also outputs diffs in HTML format. By uploading this as a GitHub Actions Artifact, you can easily view the full text in your browser without downloading.
25. AbemaTV, Inc. All Rights Reserved AbemaTV, Inc. All Rights Reserved 25 Application Link A feature (PR#336) added to provide a link directly to the target Argo CD Application being changed, similar to PipeCD's Plan Preview. You can use it simply by specifying the host with --argocd-ui-url
26. AbemaTV, Inc. All Rights Reserved