update-tf-provider-for-resource - SKILL.md Agent Skill

name: update-tf-provider-for-resource description: 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.

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:

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).
Locate the Upstream Canonical Files:
- Find the corresponding file in the canonical HashiCorp TPG Beta repository.
- 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:
```
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.
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:

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.
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

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.
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:

Remove ForceNew: true:
- Locate the field in KCC's schema file (e.g., node_config.go) and remove/toggle the ForceNew: true property.

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:

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:

Uncomment TPG Beta in Workspace:

Open go.work in the root of the repository.

Uncomment the TPG Beta provider module line:

// Change this:
//	./third_party/github.com/hashicorp/terraform-provider-google-beta
// To this:
    ./third_party/github.com/hashicorp/terraform-provider-google-beta

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:
```
go vet ./third_party/github.com/hashicorp/terraform-provider-google-beta/google-beta/services/<service>/...
```
Clean Up Workspace changes:
- Revert the go.work modification before staging your commit:
```
git restore go.work
```
Proceed to CRD Generation:
- Once the schema compiles, proceed to .gemini/skills/update-terraform-fields/SKILL.md to regenerate the CRD manifests and Go clients, verifying that your schema modifications translate correctly to KRM.
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:
```
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:
```
git add -A
git commit -m "chore: verify provider changes and ensure clean CI/CD presubmit state"
```