The management of containerized workloads has evolved significantly, moving beyond simple provisioning into complex lifecycle orchestration. While the official Kubernetes provider for Terraform handles standard resources like Deployments, Services, and ConfigMaps with precision, the ecosystem’s extensibility presents a persistent challenge. The proliferation of Custom Resource Definitions (CRDs), operator-managed resources, and multi-document manifests creates a gap where the official provider lacks native support. This is where the terraform-provider-kubectl becomes indispensable. This provider offers the most effective method for handling Kubernetes resources in Terraform by allowing engineers to leverage what Kubernetes values most: YAML. By enabling the processing and application of free-form YAML directly to a cluster, it bridges the divide between declarative infrastructure-as-code and the dynamic reality of Kubernetes-native configuration.

At the heart of this provider lies the kubectl_manifest resource. This entity enables the processing and application of free-form YAML manifests to Kubernetes clusters. Unlike standard Terraform resources that map specific arguments to specific API fields, kubectl_manifest treats the YAML body as the primary interface. This YAML object is monitored across its full lifecycle, handling creation, updates, drift detection, and deletion seamlessly. The provider has gained widespread adoption in numerous large Kubernetes installations, serving as the primary tool for orchestrating the complete lifecycle of Kubernetes resources. By allowing the use of raw YAML, it preserves the natural structure of Kubernetes definitions, reducing the cognitive load of translating complex multi-document files into Terraform blocks.

Core Architecture and Resource Inventory

The terraform-provider-kubectl is not a monolithic resource but a suite of tools designed to interact with the Kubernetes API server in various ways. It provides a structured set of resources and data sources that cover the full spectrum of cluster management needs. The following table details the core components available within the provider, highlighting their specific purposes and operational roles.

The primary resource, kubectl_manifest, is the engine that drives this provider. It accepts a yaml_body attribute, which contains the raw Kubernetes manifest. When Terraform applies this resource, the provider parses the YAML content into a structured manifest, compares it against the current state in the cluster, and applies the necessary changes. This process ensures that the desired state defined in the Terraform configuration matches the actual state in the cluster.

A critical feature of the modern provider implementation, particularly in versions supporting Terraform 1.10 and later, is the introduction of ephemeral resources. For sensitive data, the provider exposes an ephemeral kubectl_manifest resource. This capability allows users to fetch Secret payloads, freshly-minted tokens, or any other sensitive data without ever writing the value to terraform.tfstate. This is a significant security improvement, as standard Terraform state files often persist in version control or remote backends, posing a risk if sensitive credentials are inadvertently committed. The ephemeral resource ensures that these values exist only in memory during the Terraform run and are discarded immediately afterward.

Basic Usage and Workflow Mechanics

Understanding how the provider processes a kubectl_manifest resource requires looking at the interaction between the user configuration and the provider's internal code entities. The workflow begins with the definition of the resource in HCL. The yaml_body attribute is the central input. Once applied, the provider parses this content. The diagram of this process shows how the yaml_body content is parsed into a structured manifest object.

The mapping from user configuration to code entities is straightforward yet powerful. The kubectlManifestSchema variable within the provider defines the acceptable structure. When a Manifest object is processed, it interacts with objects to perform the actual API calls. After applying a configuration, Terraform state includes computed attributes that reflect the current status of the resource. These attributes are crucial for understanding the resource's identity within the cluster.

The following table illustrates the computed attributes typically found in the Terraform state after applying a basic ConfigMap resource.

A minimal example of creating a Kubernetes ConfigMap using this provider demonstrates the essential components. The configuration relies on the kubectl_manifest resource type and the yaml_body attribute. This simplicity is the provider's greatest strength. Engineers can copy-paste existing kubectl apply -f manifests directly into Terraform files with minimal modification.

hcl resource "kubectl_manifest" "my_config" { yaml_body = <<YAML apiVersion: v1 kind: ConfigMap metadata: name: my-config namespace: default data: key1: value1 key2: value2 YAML }

This pattern is the fundamental usage of the provider. It defines a Kubernetes resource using raw YAML within a Terraform configuration and applies it to the cluster. The provider then tracks this resource, ensuring that any manual changes made outside of Terraform are detected as drift and corrected upon the next terraform apply run.

