terraform-provider-kubernetes: managing cluster resources with Terraform

Full lifecycle management of cluster resources

The Kubernetes provider for Terraform is a plugin that enables full lifecycle management of Kubernetes resources, and it is maintained internally by HashiCorp. The primary language is Go, and the licence is MPL-2.0, a file-level copyleft licence.

The plugin model is the point of the design. Terraform itself does not know what a Kubernetes manifest is; the provider does the translation, and it is a separate binary that Terraform launches and talks to over a plugin protocol. That is why the repository contains a main.go entry point and a kubernetes/ directory of resource implementations, and why the dependencies include the Terraform plugin framework, the plugin SDK and the plugin mux.

For a user, the practical shape is familiar. You declare resources in HCL, Terraform plans the change, and apply it. The getting started guide, an interactive tutorial, and the registry documentation are all linked from the README, and there is an examples directory in the repository with data sources, functions and resources, plus a numbered set of example Terraform files, and a separate _examples/ directory in the tree.

The provider is also versioned separately from Terraform itself, and the requirements are stated: Terraform 1.x.x, and Go 1.26 or later to build the provider plugin from source. The homepage is the registry documentation page, which is where the resource reference lives, and there is an upgrade guide for the 2.0 release for anyone coming from an older major version.

Two plugin SDKs, served by one mux

The dependency list is the most informative document in this repository, because it records a migration rather than a design.

The module requires go 1.26.3, and among the direct dependencies are terraform-plugin-framework v1.16.1, terraform-plugin-sdk/v2 v2.38.2 and terraform-plugin-mux v0.20.0, alongside terraform-plugin-framework-validators and terraform-plugin-framework-timeouts, terraform-plugin-go, terraform-plugin-log, terraform-plugin-testing and terraform-plugin-docs.

A provider that depends on both the framework and the SDK v2 at the same time is a provider in the middle of moving from one to the other. The framework is the newer plugin interface, and the SDK v2 is the older one that most existing providers were written against. The mux exists to solve exactly that: it lets a provider serve resources implemented under either interface through a single plugin endpoint, so that a resource can be rewritten on the framework without forcing a provider major version on every user.

The supporting dependencies confirm it. terraform-plugin-framework-validators and terraform-plugin-framework-timeouts are the framework's own extension points, terraform-plugin-testing v1.13.3 is the acceptance test harness, and terraform-plugin-docs v0.16.0 generates the registry documentation from the code and the doc comments. The last one explains the presence of the docs/ and templates/ directories in the repository.

The rest of the Terraform-side plumbing is the usual set: hcl/v2 for configuration parsing, go-plugin for the plugin protocol itself, go-cty for the value types that cross the protocol boundary, terraform-json for state, terraform-exec for running Terraform in tests, go-hclog for logging, and hc-install and go-version for installing and comparing Terraform versions.

The Kubernetes side of the dependency tree

The second half of the dependency list is the Kubernetes client stack, and it is pinned to a specific minor release.

The provider depends on k8s.io/api, k8s.io/apimachinery, k8s.io/client-go and k8s.io/kubectl at v0.33.4, on k8s.io/kubernetes at v1.33.6, and on k8s.io/apiextensions-apiserver and k8s.io/kube-aggregator at v0.33.4. It also pulls in sigs.k8s.io/yaml for YAML handling and github.com/getkin/kin-openapi for OpenAPI parsing, which is what lets the provider understand the schema of a custom resource.

The presence of apiextensions-apiserver and kube-aggregator is the interesting part. Those are the API surfaces for custom resource definitions and for aggregated API servers, so the provider can work with resources that are not part of the core Kubernetes API, which is what makes it usable against operators and controllers rather than only against the built-in kinds.

Pulling in k8s.io/kubernetes itself rather than only the client libraries is unusual, and it is the sort of dependency that drives the size of the module graph. The go.sum and the go.mod list a long tail of indirect dependencies, including Azure and AWS transitively, which is the usual cost of depending on the Kubernetes ecosystem as a library.

The practical consequence for anyone using this provider is a compatibility boundary. The client libraries are pinned, so the provider tracks a Kubernetes version, and the registry documentation for the current release is the place to check which one. A provider that lags the cluster by a minor version is normally fine, since the API is versioned, but a provider that lags by a major version is a different story.

How the repository is organised and how the docs are built

The tree is the layout of a serious infrastructure plugin, and several directories have a specific job.

