|
| 1 | +# Upgrading to v45.0 |
| 2 | + |
| 3 | +The v45.0 release of *terraform-google-kubernetes-engine* contains breaking interface changes in the `workload-identity` submodule. |
| 4 | + |
| 5 | +## Workload Identity Submodule (`modules/workload-identity`) |
| 6 | + |
| 7 | +### 1. Native `kubernetes_annotations` Replacement |
| 8 | + |
| 9 | +The `workload-identity` submodule no longer uses `kubectl-wrapper` (`local-exec` bash script execution) to annotate existing Kubernetes Service Accounts. Instead, it uses the native [`kubernetes_annotations`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/annotations) resource from the `hashicorp/kubernetes` provider. |
| 10 | + |
| 11 | +#### Kubernetes Provider Prerequisite |
| 12 | +Because `kubernetes_annotations` is a native Terraform provider resource, callers **must** have an initialized and authenticated `kubernetes` provider configured in their root module context: |
| 13 | + |
| 14 | +```hcl |
| 15 | +provider "kubernetes" { |
| 16 | + host = "https://${module.gke.endpoint}" |
| 17 | + token = data.google_client_config.default.access_token |
| 18 | + cluster_ca_certificate = base64decode(module.gke.ca_certificate) |
| 19 | +} |
| 20 | +``` |
| 21 | + |
| 22 | +> **Note:** If you previously configured `ignore_annotations` in your `kubernetes` provider block to ignore Workload Identity annotations (e.g., `ignore_annotations = ["^iam.gke.io\\/.*"]`) to prevent conflicts with the legacy `kubectl-wrapper`, you must remove that configuration. Otherwise, the new native `kubernetes_annotations` resource will not function correctly. |
| 23 | +
|
| 24 | +--- |
| 25 | + |
| 26 | +### 2. Removed Input Variables |
| 27 | + |
| 28 | +The following input variables were previously used to configure `gcloud container clusters get-credentials` and `kubectl` inside `kubectl_wrapper.sh`. They have been removed as they are no longer required by the module: |
| 29 | + |
| 30 | +- `cluster_name` |
| 31 | +- `location` |
| 32 | +- `impersonate_service_account` |
| 33 | +- `use_existing_context` |
| 34 | + |
| 35 | +#### Expected Error if Unchanged |
| 36 | +If you attempt to apply module calls containing these deleted inputs, Terraform will return an error during configuration validation: |
| 37 | + |
| 38 | +```text |
| 39 | +Error: Unsupported argument |
| 40 | +
|
| 41 | + on main.tf line 32, in module "workload_identity": |
| 42 | + 32: cluster_name = module.gke.name |
| 43 | +
|
| 44 | +An argument named "cluster_name" is not expected here. |
| 45 | +``` |
| 46 | + |
| 47 | +#### Migration Example |
| 48 | + |
| 49 | +Update your `module "workload_identity"` calls to remove the deleted arguments: |
| 50 | + |
| 51 | +```diff |
| 52 | +module "workload_identity" { |
| 53 | + source = "terraform-google-modules/kubernetes-engine/google//modules/workload-identity" |
| 54 | +- version = "~> 44.0" |
| 55 | ++ version = "~> 45.0" |
| 56 | + |
| 57 | + project_id = var.project_id |
| 58 | + name = "my-app" |
| 59 | +- cluster_name = module.gke.name |
| 60 | +- location = module.gke.location |
| 61 | + namespace = "default" |
| 62 | + use_existing_k8s_sa = true |
| 63 | + k8s_sa_name = "existing-ksa" |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +--- |
| 68 | + |
| 69 | +### 3. State Migration Strategy |
| 70 | + |
| 71 | +For existing deployments where `use_existing_k8s_sa = true` and `annotate_k8s_sa = true`: |
| 72 | + |
| 73 | +1. Terraform will plan to destroy the legacy `module.annotate-sa` resources and create `kubernetes_annotations.main[0]`. |
| 74 | +2. `kubernetes_annotations.main[0]` uses `force = true` and Server-Side Apply to adopt the existing `"iam.gke.io/gcp-service-account"` annotation seamlessly. |
| 75 | +3. **Proactive State Cleanup for CI/CD Runners:** Standard CI/CD runner environments (Terraform Cloud, Spacelift, Atlantis, minimal GitHub Actions runners) typically lack local `gcloud` and `kubectl` binaries. Attempting to run `terraform apply` directly may fail during the destroy phase of `module.annotate-sa`. |
| 76 | + |
| 77 | +To prevent build failures, remove the legacy module state **prior to running `terraform apply`**: |
| 78 | + |
| 79 | +```bash |
| 80 | +# Standard module call |
| 81 | +terraform state rm 'module.workload_identity.module.annotate-sa' |
| 82 | + |
| 83 | +# Module call using count or for_each |
| 84 | +terraform state rm 'module.workload_identity["app"].module.annotate-sa' |
| 85 | +terraform state rm 'module.workload_identity[0].module.annotate-sa' |
| 86 | +``` |
| 87 | + |
| 88 | +*Note: Deployments created with `use_existing_k8s_sa = false` (default) do not use `module.annotate-sa` and require no state migration.* |
0 commit comments