Provider Installation and Configuration

Integrating the provider into an existing Terraform environment requires careful attention to versioning and provider sources. The provider has historically been published under different source addresses, primarily gavinbunney/kubectl and later alekc/kubectl. Managing this transition is critical for teams migrating their infrastructure.

The provider can be installed and managed automatically by Terraform. For new projects, the standard approach is to declare the provider requirement in the terraform block.

hcl terraform { required_providers { kubectl = { source = "alekc/kubectl" } } }

The provider uses the same kubeconfig as the official Kubernetes provider. This means that if a team already uses the hashicorp/kubernetes provider, the kubectl provider can be configured to point at the same cluster context. This consistency simplifies environment management.

hcl provider "kubectl" { config_path = "~/.kube/config" config_context = "my-cluster" }

However, teams that have used the gavinbunney/kubectl source in the past must address the migration to alekc/kubectl to continue receiving updates and fixes. Terraform 1.5 and later support moved blocks, which allow for the safe migration of state without destroying and recreating resources.

Migrating Between Provider Sources

For organizations transitioning from gavinbunney/kubectl to alekc/kubectl, the migration process involves specific Terraform state operations. The goal is to change the provider source in the configuration and update the state address to reflect the new provider, ensuring that the underlying Kubernetes resources remain intact.

1. Pick a transitional address (any unused name; _v3 works).
2. Update the Terraform configuration to use the new source.
3. Add a moved block to handle the state migration.

```hcl
terraform {
required_providers {
kubectl = {
source = "alekc/kubectl"
}
}
}

moved {
from = kubectlmanifest.myapp # was gavinbunney/kubectl
to = kubectlmanifest.myapp_v3 # now alekc/kubectl
}

resource "kubectlmanifest" "myappv3" {
# ... same yamlbody / attributes as before
}
```

After configuring the moved block and updating the resource name to the transitional address, the next steps involve initializing and planning.

bash terraform init -upgrade terraform plan

The plan reports the resource as moved with no in-place changes. The output typically looks like this:

```text

kubectlmanifest.myapp has moved to kubectlmanifest.myapp_v3

resource "kubectlmanifest" "myapp_v3" {
# (N unchanged attributes hidden)
}
Plan: 0 to add, 0 to change, 0 to destroy.
```

Running terraform apply commits the move. This operation is a no-op for the resource itself; only the state address changes. After the move applies, the resource can be renamed back to the original name if desired. This involves dropping the _v3 suffix from the resource block, adding a second moved block pointing my_app_v3 to my_app, and applying again. Once the addresses match, the moved blocks can be removed entirely.

It is important to note a specific behavior during this process. terraform plan -detailed-exitcode returns 2 on the first plan because moved annotations count as "changes present," even when the resource summary shows 0 to add, 0 to change, and 0 to destroy. The second plan, after the apply, returns 0 cleanly. Teams relying on exit codes in CI/CD pipelines should treat the plan summary line as authoritative rather than the exit code during the migration phase. The 20 attributes shared with the gavinbunney implementation carry over unchanged, ensuring compatibility.

Advanced Patterns: CRDs, Templating, and Server-Side Apply

The true power of the kubectl_manifest resource emerges when managing resources that the official provider cannot handle. The official Kubernetes provider covers most standard resources, but the ecosystem is full of CRDs and operator-managed resources. The kubectl provider lets users apply arbitrary YAML manifests, similar to running kubectl apply -f. It handles CRDs, custom resources, multi-document YAML files, and anything else expressible in a Kubernetes manifest.

Managing Custom Resource Definitions and Operators

Consider a scenario involving OpenFaaS, a serverless platform for Kubernetes. Managing an OpenFaaS function requires interacting with CRDs that the official provider may not fully support or may handle poorly. The kubectl_manifest resource allows engineers to define the OpenFaaS function using its native YAML specification.

To set this up, kubectl must be configured to point to the target cluster. For a local development environment using kind, this can be done as follows:

bash $ kind export kubeconfig --name=openfaas Set kubectl context to "kind-openfaas" $ kubectl config view --context=kind-openfaas --raw --output="go-template-file=../../cluster.tfvars.gotemplate" > terraform.tfvars

