Argo CD and Terraform are used together in modern platform teams because each solves a different part of the delivery problem. Terraform provisions infrastructure using code and manages long lived resources across cloud providers. Argo CD continuously deploys applications by syncing Kubernetes manifests from Git to a cluster and assumes the infrastructure already exists. Understanding where one tool ends and the other begins is the foundation for a stable GitOps workflow.
Core Responsibilities and Separation of Concerns
Terraform is the most popular solution for implementing Infrastructure As Code. The Terraform provider registry contains a very large collection of providers and integrations for all the major cloud providers and at the same time offers a wealth of integration for databases, networking components, Continuous Integration platforms etc.
Argo CD is a GitOps continuous delivery tool that automatically syncs Kubernetes manifests from a Git repository to a cluster, while Terraform is an infrastructure as code tool that provisions cloud resources like VMs, networks, and databases across providers.
The natural starting point is a clean split:
- Everything that is deployed or managed on Kubernetes is controlled by Argo CD
- Everything that is outside the cluster is controlled by Terraform
Each tool is completely oblivious to what the other one is doing. This separation avoids coupling and keeps operational responsibilities clear.
Typical Terraform owned resources are those with no Kubernetes representation:
- Virtual machines
- Storage primitives
- Networking constraints and routes
- DNS records
Argo CD in its vanilla version only handles resources that are described in Kubernetes manifests. If you want to manage a resource that has no Kubernetes representation, then Terraform should handle it.
Common Integration Boundaries
Teams repeatedly ask how the two tools should interact:
- What is the best way to pass variables from Terraform to Helm charts deployed with Terraform?
- How to get secrets in Kubernetes applications that are generated or retrieved from Terraform?
- When should the Terraform Helm and Kubernetes providers come into play if Argo CD already supports Kubernetes deployments on its own?
- For which Kubernetes resources should Terraform be responsible and for which Argo CD?
- What is the proper boundary between the two tools so that operators can use them to the maximum benefit?
A practical boundary is to let Terraform create the underlying infrastructure for the application, then also create the Kubernetes cluster and install Argo CD. Finally, let Argo CD take over for all existing resources that are managed by the cluster, e.g. Deployments and services.
Terraform provisions infrastructure like VMs, networks, databases using code, while Argo CD continuously deploys applications by syncing Kubernetes manifests from Git. Argo CD assumes infrastructure already exists, whereas Terraform creates and manages it across providers like AWS or GCP.
Argo CD cannot replace Terraform because they serve distinct purposes.
Terraform as Git Committer Pattern
A very clean approach is to keep the tools isolated and let Git be the handoff.
Argo CD will continuously sync changes it finds in Git, without concern for how those changes were committed. This means that we can use Terraform to commit files to Git, which will be picked up by Argo CD.
This is a very clean approach as each tool is fully isolated from the other and there is no direct communication between them. Terraform doesn’t know anything about Argo CD and vice versa. All communication happens via Git.
The handoff works like this:
- Terraform runs first. It creates the infrastructure required for your application. It can also install Argo CD into the cluster, but no other Kubernetes resource
- Output variables are put in Kubernetes manifests or Argo CD application sets, or even plain applications. Terraform supports templating files on its own as a built-in capability
- The final result is committed to Git by Terraform like any other manifest
- Argo CD notices Git changes and syncs the files without visibility into how they were created
The pattern can cover many use cases, but not secrets. For example, workload ID information can come from Terraform but must be used in Argo CD.
Note that everything we say about Terraform also applies to OpenTofu.
Managing Argo CD with Terraform
The Terraform ArgoCD provider lets you manage ArgoCD resources - applications, projects, repositories, and clusters - using Terraform's declarative syntax. Instead of clicking through the UI or running argocd CLI commands, you define your ArgoCD configuration as Terraform code, version it in Git, and apply it through your standard Terraform workflow.
This approach is particularly useful when you are already using Terraform to provision your Kubernetes clusters and want to bootstrap ArgoCD configuration as part of the same pipeline.
Installing the provider:
hcl
terraform {
required_version = ">= 1.5.0"
required_providers {
argocd = {
source = "argoproj-labs/argocd"
version = "~> 7.15"
}
kubernetes = {
source = "hashicorp/kubernetes"
version = "~> 2.25"
}
}
}
Configuring Provider Authentication
The ArgoCD provider needs to connect to your ArgoCD server.
With this setup, Argo CD applications, projects, repositories and clusters become Terraform resources that can be versioned alongside the infrastructure that hosts them.
GitOps Bridge Pattern and Limitations
How to Integrate Terraform with Argo CD Without Breaking GitOps is a recurring challenge.
Terraform is the go-to tool for provisioning cloud infrastructure — things like Kubernetes clusters, databases, and identity or access controls, aka cloudy stuff. But integrating those Terraform-managed resources with Argo CD in a way that actually sticks to GitOps principles is where things get tricky.
One of the more common approaches is the GitOps Bridge Pattern. It’s gained traction, even with AWS backing, and it works — but it introduces real-world trade-offs.
Here’s the basic idea: Terraform exports the values your Argo CD Application needs and injects them into a cluster secret as labels or annotations. Argo CD then consumes that metadata using an ApplicationSet with a cluster generator.
Limitations of the GitOps Bridge Pattern:
- Requires ApplicationSets. This pattern only works with ApplicationSets using the cluster generator. That’s fine if you're managing dozens of clusters, but not ideal if you want to use a basic Application or a different generator.
- Breaks GitOps as a Source of Truth. Metadata used by Argo CD comes from cluster secrets — not Git.
The pattern is declarative and can be simple, but it moves configuration out of Git and into the cluster.
State Management and Operational Constraints
Argo CD does not natively handle Terraform state. It is a GitOps controller built for Kubernetes manifests, so managing Terraform state files, locking, or backends falls outside its scope.
To reconcile Terraform through Argo CD, teams typically use an operator like Crossplane or the Argo CD Terraform controller, which stores state in a remote backend such as S3 or Terraform Cloud.
You can integrate Terraform by running it as a pre-sync or post-sync hook in an Argo CD Application. This lets you manage infrastructure changes alongside application deployments. Alternatively, use tools like ArgoCD-Terraform or wrap Terraform in Kubernetes Custom Resources to fit GitOps workflows.
Argo CD limitations that affect complex or large-scale environments:
- Limited support for complex dependency management between applications compared to tools like Helmfile or Terraform
- RBAC and multi-tenancy features are functional but can be complex to configure securely at scale
- Lacks built-in secrets management, often requiring integration with tools like HashiCorp Vault or SOPS
- Resource drift outside Git isn’t automatically reconciled unless auto-sync is enabled, which can cause unexpected state changes
- UI can become slow or cluttered with many applications or deeply nested directories
These constraints reinforce why Terraform remains responsible for infrastructure and state, while Argo CD focuses on declarative delivery of manifests.
Practical Provider Configuration
When using Terraform to commit manifests for Argo CD, the built-in templating capabilities allow output values to be rendered into files before commit.
A minimal workflow separates concerns:
- Terraform creates cloud resources, Kubernetes cluster and Argo CD instance
- Terraform renders application manifests with outputs and commits them to Git
- Argo CD syncs the committed manifests
The provider configuration for managing Argo CD itself is shown above. The Kubernetes provider is often used alongside it when bootstrapping the control plane.
Integration Comparison
| Approach | Direct coupling | Git as source of truth | Typical use case |
| - Terraform commits manifests to Git | No | Yes | Clean handoff of outputs |
| - Argo CD provider manages Argo CD config | Yes via Terraform | Yes | Bootstrapping Argo CD |
| - Pre-sync / post-sync hooks | Yes | Partial | Run Terraform with deploys |
| - GitOps Bridge with cluster secrets | Yes | No | Multi-cluster ApplicationSet |
| Responsibility | Terraform | Argo CD |
| - Cloud VMs, networks, databases | Yes | No |
| - Kubernetes cluster creation | Yes | No |
| - Deployments, Services, ConfigMaps | No | Yes |
| - State files and locking | Yes | No |
| - Continuous sync from Git | No | Yes |
Conclusion
Effective use of Argo CD and Terraform relies on respecting the distinct domains each tool owns. Terraform creates and manages infrastructure across providers like AWS or GCP and handles state in remote backends such as S3 or Terraform Cloud. Argo CD assumes infrastructure already exists and continuously syncs Kubernetes manifests from Git.
The most sustainable patterns keep the tools isolated with Git as the interface. Using Terraform to commit manifests lets Argo CD operate without visibility into how those manifests were created, preserving a clean GitOps model. Managing Argo CD resources with the Terraform ArgoCD provider lets platform teams bootstrap the delivery plane declaratively alongside the cluster it will manage.
Patterns that introduce direct coupling, such as running Terraform as pre-sync hooks or using the GitOps Bridge with cluster secrets, can work but trade away source of truth guarantees and increase operational complexity. The limitations of Argo CD around dependency management, secrets, and state handling further reinforce keeping Terraform responsible for infrastructure outside the cluster.
The recommended evolution remains straightforward: Terraform first creates the underlying infrastructure and installs Argo CD, then Argo CD takes over all resources managed by the cluster. Outputs can flow via templated files committed to Git. For teams needing more integration, the Argo CD Terraform provider and custom resource wrappers provide declarative control without breaking the GitOps contract.