The Go code sits in main.go at the root, with internal/ for the provider internals, kubernetes/ for the resource implementations, util/ for helpers, version/ for the version metadata, manifest/ for the provider manifest, and tools/ for the tool dependencies. The examples/ directory holds data-sources/, functions/ and resources/ subdirectories along with eight numbered example Terraform files, and _examples/ is the directory the README links for examples in the repository.

The documentation pipeline is worth noticing. There is a docs/ directory for the registry documentation, a templates/ directory for the templates used to generate it, and the terraform-plugin-docs dependency does the generation. The README links the registry documentation, the examples, and the Kubernetes Provider 2.0 upgrade guide, all of which are produced from content in this repository rather than written by hand elsewhere.

The changelog process has its own documentation. There is a CHANGELOG.md, a CHANGELOG_GUIDE.md explaining how entries are written, and a .changelog/ directory for the fragments. The .copywrite.hcl file is the copywrite headers configuration, so the source files carry the licence header automatically, and RELEASING.md documents the release process. Renovate is configured in renovate.json, and linting is handled by golangci-lint through .golangci.yml, with a markdown linter and a link checker for the documentation.

The contributor-facing material is under _about/, with CONTRIBUTING.md, ISSUES.md describing the issue lifecycle, and FAQ.md with answers to frequently asked questions.

Where to ask, and how to report a security problem

Support for the provider is split between a Kubernetes community channel and the repository's own issue tracker, and the README tells you which to use.

Chat happens in the #terraform-providers channel on the Kubernetes Slack, with a link to sign up on the Kubernetes Slack. That channel is where questions about the provider in the context of a real cluster get asked and answered, and it is the faster route for usage questions than an issue.

For bugs and feature requests, the contributing section points at the contribution guidelines and at the issue tracker, and it notes that once you have filed an issue it will follow the issue lifecycle described in ISSUES.md. The FAQ page is linked as well, and the phrasing is careful: some answers to frequently asked questions are also available.

Security issues have their own channel, and the README is direct about it. The project states that it takes Terraform's security and its users' trust very seriously, and asks that anyone who believes they have found a security issue in the provider disclose it responsibly by contacting [email protected]. That is a private disclosure address rather than a public issue, which is the correct route for a provider that holds cluster credentials.

The upgrade guide for the 2.0 release is linked alongside the usage documentation, which is the one to read if you are moving a configuration written for an older provider major version, since resource schema changes in a provider are what break plans in a running codebase.

Release cadence and the 3.x line

The version history shows a provider that ships steadily and is still moving.

Version 3.2.0 was published on 2026-06-04, 3.2.1 on 2026-07-01 and 3.3.0 on 2026-10-01, and the last push to the repository was on 2026-10-16, two weeks after the newest tag. The repository is not archived, and the default branch is main.

The pattern is worth reading as a signal about the project. A 3.2.0 minor followed by a 3.2.1 patch, then a 3.3.0 feature release, is the healthy cadence of a provider that has a stable plugin interface and adds resources and features on top of it. The two major version boundaries that have already happened, 2.0 and 3.0, are the ones that would have carried breaking schema changes, and the project keeps an upgrade guide for the 2.0 transition.

For a team running this in production, the practical guidance is to read the changelog before upgrading a minor version, because a provider release that adds a resource can also change defaults, and the CHANGELOG_GUIDE.md in the repository is the place where the project explains which entries are intended to be breaking for users and which are internal.

The broader point about Terraform providers in general applies here. The provider tracks the Kubernetes API through its client libraries, and those are pinned to 1.33 in the current release. When the provider moves to the next Kubernetes minor, the compatibility window shifts with it, and a cluster that is several minors ahead of your provider is the configuration most likely to hit a gap.

Editorial conclusion

Adopt the Kubernetes provider for Terraform if you want Kubernetes resources managed with the same plan and apply workflow as the rest of your infrastructure and you accept that the cluster API is a moving target under a declarative tool. Do not adopt it if you need to manage arbitrary resources the provider does not model, since the manifest approach is not a general escape hatch, and read the 2.0 upgrade guide before migrating from an older major version. Before you start, check the provider version against the Kubernetes version you run, since the client libraries are pinned to 1.33, and read the CHANGELOG_GUIDE.md, because the provider's own changelog process explains which entries are breaking changes for users.

Frequently asked questions

Official sources

1. hashicorp/terraform-provider-kubernetes on GitHub
2. License: MPL-2.0
3. Project website
4. README
5. Releases