The terraform-provider-kubectl maintained by gavinbunney exists as a Terraform provider that enables management of Kubernetes resources using raw YAML manifests within Terraform's declarative infrastructure-as-code workflow. The 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. This capability positions the provider as a practical integration point for teams that want to keep Kubernetes manifests as the source of truth while benefiting from Terraform's plan, apply, and state reconciliation mechanics.
The provider's core value proposition centers on the kubectl_manifest resource, which allows free-form yaml to be processed and applied against Kubernetes. The 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 configuration is handled through the KubeProvider struct and initializeConfiguration function, supporting multiple authentication methods including kubeconfig files, static credentials, and exec plugins. The configuration surface is exposed through environment variables and provider arguments that map directly to Kubernetes API connectivity concerns.
Provider Identity and Purpose
The provider is described as the best way of managing Kubernetes resources in Terraform, by allowing you 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.
The provider is positioned to bridge Terraform and Kubernetes. The terraform-provider-kubectl is a 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.
For teams operating large Kubernetes installations, the provider provides a path to completely manage the lifecycle of Kubernetes resources without abandoning Terraform's state model. The impact is that manifest authors can continue to author Kubernetes native yaml while Terraform assumes responsibility for ordering, dependency management, and drift detection.
The overview covers the provider's architecture, core components, and development infrastructure. For detailed configuration options, see Provider Configuration. For comprehensive documentation of the primary resource, see kubectl_manifest Resource.
Installation and Version Constraints
Terraform 0.13+ is required for use. The provider can be installed and managed automatically by Terraform. Sample versions.tf file configuration is provided to pin the provider source and minimum version.
hcl
terraform {
required_version = ">= 0.13"
required_providers {
kubectl = {
source = "gavinbunney/kubectl"
version = ">= 1.7.0"
}
}
}
The required_version constraint of >= 0.13 aligns with Terraform's provider source and plugin protocol introduced in that major release. The source string gavinbunney/kubectl identifies the namespace and provider name on the Terraform Registry. The version constraint >= 1.7.0 establishes a minimum acceptable provider version for the configuration.
If you don't 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. See User Guide for details on installation and all the provided data and resource types.
The installation path decision affects team workflow. Placing the binary at the root of the Terraform folder enables project-local plugin isolation. Placing it in the Terraform plugin folder on the system enables system-wide reuse across multiple workspaces. The impact is reduced download time for subsequent projects and consistent versioning across the organization.
Manual Binary Acquisition and One-Liner Script
The following one-liner script will fetch the latest provider version and download it to your ~/.terraform.d/plugins directory.
bash
mkdir -p ~/.terraform.d/plugins && \
curl -Ls https://api.github.com/repos/gavinbunney/terraform-provider-kubectl/releases/latest \
| jq -r ".assets[] | select(.browser_download_url | contains(\"$(uname -s | tr A-Z a-z)\")) | select(.browser_download_url | contains(\"amd64\")) | .browser_download_url" \
| xargs -n 1 curl -Lo ~/.terraform.d/plugins/terraform-provider-kubectl.zip && \
pushd ~/.terraform.d/plugins/ && \
unzip ~/.terraform.d/plugins/terraform-provider-kubectl.zip -d terraform-provider-kubectl-tmp && \
mv terraform-provider-kubectl-tmp/terraform-provider-kubectl*
The script creates the plugin directory, queries the GitHub releases API for the latest release, filters assets for the current operating system and amd64 architecture, downloads the zip, extracts it, and moves the binary into place. The use of $(uname -s | tr A-Z a-z) ensures the OS name matches the asset naming convention used in releases.
The impact for operators is automated acquisition without manual browser interaction. The contextual layer connects to the versions.tf constraint, because the downloaded binary must satisfy the >= 1.7.0 minimum. The script assumes jq is present and network access to GitHub API and release assets is allowed.
Building From Source with Go and Make
Development and custom builds are supported via Go. If you wish to work on the provider, you'll first need Go installed on your machine (version 1.12+ is required). You'll 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 process steps are documented as:
bash
go get github.com/gavinbunney/terraform-provider-kubectl
Enter the provider directory and build the provider
cd $GOPATH/src/github.com/gavinbunney/terraform-provider-kubectl
make build
This will build the provider and put the provider binary in the $GOPATH/bin directory.
Building The Provider documentation repeats the steps:
bash
go get github.com/gavinbunney/terraform-provider-kubectl
Enter the provider directory and build the provider
cd $GOPATH/src/github.com/gavinbunney/terraform-provider-kubectl
make build
The build output binary can then be placed in a Terraform plugin directory for use. The requirement for Go version 1.12+ reflects the provider's Go module dependencies and the Terraform Plugin SDK requirements.
Testing Infrastructure and k3s Integration
Testing is exposed through make targets. In order to test the provider, you can simply run make test.
bash
make test
The provider uses k3s to run integration tests. These tests look for any *.tf files in the test/e2e folder and run an plan, apply, refresh and plan loop over each file.
Inside each file the string name-here is replaced with a unique name during test execution. This is a simple string replace before the TF is applied to ensure that tests don't fail due to naming clashes.
Each scenario can be placed in a folder, to help others navigate and use the examples, and added to the README.MD.
Note: The test infrastructure doesn't support multi-file TF configurations so ensure your test scenario is in a single file.
The use of k3s provides a lightweight, single-binary Kubernetes distribution for CI and local development. The impact is that integration tests can run without a full control plane, reducing resource consumption and test flakiness. The name-here replacement prevents collisions when tests run in parallel or sequentially within the same cluster.
In order to run the full suite of Acceptance tests, run make testacc.
bash
make testacc
Note: Acceptance tests create real resources, and often cost money to run.
Acceptance tests validate real resource creation against a live Kubernetes API. The cost warning reflects potential cloud resource charges when tests target managed Kubernetes services rather than local k3s.
Release History and Changelog Details
Releases: gavinbunney/terraform-provider-kubectl
Release list includes v1.19.0 and v1.18.0 and v1.17.0.
v1.19.0
Changelog entries include:
- 0ad0c82 Add new resource 'kubectlkustomizedocuments' (#113) by @matyat
- c9dc419 Expand kustomize test coverage and update for later kustomize format (#328)
- c0eb6c2 Fix kustomize api change & fix dep updates (#327)
- 08f3ba7 Add test for replanning manifests which are always changing (#322)
Internal Changes
- cb35f13 Bump google.golang.org/grpc from 1.68.0 to 1.68.1 in the gomod-deps group (#326)
- 36642c4 Bump actions/upload-artifact from 3 to 4 in the actions-deps group (#324)
- 4ad6d77 Bump github.com/zclconf/go-cty from 1.15.0 to 1.15.1 in the gomod-deps group (#325)
- 1126047 Use groups for dependabot instead of pr limits (#323)
The addition of kubectlkustomizedocuments expands the provider's ability to process Kustomize bundles declaratively. The expansion of kustomize test coverage and updates for later kustomize format indicate compatibility work with evolving Kubernetes manifest tooling. The fix for kustomize api change and dependency updates maintains stability across Kustomize versions.
The internal changes show active dependency hygiene. Bumping google.golang.org/grpc from 1.68.0 to 1.68.1 in the gomod-deps group addresses transport layer patches. The bump of actions/upload-artifact from 3 to 4 in the actions-deps group reflects CI workflow modernization. The bump of github.com/zclconf/go-cty from 1.15.0 to 1.15.1 in the gomod-deps group updates the Terraform configuration type system dependency. Using groups for dependabot instead of pr limits changes automated dependency PR management strategy.
v1.17.0
Changelog entries include:
- 1ce5762 Fix issues with k8s exec plugin for authentication (#319)
- b36092b Add tests for workloads & fix ignoring metadata.managedFields (#321)
- 4449e71 Expand testing of k8s versions (#320)
Internal Changes
- 7feb2c9 Support arm64/amd64 for k3s
- da65ff2 Rename e2e test runner
- 506e6b2 Add workflow to cache k3s/registry images in ghcr (#312)
- e04cae8 Bump goreleaser/goreleaser-action from 3 to 6 (#304)
- 4a948cc Bump crazy-max/ghaction-import-gpg from 5 to 6 (#306)
- ed9d3af Bump github.com/stretchr/testify from 1.7.0 to 1.10.0 (#310)
- e1a913e Exclude dependabot from docker workflows
- 22f2c36 Exclude dependabot from docker workflows
- 806e594 Bump actions/setup-go from 3 to 5 (#302)
- d8f2429 Bump actions/checkout from 3
The fix for k8s exec plugin for authentication resolves credential helper scenarios commonly used in corporate environments. Adding tests for workloads and fixing ignoring metadata.managedFields improves state accuracy by avoiding spurious diffs from Kubernetes managed fields. Expanding testing of k8s versions broadens compatibility validation.
Supporting arm64/amd64 for k3s enables the test infrastructure to run on Apple Silicon and x86_64 hardware. Renaming the e2e test runner improves clarity. Adding workflow to cache k3s/registry images in ghcr reduces CI startup time. Bumps to goreleaser/goreleaser-action, ghaction-import-gpg, testify, actions/setup-go, and actions/checkout reflect continuous integration maintenance.
Provider Configuration Options and Authentication
The provider configuration is handled through the KubeProvider struct and initializeConfiguration() function, supporting multiple authentication methods including kubeconfig files, static credentials, and exec plugins.
| Configuration Option | Environment Variable | Description |
|---|---|---|
| host | KUBE_HOST | Kubernetes API server URL |
| config_path | KUBECONFIG, KUBECONFIGPATH | Path to kubeconfig file |
| token | KUBE_TOKEN | Service account token |
| applyretrycount | KUBECTLPROVIDERAPPLYRETRYCOUNT | Number of retry attempts |
| loadconfigfile | KUBELOADCONFIG_FILE | Enable kubeconfig loading |
The host option maps to KUBEHOST and defines the Kubernetes API server URL. The configpath option maps to KUBECONFIG and KUBECONFIGPATH and specifies the path to kubeconfig file. The token option maps to KUBETOKEN and provides a service account token for authentication. The applyretrycount option maps to KUBECTLPROVIDERAPPLYRETRYCOUNT and controls number of retry attempts for apply operations. The loadconfigfile option maps to KUBELOADCONFIGFILE and enables kubeconfig loading.
The environment variable mapping allows operators to avoid hardcoding sensitive values in Terraform configuration. The impact is improved secret management and portability across environments.
Sources: kubernetes/provider.go176-187
The provider configuration is handled through the KubeProvider struct and initializeConfiguration() function, supporting multiple authentication methods including kubeconfig files, static credentials, and exec plugins.
Core Resource kubectl_manifest
The kubectl_manifest resource is the core component that handles YAML manifest application, serving as the primary interface between Terraform and Kubernetes resources.
Sources: kubernetes/provider.go184-186
The resource accepts free-form yaml and tracks it through Terraform state. Creation, updates and deletion are handled seamlessly including drift detection. The impact for users is that manual kubectl apply changes are detected and reconciled during Terraform plan.
The provider includes several data sources for processing YAML files and generating Kubernetes manifests:
Sources: kubernetes/provider.go176-181
For information about YAML processing capabilities, see Data Sources.
The data sources enable processing directories of yaml files and inline templating. This allows Terraform configurations to reference manifest collections without embedding them inline.
Data Sources and YAML Processing
The project uses a comprehensive testing infrastructure with k3s clusters for acceptance testing:
The provider relies on several key 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 |
The Terraform Plugin SDK v2 at v2.35.0 provides the framework for provider schema definition, resource CRUD operations, and state management. The k8s.io/client-go at v0.32.1 provides the Kubernetes Go client used for API communication. The k8s.io/kubectl at v0.32.1 provides kubectl-specific utilities for manifest handling.
The provider includes several data sources for processing YAML files and generating Kubernetes manifests:
Sources: kubernetes/provider.go176-181
The data sources complement the kubectl_manifest resource by enabling dynamic manifest generation and processing of directories.
Development Guide Summary
If you wish to work on the provider, you'll first need Go installed on your machine (version 1.12+ is required). You'll also need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH.
To compile the provider, run make build.
In order to test the provider, you can simply run make test.
bash
make test
The provider uses k3s to run integration tests. These tests look for any *.tf files in the test/e2e folder and run an plan, apply, refresh and plan loop over each file.
Inside each file the string name-here is replaced with a unique name during test execution. This is a simple string replace before the TF is applied to ensure that tests don't fail due to naming clashes.
Each scenario can be placed in a folder, to help others navigate and use the examples, and added to the README.MD.
Note: The test infrastructure doesn't support multi-file TF configurations so ensure your test scenario is in a single file.
In order to run the full suite of Acceptance tests, run make testacc.
Note: Acceptance tests create real resources, and often cost money to run.
bash
make testacc
Thanks to the original provider by nabancard and lawrecncegripper on the original base of this provider.
The acknowledgment of nabancard and lawrecncegripper reflects the provider's lineage and community origin.
Conclusion
The terraform-provider-kubectl by gavinbunney occupies a specific niche in the Kubernetes and Terraform ecosystem by allowing raw YAML manifests to participate in Terraform's declarative lifecycle. The provider's core kubectl_manifest resource provides state tracking and drift detection for Kubernetes resources defined as yaml, while data sources support processing of manifest directories and templating.
Installation paths include automatic Terraform managed installation via versions.tf with source gavinbunney/kubectl and version >= 1.7.0, manual binary download from the releases page, and a documented one-liner script that queries the GitHub API for the latest release asset matching the host OS and amd64 architecture and installs it into ~/.terraform.d/plugins. Building from source requires Go 1.12+ and GOPATH setup, with make build producing a binary in $GOPATH/bin.
Testing is built around k3s for integration tests, with make test executing plan-apply-refresh-plan loops over *.tf files in test/e2e, using name-here string replacement to avoid naming clashes, and with make testacc running acceptance tests that create real resources and may incur cost. The test infrastructure does not support multi-file TF configurations.
Release history shows active maintenance with v1.19.0 introducing kubectlkustomizedocuments and kustomize test coverage expansions, fixing kustomize api changes, and adding replanning tests, alongside dependency bumps for grpc, go-cty, and GitHub Actions workflows. v1.17.0 fixed k8s exec plugin authentication issues, added workload tests and metadata.managedFields handling, expanded k8s version testing, added arm64/amd64 support for k3s, and updated CI dependencies.
Configuration is handled via KubeProvider struct and initializeConfiguration with options for host, configpath, token, applyretrycount, and loadconfigfile mapped to environment variables KUBEHOST, KUBECONFIG, KUBETOKEN, KUBECTLPROVIDERAPPLYRETRYCOUNT, and KUBELOADCONFIGFILE. Authentication methods include kubeconfig files, static credentials, and exec plugins.
The provider depends on github.com/hashicorp/terraform-plugin-sdk/v2 v2.35.0, k8s.io/client-go v0.32.1, and k8s.io/kubectl v0.32.1. The overall architecture enables large Kubernetes installations to manage the lifecycle of Kubernetes resources through Terraform while preserving yaml as the native resource definition format.