# Update Tf Provider For Resource

> Guides through aligning, backporting, and updating KCC's vendored Terraform Google Beta provider code with the canonical upstream repository while carefully preserving local patches, overrides, and KRM-specific tweaks.

- Skill: `googlecloudplatform/update-tf-provider-for-resource` (Agent Skill)
- Install (CLI): `npx skillmds@latest add googlecloudplatform/update-tf-provider-for-resource`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlecloudplatform/update-tf-provider-for-resource/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: GoogleCloudPlatform (https://skillmd.com/u/googlecloudplatform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/googlecloudplatform/update-tf-provider-for-resource

---


# KCC Update Terraform Provider for Resource (Agentic-Friendly Guide)

This skill provides step-by-step instructions for an automated agent or developer to backport, update, or align KCC's locally vendored Terraform Google Beta Provider (TPG Beta) code with the canonical upstream HashiCorp provider while **strictly preserving** KCC-specific local patches and overrides.

---

## 1. Prerequisites & Discovery

Before modifying any files, identify the targets in both the local repository and the upstream canonical provider:

1. **Locate the Local Files**:
   - Vendored provider files are located under `third_party/github.com/hashicorp/terraform-provider-google-beta/google-beta/services/<service>/`.
   - Identify the specific resource schema or resource definition files (e.g., `resource_container_node_pool.go` or `node_config.go`).
2. **Locate the Upstream Canonical Files**:
   - Find the corresponding file in the [canonical HashiCorp TPG Beta repository](https://github.com/hashicorp/terraform-provider-google-beta/tree/main/google-beta/services/).
   - **Agentic Tip (Small Files)**: Use the `read_url_content` tool with the **raw GitHub URL** to fetch the upstream file content directly:
     - **Format**: `https://raw.githubusercontent.com/hashicorp/terraform-provider-google-beta/main/google-beta/services/<service>/<filename>`
     - **Example**: `https://raw.githubusercontent.com/hashicorp/terraform-provider-google-beta/main/google-beta/services/container/node_config.go`
   - **Agentic Tip (Large Files / Truncation Avoidance)**: If the raw file is large (e.g. over 30KB), `read_url_content` might truncate it. Instead, download the raw file using `curl` to a local workspace scratch folder (e.g., `.gemini/scratch/`) using `run_command`:
     ```bash
     mkdir -p .gemini/scratch
     curl -s -o .gemini/scratch/<filename> https://raw.githubusercontent.com/hashicorp/terraform-provider-google-beta/main/google-beta/services/<service>/<filename>
     ```
     You can then use filesystem tools (`view_file`, `grep_search`) to safely read/search the downloaded copy. Remember to run `rm -rf .gemini/scratch/` once done.
3. **Determine the Target Task**:
   - Are you backporting a newly added field/block?
   - Are you enabling in-place updates for a field that recently became mutable at the GCP API level?

---

## 2. Analyzing & Preserving KCC-Specific Patches (Critical)

KCC's vendored provider contains custom patches specifically implemented to enforce KRM (Kubernetes Resource Model) semantics, handle Kubernetes-specific lifecycle events, and prevent API server sync bugs.

> [!CAUTION]
> **NEVER blindly overwrite a KCC vendored provider file with the upstream canonical version.** Doing so will revert critical KCC-specific changes and break resources at runtime.

### Steps to Discover and Analyze Local Patches:
1. **Review Local Commit History**:
   - Run `git log -p -S "ForceNew" -- <path_to_local_file>` to find why fields were made immutable (e.g. `ForceNew: true`).
   - Run `git log -p -n 10 -- <path_to_local_file>` to review recent local modifications.
   - Search the local file for custom comments containing keywords like `KCC`, `CNRM`, `KRM`, or `Autogen`.
2. **Identify Key Categories of Local Patches**:
   - **Custom `ForceNew: true` Overrides**: KCC explicitly marks fields `ForceNew: true` (even if upstream marks them mutable) if GKE/GCP doesn't allow in-place updates under KRM lifecycle policies, or if KCC needs to statically expose them as `Immutable` in the generated CRD descriptions.
   - **Empty Block Flatteners**: Look for custom overrides in flatteners where empty/nil blocks explicitly return `nil` or empty slices to prevent Terraform calculating false diffs (refer to `update-terraform-fields` skill documentation).
   - **Custom Diff Suppressors**: Check for KCC-specific suppressors designed to ignore GKE/GCP autogenerated out-of-band attributes (e.g., GKE autoscaling or sandbox labels).

---

## 3. Aligning & Backporting Upstream Changes

When updating KCC's vendored code with upstream features:

### Case A: Backporting a New Field
1. **Extract Schema Changes**:
   - Copy the field's schema definition block from the upstream file.
   - **Check Immutability**: Decide if the new field is immutable at the KRM/GCP API level. If it is, explicitly add `ForceNew: true` to its schema definition to trigger correct CRD `Immutable. ` generation.
2. **Extract Expanders & Flatteners**:
   - Copy the corresponding expander (Go KRM/Terraform struct -> GCP SDK struct) and flattener (GCP SDK struct -> Terraform map) code.
   - **Ensure Safe Flattening**: If the new field is an optional block or struct, wrap its flattener to ensure it returns `nil` if empty, avoiding false updates.

### Case B: Upgrading an Immutable Field to Mutable (Enabling In-Place Updates)
If the GKE/GCP API has evolved to support in-place updates for a field that KCC currently treats as immutable:
1. **Remove `ForceNew: true`**:
   - Locate the field in KCC's schema file (e.g., `node_config.go`) and remove/toggle the `ForceNew: true` property.
2. **Implement the Update Handler**:
   - Open the resource update file (e.g., `resource_container_node_pool.go`).
   - Implement a `d.HasChange` block in the resource update function to detect changes to the newly mutable field, serialize the updated state, and send the update payload to the GCP API using GKE/GCP client SDKs:
     ```go
     if d.HasChange(prefix + "node_config.0.my_newly_mutable_field") {
         req := &container.UpdateNodePoolRequest{
             NodePoolId: name,
             MyNewlyMutableField: expandMyField(d.Get(prefix + "node_config.0.my_newly_mutable_field")),
         }
         // Execute the update request via GKE/GCP client SDK...
     }
     ```

---

## 4. Local Compilation & Validation

Every time you update the vendored provider code, you **MUST** verify that it compiles successfully inside the KCC workspace:

1. **Uncomment TPG Beta in Workspace**:
   - Open `go.work` in the root of the repository.
   - Uncomment the TPG Beta provider module line:
     ```go
     // Change this:
     //	./third_party/github.com/hashicorp/terraform-provider-google-beta
     // To this:
     	./third_party/github.com/hashicorp/terraform-provider-google-beta
     ```
2. **Run Compiler Checks**:
   - Run `go vet` from the repository root, scoped to the specific GKE/GCP service package you modified. This ensures all workspace-level dependencies compile correctly:
     ```bash
     go vet ./third_party/github.com/hashicorp/terraform-provider-google-beta/google-beta/services/<service>/...
     ```
3. **Clean Up Workspace changes**:
   - Revert the `go.work` modification before staging your commit:
     ```bash
     git restore go.work
     ```
4. **Proceed to CRD Generation**:
   - Once the schema compiles, proceed to [.gemini/skills/update-terraform-fields/SKILL.md](https://github.com/GoogleCloudPlatform/k8s-config-connector/blob/master/.gemini/skills/update-terraform-fields/SKILL.md) to regenerate the CRD manifests and Go clients, verifying that your schema modifications translate correctly to KRM.
5. **Mandatory CI/CD Presubmit Verification**:
   - Run the resource docs generation and the core CI presubmit validation scripts locally to ensure complete alignment across vendored code, CRDs, documentation, and generated artifacts before submitting a PR:
     ```bash
     make resource-docs
     dev/ci/presubmits/validate-generated-files
     scripts/validate-prereqs.sh
     ```
   - Ensure any modified or regenerated files (including generated docs) are staged and committed cleanly:
     ```bash
     git add -A
     git commit -m "chore: verify provider changes and ensure clean CI/CD presubmit state"
     ```
6. **Additional testing**
   - Refer to .gemini/skills/test-terraform-fields/SKILL.md to set up E2E tests, record golden files, check against MockGCP, and run linters.