Initializing the configuration installs the provider and sets up Terraform. The output confirms the installation of the provider versions, such as hashicorp/kubernetes and the kubectl provider.

Dynamic YAML with Templatefile

Kubernetes manifests are often dynamic, requiring values to be injected based on environment variables or Terraform inputs. The kubectl provider supports this by allowing the yaml_body to be a string resulting from Terraform's templatefile function. This enables the creation of complex, parameterized manifests.

hcl resource "kubectl_manifest" "ingress_route" { yaml_body = templatefile("${path.module}/manifests/ingress-route.yaml.tpl", { name = var.app_name namespace = var.namespace domain = var.domain service = var.service_name port = var.service_port }) }

The corresponding template file (manifests/ingress-route.yaml.tpl) uses Go template syntax to insert variables:

yaml apiVersion: traefik.io/v1alpha1 kind: IngressRoute metadata: name: ${name} namespace: ${namespace} spec: entryPoints: - websecure routes: - match: Host(`${domain}`) kind: Rule services: - name: ${service} port: ${port} tls: certResolver: letsencrypt

This pattern is highly effective for managing networking resources like Traefik IngressRoutes or Istio VirtualServices. For example, an Istio VirtualService can be defined using the same method, ensuring that the routing rules are managed as code.

hcl resource "kubectl_manifest" "virtual_service" { yaml_body = <<YAML apiVersion: networking.istio.io/v1beta1 kind: VirtualService metadata: name: my-app namespace: production spec: hosts: - app.example.com gateways: - istio-system/main-gateway http: - match: - uri: prefix: /api route: - destination: host: api-service port: number: 8080 - route: - destination: host: frontend-service port: number: 80 YAML }

Server-Side Apply

Conflicts with other controllers are a common challenge in Kubernetes. When multiple systems attempt to manage the same resource, client-side apply (the default kubectl apply behavior) can lead to merge conflicts or lost updates. The kubectl provider supports server-side apply, which is better at handling conflicts with other controllers.

Server-side apply uses a three-way merge strategy on the API server, comparing the live object, the last applied configuration, and the new configuration. This approach reduces the likelihood of conflicts and provides a more reliable way to manage resources in shared clusters.

hcl resource "kubectl_manifest" "deployment" { yaml_body = <<YAML apiVersion: apps/v1 kind: Deployment metadata: name: my-app namespace: production spec: replicas: 3 YAML # Enable server-side apply if supported by provider version # specific attributes may vary by version, check documentation }

Conclusion

The terraform-provider-kubectl stands as a critical component in the modern DevOps toolchain, specifically for teams managing complex Kubernetes environments. By leveraging the kubectl_manifest resource, engineers can bypass the limitations of structured Terraform resources and directly apply the YAML manifests that Kubernetes was designed to consume. This approach offers several distinct advantages:

1. Native Compatibility: It supports CRDs, operators, and multi-document files that the official provider does not natively handle.
2. Lifecycle Management: It provides seamless creation, updating, deletion, and drift detection for resources managed via raw YAML.
3. Security Features: The inclusion of ephemeral resources for sensitive data like Secrets and tokens addresses a major security gap in traditional state management.
4. Flexibility: The integration with Terraform's templating engine allows for dynamic and parameterized manifest generation, supporting infrastructure-as-code best practices.

The provider's evolution, including the transition from gavinbunney to alekc sources, highlights the active community development and the importance of proper state migration strategies. Teams must remain vigilant regarding provider source changes and utilize Terraform's moved blocks to ensure smooth transitions without service disruption. As Kubernetes continues to evolve, the ability to manage resources through raw YAML in a version-controlled, auditable, and idempotent manner will remain a cornerstone of scalable infrastructure management. The kubectl_manifest resource ensures that Terraform remains relevant and powerful in the face of Kubernetes' extensibility, providing a bridge between the rigidity of code and the flexibility of container orchestration.

Sources

1. github.com/gavinbunney/terraform-provider-kubectl
2. github.com/alekc/terraform-provider-kubectl
3. deepwiki.com/gavinbunney/terraform-provider-kubectl
4. developer.hashicorp.com/terraform/tutorials/kubernetes
5. oneuptime.com