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.yamlfor eachgoogle_type.- Search pattern: Look for
name: 'resource_name'or perform a filename match.
- Search pattern: Look for
- Enabling: For each found YAML file:
- Ensure
include_in_tgc_next: trueis present at the top-level. - Place it in the proper order according to the progression of fields in the
mmv1/api/resource.gofile.
- Ensure
2. Check for URL Parameters and Asset Name Format
- If the resource has parameters marked as
url_param_only: trueandrequired: true, verify if they can be extracted from the CAI asset name duringcai2hclconversion. - If the
self_linkin the YAML file is just{{name}}or does not contain all the required parameters in its pattern, you MUST specifycai_asset_name_formatat 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 valuev(common in shared templates), it will return empty values duringcai2hclconversion because there is no Terraform state. - If this causes issues (e.g., dropping required fields), consider adding
tgc_ignore_terraform_custom_flatten: trueto 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_partyare shared with the standard Google Provider. DO NOT useexclude_test: truein 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_testssection at the top-level of the resource's YAML file withskip: '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
cai2hcldrops), it may fail validation (Invalid combination of arguments). - Solution: Implement a custom
tgc_decoderinmmv1/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 tidyor compilation fails after generation because a package (e.g.,compute) is not found in the TGC environment. - Cause: Shared templates in
mmv1/templates/terraform/constantsmay 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:
Note: The exact path to{{- if not $.ResourceMetadata.ProductMetadata.IsTgcCompiler }} // Code to exclude for TGC (only included for standard Terraform provider) {{- end }}IsTgcCompilermay vary depending on the template's context (e.g.,$.IsTgcCompileror$.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.