OpenParable
Skip to content
← Back to skills

Tgc Add New Generated Resource Skill

Development
tgc-add-new-generated-resource-skill

Tgc Add New Generated Resource Skill is an Agent Skill for development published in the GoogleCloudPlatform/magic-modules repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Add a new generated resource to TGC. Use when you need to add a new generated resource to TGC.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/GoogleCloudPlatform/magic-modules/blob/HEAD/.agents/archive/tgc/skills/tgc/tgc-add-new-generated-resource-skill/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tgc-add-new-generated-resource-skill, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

tgc-add-new-generated-resource-skill

When you need to add a new generated resource to TGC, use this skill.

When to Use This Skill

  • Use this when adding a new generated resource to TGC.
  • This is helpful when you need to understand the structural steps and configurations needed to expose a generated resource to the Terraform Google Conversion (TGC) library.

How to Use It

If you added or modified a generated resource, follow the steps below carefully.

1. Map and Enable

  • Mapping: Use a script or command to locate mmv1/products/.../Resource.yaml for each google_ type.
    • Search pattern: Look for name: 'resource_name' or perform a filename match.
  • Enabling: For each found YAML file:
    • Ensure include_in_tgc_next: true is present at the top-level.
    • Place it in the proper order according to the progression of fields in the mmv1/api/resource.go file.

2. Check for URL Parameters and Asset Name Format

  • If the resource has parameters marked as url_param_only: true and required: true, verify if they can be extracted from the CAI asset name during cai2hcl conversion.
  • If the self_link in the YAML file is just {{name}} or does not contain all the required parameters in its pattern, you MUST specify cai_asset_name_format at the top-level to define the pattern for extraction.
  • Example: cai_asset_name_format: 'projects/{{project}}/locations/{{location}}/notificationConfigs/{{config_id}}'

3. Check for Custom Flatteners

  • When enabling an existing generated resource for TGC, check if any fields use custom_flatten.
  • If the custom flattener uses d.Get(...) instead of reading from the passed value v (common in shared templates), it will return empty values during cai2hcl conversion because there is no Terraform state.
  • If this causes issues (e.g., dropping required fields), consider adding tgc_ignore_terraform_custom_flatten: true to the field's definition in the YAML to use the default mapping.

4. Skipping Tests Safely for TGC

  • Tests generated from examples and handwritten tests in third_party are shared with the standard Google Provider. DO NOT use exclude_test: true in examples or rename handwritten tests to skip them for TGC, as this will affect the Google Provider as well!
  • To skip a test generated from an example for TGC only: Add tgc_skip_test: 'Reason for skipping' to the example definition in the resource's YAML file.
  • To skip a handwritten test for TGC only: Add the test name to the tgc_tests section at the top-level of the resource's YAML file with skip: 'Reason for skipping'. This prevents the generator from creating duplicates and applies the skip.

5. Handling Missing CAI Data vs Schema Requirements

  • If the CAIS API does not return certain fields, they will be missing in the input CAI asset files for tests.
  • If the resource schema requires at least one of several blocks to be specified, and CAIS returns an empty block (which cai2hcl drops), it may fail validation (Invalid combination of arguments).
  • Solution: Implement a custom tgc_decoder in mmv1/templates/tgc_next/decoders/ to inject minimal valid data or an empty map to satisfy the schema when data is missing in CAI.

Troubleshooting Build Failures

Missing Package Dependency in Shared Templates

  • Symptom: go mod tidy or compilation fails after generation because a package (e.g., compute) is not found in the TGC environment.
  • Cause: Shared templates in mmv1/templates/terraform/constants may contain hardcoded imports or functions relying on packages not available in TGC.
  • Solution: Wrap the problematic code in the template with a compiler condition to exclude it for TGC generation. You can use the helper method IsTgcCompiler:
    {{- if not $.ResourceMetadata.ProductMetadata.IsTgcCompiler }}
    // Code to exclude for TGC (only included for standard Terraform provider)
    {{- end }}
    
    Note: The exact path to IsTgcCompiler may vary depending on the template's context (e.g., $.IsTgcCompiler or $.ProductMetadata.IsTgcCompiler).

No Tests Generated Failure

  • Symptom: Error generating resource tests: No TGC tests for resource <ResourceName>
  • Action: This commonly happens when all examples in the YAML are excluded or there is a file naming mismatch. Please refer to Item 11 in the Troubleshooting Playbook for detailed causes and solutions.