# Update Tf Provider For Resource

> Update Tf Provider For Resource is an Agent Skill for development published in the GoogleCloudPlatform/k8s-config-connector repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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 name: `update-tf-provider-for-resource`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/GoogleCloudPlatform/k8s-config-connector/blob/HEAD/.gemini/skills/update-tf-provider-for-resource/SKILL.md
- Repository: GoogleCloudPlatform/k8s-config-connector (1,053 GitHub stars when collected)

## SKILL.md

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

---

Source: https://www.openparable.com/skill/development/update-tf-provider-for-resource (OpenParable). Cite the canonical URL above.
