The terraform-provider-kubectl project exists as a specialized Terraform provider that enables management of Kubernetes resources using raw YAML manifests within Terraform’s declarative infrastructure-as-code workflow. This provider bridges the gap between Terraform’s resource lifecycle management and Kubernetes’ native YAML-based resource definitions, allowing users to apply, update, and delete Kubernetes resources while maintaining Terraform state tracking and drift detection. The provider is presented as the best way of managing Kubernetes resources in Terraform, by allowing users to use the thing Kubernetes loves best - yaml. The core of this provider is the kubectl_manifest resource, allowing free-form yaml to be processed and applied against Kubernetes. This yaml object is then tracked and handles creation, updates and deleted seamlessly - including drift detection. A set of helpful data resources to process directories of yaml files and inline templating is available. This terraform-provider-kubectl provider has been used by many large Kubernetes installations to completely manage the lifecycle of Kubernetes resources. The provider operates as a bridge between Terraform’s resource management lifecycle and Kubernetes’ API server, with YAML processing at its core. The provider’s architecture centers around several key components that handle the complete lifecycle from Terraform configuration to Kubernetes resource management. The provider implements a sophisticated YAML processing system that handles templating, multi-document parsing, and manifest validation before applying resources to Kubernetes. The provider uses dynamic Kubernetes clients to discover API resources and manage the complete lifecycle of resources, including creation, updates, deletion, and rollout monitoring.
Architecture and Core Philosophy
The provider serves as a robust bridge between Terraform’s infrastructure management capabilities and Kubernetes’ declarative resource model, enabling users to leverage YAML-based Kubernetes configurations within Terraform workflows while maintaining state consistency and drift detection. This bridging function is realized by accepting native Kubernetes YAML as input and translating the desired state into Terraform managed resources. The impact for operators is that teams can keep Kubernetes manifests in their existing Git repositories and apply them through Terraform without re-writing them into HCL resource blocks. The contextual layer connects this design choice to the broader ecosystem preference for YAML as the canonical Kubernetes description format, preserving authorship and tooling familiarity while adding Terraform’s planning, state, and dependency graph.
The provider operates as a bridge between Terraform’s resource management lifecycle and Kubernetes’ API server, with YAML processing at its core. The architecture is intentionally thin in abstraction; it does not reinterpret the semantics of a Deployment, Service, or Custom Resource Definition. Instead it preserves the manifest fidelity and delegates interpretation to the Kubernetes API server. This design reduces translation errors and allows immediate adoption of new Kubernetes API versions as they appear in manifests.
The provider’s architecture centers around several key components that handle the complete lifecycle from Terraform configuration to Kubernetes resource management. The components coordinate parsing, templating, validation, apply, read, and delete operations in a single provider process. The real world consequence is that a single Terraform plan can encompass hundreds of heterogeneous Kubernetes objects without requiring per-kind provider resources.
Core Resource kubectl_manifest
The core of this provider is the kubectl_manifest resource, allowing free-form yaml to be processed and applied against Kubernetes. This yaml object is then tracked and handles creation, updates and deleted seamlessly - including drift detection. The resource accepts a single YAML document or a multi-document YAML string as input. Terraform stores the manifest in state and computes drift by comparing the live object in the cluster to the stored manifest representation.
For platform engineers, this means that an existing manifest directory can be adopted into Terraform with minimal transformation. The provider tracks the resource identifier derived from apiVersion, kind, metadata.name and metadata.namespace. When the cluster object diverges from the manifest, Terraform reports drift and offers a corrective plan. The impact is reduced manual kubectl apply cycles and auditable change history inside Terraform state.
The provider implements a sophisticated YAML processing system that handles templating, multi-document parsing, and manifest validation before applying resources to Kubernetes. Templating allows interpolation of Terraform values into manifests. Multi-document parsing enables a single file with multiple --- separated objects to be treated as a cohesive unit. Manifest validation occurs prior to API submission to surface syntax errors early in the Terraform plan phase.
Data Resources and Directory Processing
A set of helpful data resources to process directories of yaml files and inline templating is available. These data resources complement the kubectl_manifest resource by enabling bulk ingestion of manifest collections. Directory processing allows a whole folder of YAML files to be discovered, read, and transformed into Terraform resources without enumerating each file by hand.
The practical consequence is that GitOps style repositories containing dozens of YAML files can be referenced as a single Terraform data source, with changes to any file reflected in the next Terraform run. Inline templating support means that environment-specific values such as namespace, image tags, or replica counts can be injected at Terraform evaluation time while the underlying YAML structure remains unchanged.
Installation and Terraform Integration
The provider can be installed and managed automatically by Terraform. Installation requires Terraform 0.13+. The provider can be installed and managed automatically by Terraform. Sample versions.tf file is referenced in documentation as the mechanism to pin the provider source and version. If you do not want to use the one-liner above, you can download a binary for your system from the release page, then either place it at the root of your Terraform folder or in the Terraform plugin folder on your system.
The impact for users is that no manual plugin compilation is required in normal usage. Terraform’s plugin discovery will fetch the correct binary for the host OS and architecture on first run. For air-gapped environments, the manual binary download path provides an offline installation route.
The provider is the best way of managing Kubernetes resources in Terraform, by allowing you to use the thing Kubernetes loves best - yaml. This positioning reflects a design choice to avoid re-authoring Kubernetes objects in Terraform’s native resource schemas, which exist for the hashicorp/kubernetes provider. The contextual layer is that organizations already invested in YAML-based workflows can retain those artifacts while gaining Terraform’s dependency ordering and state management.
Development Guide and Build System
If you wish to work on the provider, you will first need Go installed on your machine. Version 1.12+ is required. You will also need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH. To compile the provider, run make build.
The build system component is responsible for compilation and distribution. Key files for this component are main.go, go.mod, and Makefile. The Makefile encodes the build targets that produce the provider binary for multiple platforms.
The development workflow means that contributors can clone the repository, run the build command, and produce a local binary that can be placed into a local Terraform plugin directory for testing. The impact is rapid iteration without waiting for official releases.
make build
Go Module Dependencies
The provider relies on a curated set of Go modules for Kubernetes integration and Terraform provider functionality.
| Module | Version | Purpose |
|---|---|---|
| github.com/hashicorp/terraform-plugin-sdk/v2 | v2.35.0 | Terraform provider framework |
| k8s.io/client-go | v0.32.1 | Kubernetes Go client |
| k8s.io/kubectl | v0.32.1 | kubectl functionality |
| k8s.io/cli-runtime | v0.32.1 | Kubernetes CLI runtime |
| sigs.k8s.io/kustomize/api | v0.19.0 | Kustomize integration |
Sources: go.mod7-29
The presence of k8s.io/client-go provides direct API server communication. k8s.io/kubectl and k8s.io/cli-runtime supply the command line apply semantics that the provider emulates. sigs.k8s.io/kustomize/api enables Kustomize style overlay processing inside Terraform. The Terraform provider framework version pins the SDK behavior for schema definitions, plan modifiers, and state management.
The real world consequence is that the provider inherits upstream Kubernetes client behavior, including authentication, RBAC enforcement, and API discovery. Upgrades to these modules are tracked in go.mod and influence which Kubernetes minor versions can be targeted.
Configuration and Retry Logic
The provider implements configurable retry logic through the kubectlApplyRetryCount variable, allowing resilient operations against unstable clusters.
Provider argument details:
- applyretrycount
- provider argument
- KUBECTLPROVIDERAPPLYRETRYCOUNT
Sources: kubernetes/provider.go238-255
This configuration allows operators to increase the number of apply attempts when the cluster is under load or experiencing transient API errors. The environment variable name KUBECTLPROVIDERAPPLYRETRYCOUNT allows the retry count to be set without modifying Terraform configuration files, which is useful in CI pipelines where retry behavior may differ between environments.
The impact is fewer failed Terraform applies due to temporary etcd latency or API server throttling. The contextual layer ties this to the reality of large clusters where apply operations can be retried safely because kubectl apply is idempotent.
Discovery and Dynamic Client Behavior
The provider uses Kubernetes discovery mechanisms to dynamically determine available API resources and their REST mappings. This discovery enables the provider to handle Custom Resource Definitions without prior schema knowledge.
Dynamic discovery means the provider does not require a static catalog of resource types. When a manifest references a CRD, the provider queries the API server discovery endpoint to find the correct API group, version, and resource path. This allows support for any Kubernetes resource, including those introduced after the provider was released.
The provider uses dynamic Kubernetes clients to discover API resources and manage the complete lifecycle of resources, including creation, updates, deletion, and rollout monitoring. Rollout monitoring is particularly relevant for Deployments and other controller objects where the provider can wait for the observed status to converge before reporting success to Terraform.
Component Architecture Overview
The provider includes comprehensive testing, build automation, and quality assurance systems that ensure reliability across multiple Kubernetes and Terraform versions.
| Component | Purpose | Key Files |
|---|---|---|
| Build System | Compilation and distribution | main.go, go.mod, Makefile |
| Testing Framework | Unit and acceptance tests | kubernetes/provider_test.go, _examples/ |
| CI/CD Pipeline | Automated testing and releases | .github/workflows/, scripts/ |
| Code Quality | Linting, formatting, validation | gofmt, go vet, errcheck |
| Version Matrix | Multi-version compatibility testing | K8s versions, Terraform versions |
The testing framework provides unit and acceptance tests that validate manifest application, drift detection, and deletion semantics. The CI/CD pipeline automates testing and releases, ensuring that changes are validated before publication. Code quality tools such as gofmt, go vet, and errcheck maintain consistency across the codebase.
The provider supports the last 7 Kubernetes releases and last 4 stable Terraform versions, with automated testing. This wide version matrix reduces the risk of incompatibility when upgrading either Terraform or the Kubernetes control plane. The practical impact is that enterprises can adopt the provider with confidence that it will continue to function across their upgrade cadence.
YAML Processing Pipeline
The provider implements a sophisticated YAML processing system that handles templating, multi-document parsing, and manifest validation before applying resources to Kubernetes. The pipeline first normalizes input, then applies templating if configured, then splits multi-document YAML into individual manifests, then validates each manifest against Kubernetes structural requirements.
For users, this means that errors are caught early in the Terraform plan phase rather than during apply. The contextual layer is that validation reduces cluster churn and avoids partial applies that could leave resources in an inconsistent state.
Lifecycle Management
The provider is described as allowing free-form yaml to be processed and applied against Kubernetes. This yaml object is then tracked and handles creation, updates and deleted seamlessly - including drift detection. The complete lifecycle support includes creation on first apply, update when the manifest changes, and deletion when the resource is removed from Terraform configuration.
Drift detection is a central capability. Terraform can detect when an object has been modified outside of Terraform, such as by kubectl apply executed manually or by a Kubernetes operator. The provider surfaces this drift in plan output, enabling corrective actions.
The provider includes comprehensive testing, build automation, and quality assurance systems that ensure reliability across multiple Kubernetes and Terraform versions. This reliability focus is reinforced by the version matrix testing across Kubernetes and Terraform versions.
Conclusion
The terraform-provider-kubectl project occupies a distinct niche by refusing to abstract away Kubernetes YAML and instead embracing it as the source of truth inside Terraform workflows. The design choice to center on the kubectl_manifest resource and to support directory processing and templating creates a pragmatic path for teams that already manage clusters with YAML. The architecture’s reliance on official Kubernetes Go clients, kubectl functionality, and CLI runtime ensures behavioral parity with native kubectl apply while adding Terraform’s state tracking, dependency graph, and drift detection. Configurable retry logic and dynamic API discovery make the provider resilient in production clusters that experience transient failures or evolve with new CRDs. The build system, testing framework, CI/CD pipeline, code quality gates, and version matrix collectively support a provider that is used by many large Kubernetes installations to completely manage the lifecycle of Kubernetes resources. The combination of YAML fidelity, Terraform lifecycle control, and broad version compatibility positions the provider as a bridge that respects Kubernetes conventions while delivering infrastructure-as-code governance.