Overview on Magic Modules

Add documentation

Mon, 01 Jan 0001 00:00:00 +0000

Add documentation#

Documentation is autogenerated based on the resource and [field(https://googlecloudplatform.github.io/magic-modules/develop/add-fields/] configurations. This page describes how to add documentation to resources and fields.

For more information about types of resources and the generation process overall, see How Magic Modules works.

Before you begin#

Complete the steps in Set up your development environment to set up your environment and your Google Cloud project.

Ensure that your magic-modules, terraform-provider-google, and terraform-provider-google-beta repositories are up to date.

cd ~/magic-modules
git checkout main && git clean -f . && git checkout -- . && git pull
cd $GOPATH/src/github.com/hashicorp/terraform-provider-google
git checkout main && git clean -f . && git checkout -- . && git pull
cd $GOPATH/src/github.com/hashicorp/terraform-provider-google-beta
git checkout main && git clean -f . && git checkout -- . && git pull

Add documentation#

MMv1

To preview the documentation:

Add resource tests

Mon, 01 Jan 0001 00:00:00 +0000

Add resource tests#

This page describes how to add tests to a new resource in the google or google-beta Terraform provider.

The providers have two basic types of tests:

Unit tests: test specific functions thoroughly. Unit tests do not interact with GCP APIs.
Acceptance tests (aka VCR tests, or create and update tests): test that resources interact as expected with the APIs. Acceptance tests interact with GCP APIs, but should only test the provider’s behavior in constructing the API requests and parsing the responses.

Acceptance tests are also called “VCR tests” because they use go-vcr to record and play back HTTP requests. This allows tests to run more quickly on PRs because the resources don’t actually need to be created, updated, or destroyed by the live API.

Create a pull request

Mon, 01 Jan 0001 00:00:00 +0000

Create a pull request (PR)#

Requirements#

Make sure your branch contains a single self-contained change. For example:
- If you are adding multiple resources to the provider, only put one resource in each PR - even if the product requires all resources to be present before it can be meaningfully used.
- If you are adding a few fields and also fixing a bug, create one PR for adding the new fields and a separate PR for the bugs.
Follow the instructions at Creating a pull request to create a pull request to merge your branch into GoogleCloudPlatform/magic-modules.
- Make sure the PR body includes the text Fixes GITHUB_ISSUE_LINK. once per issue resolved by your PR. Replace GITHUB_ISSUE_LINK with a link to a GitHub issue from the provider issue tracker.
- Write release notes

Code review#

(For Google-driven changes) Assign a service team engineer to review your change. Get their approval before proceeding with review by maintainers.
Creating a new pull request or pushing a new commit automatically triggers our CI pipelines and workflows. After CI starts, downstream diff generation takes about 10 minutes; VCR tests can take up to 2 hours. If you are a community contributor, some tests will only run after approval from a reviewer.
- While convenient, relying on CI to test iterative changes to PRs often adds extreme latency to reviews if there are errors in test configurations or at runtime. We strongly recommend you test your changes locally before pushing even after the initial change.
- VCR tests will first attempt to play back recorded HTTP requests (REPLAYING mode). If any tests fail, they will run in RECORDING mode to generate a new cassette; then, the same tests will run again in REPLAYING mode to detect any nondeterministic behavior in the test (which can cause flaky tests.)
A maintainer will automatically be assigned to your PR for final review.
If your assigned reviewer does not respond to changes on a pull request within two US business days, ping them on the pull request.

TIP: Speeding up review:

Immutable fields

Mon, 01 Jan 0001 00:00:00 +0000

Immutable fields#

Note: This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.

ForceNew in a Terraform resource schema attribute that indicates that a field is immutable – that is, that a change to the field requires the resource to be destroyed and recreated.

MMv1 resource reference

Mon, 01 Jan 0001 00:00:00 +0000

MMv1 resource reference#

This page documents commonly-used properties for resources. For a full list of available properties, see resource.go ↗.

Basic#

`name`#

API resource name.

`description`#

Resource description. Used in documentation.

Example:

description: |
 This is a multi-line description
 of a resource. All multi-line descriptions must follow
 this format of using a vertical bar followed by a line-break,
 with the remaining description being indented.

`references`#

Links to reference documentation for a resource. Contains two attributes:

Set up your development environment

Mon, 01 Jan 0001 00:00:00 +0000

Set up your development environment#

Before you start adding or updating a Terraform resource using magic-modules, you must first set up your environment by installing the necessary tools. This page explains the steps for setting up your development environment.

Install the gcloud CLI.
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don’t already have a project to use for testing changes to the Terraform providers, create a project instead of selecting an existing poject. After you finish these steps, you can delete the project, removing all resources associated with the project.

Types of breaking changes

Mon, 01 Jan 0001 00:00:00 +0000

Types of breaking changes#

A “breaking change” is any change that requires an end user to modify a previously-valid configuration after a provider upgrade. In this context, a “valid configuration” is one that:

Is considered syntactically correct by terraform validate
Does not return an error during terraform apply
Creates, updates, deletes, or does not modify resources
Only manages resources that have not been altered with other tools, such as gcloud or Cloud Console.

This document lists many types of breaking changes but may not be entirely comprehensive. Some types of changes that would normally be “breaking” may have specific mitigating circumstances that make them non-breaking.

Add a resource

Mon, 01 Jan 0001 00:00:00 +0000

Add a resource#

This page describes how to add a new resource to the google or google-beta Terraform provider using MMv1 and/or handwritten code.

For more information about types of resources and the generation process overall, see How Magic Modules works.

Before you begin#

Complete the steps in Set up your development environment to set up your environment and your Google Cloud project.

Ensure that your magic-modules, terraform-provider-google, and terraform-provider-google-beta repositories are up to date.

cd ~/magic-modules
git checkout main && git clean -f . && git checkout -- . && git pull
cd $GOPATH/src/github.com/hashicorp/terraform-provider-google
git checkout main && git clean -f . && git checkout -- . && git pull
cd $GOPATH/src/github.com/hashicorp/terraform-provider-google-beta
git checkout main && git clean -f . && git checkout -- . && git pull

Add a resource#

MMv1

Using an editor of your choice, in the appropriate product folder, create a file called RESOURCE_NAME.yaml. Replace RESOURCE_NAME with the name of the API resource you are adding support for. For example, a configuration file for NatAddress would be called NatAddress.yaml.

Add TGC conversion

Mon, 01 Jan 0001 00:00:00 +0000

Add TGC conversion#

This method of adding TGC support is currently experimental and not officially supported. We recommended this path only for core contributors.

terraform-google-conversion (TGC) consumes a Terraform plan and uses it to build Cloud Asset Inventory (CAI) Assets. These built assets only exist in memory locally.

TGC supports only those GCP resources that are available in both the Terraform provider and Cloud Asset Inventory.

Before you begin#

Getting a Terraform resource name from a GCP resource name#

The first step in determining if a GCP resource is supported is to identify the corresponding Terraform resource. You can often do this by searching for the GCP resource name in the Terraform google provider documentation.

Contribution process

Mon, 01 Jan 0001 00:00:00 +0000

Contribution process#

This page explains how you can contribute code and documentation to the magic-modules repository.

Before you begin#

Familiarize yourself with GitHub flow
Fork the Magic Modules repository into your GitHub account
Set up your development environment
Check whether the feature you want to work on has already been requested in the issue tracker.
- If there’s an issue and it already has a dedicated assignee, this indicates that someone might have already started to work on a solution. Otherwise, you’re welcome to work on the issue.

Contribute code#

Set up your development environment
Create a new branch for your change
Make the code change. For example:
Generate the providers that include your change.
Run provider tests locally that are relevant to the change you made
Create a pull request (PR)
(For Google-driven changes) Do a local review with a service team engineer
Make changes in response to maintainers’ code review

After your change is merged#

After your change is merged, it can take a week or longer to be released to customers.

Deletion policy

Mon, 01 Jan 0001 00:00:00 +0000

Deletion policy#

This page documents how to work with the deletion_policy field present in nearly all provider resources.

MMv1

MMv1 resources support deletion_policy out of the box without any complication or changes needed by a contributor.

There are three values allowed on every deletion_policy field:

PREVENT: This will block deletion of the resource.
ABANDON: Deletion of the resource will remove it from Terraform state but not from the API.
DELETE: Deletion of the resource will remove it from Terraform state and from the API.

Updating the default value of `deletion_policy` for a resource#

All resources will use a value of “DELETE” by default if unspecified, but this default can be changed to another value by including the following:

Handwritten docs style guide

Mon, 01 Jan 0001 00:00:00 +0000

Handwritten documentation style guide#

This document describes the style guide for handwritten documentation for resources and data sources. MMv1-based resources will automatically generate documentation that matches this style guide.

File name and location#

Handwritten documentation lives in:

Data sources: magic-modules/third_party/terraform/website/docs/d/
Resources: magic-modules/third_party/terraform/website/docs/r/

The name of the file is the name of the resource without a google_ prefix. For example, for google_compute_instance, the file is called compute_instance.html.markdown

YAML frontmatter#

Every resource or datasource documentation page must include YAML frontmatter which sets subcategory (where the page will be displayed in the left sidebar).

Make a breaking change

Mon, 01 Jan 0001 00:00:00 +0000

Guidance on making a breaking changes

MMv1 field reference

Mon, 01 Jan 0001 00:00:00 +0000

MMv1 field reference#

This page documents commonly-used properties for fields. For a full list of available properties, see type.go ↗.

Shared properties#

`name`#

Specifies the name of the field within Terraform. By default this will also be the key for the field in the API request message, if a separate api_name is not declared using the corresponding property.

`type`#

Sets the expected data type of the field. All valid types are declared here.

Review a pull request

Mon, 01 Jan 0001 00:00:00 +0000

Review a pull request#

This page provides guidelines for reviewing a Magic Modules pull request (PR).

Google-driven changes must have a service team engineer review changes prior to review by repository maintainers. For community members, this is not required.

Review#

Read the PR description to understand the context and ensure the PR either
- is linked to a GitHub issue or an internal bug
  - if not, check the issue tracker to see whether the feature has already been requested and add the issues in the description, if any.
  - “Fixes {github_issue_link}” is preferred if an external issue is available because it will auto-close the issue when the PR is merged. However, there’s no need to create an external issue solely for this purpose.
- establishes clear context itself via title or description.
If the PR adds any new resource, ensure that the resource does not already exist in the GA provider or beta provider
Read through all the changes in the PR, generated code in the downstreams and the API documentation to ensure that:
1. the resource schema added in the PR matches the API structure.
2. the features are added in the correct version
  - features only available in beta are not included in the GA google provider.
  - features added to the GA provider are also included in the beta provider – beta should be a strict superset of GA.
3. no breaking changes are introduced without a valid justification. Add the override-breaking-change label if there is a valid justification.
  - remember to check for changes in default behaviour like changing the flags on delete!
4. verify the change fully resolves the linked issues, if any. If it does not, change the “Fixes” message to “Part of”.
Check the tests added/modified to ensure that:
1. all fields added/updated in the PR appear in at least one test.
  - It is advisable to test updating from a non-zero value to a zero value if feasible.
2. all mutable fields are tested in at least one update test.
3. all resources in the acceptance tests have a tf-test or tf_test prefix in their primary id field.
4. all handwritten test Config steps include import steps following them
5. all related tests pass in GA for features promoted from beta to GA.
  
  Note: Presubmit VCR tests do not run in GA. Manual testing is required for promoted GA features.

Run tests

Mon, 01 Jan 0001 00:00:00 +0000

Run tests#

Before you begin#

Generate the modified provider(s)

Set up application default credentials for Terraform

gcloud auth application-default login
export GOOGLE_USE_DEFAULT_CREDENTIALS=true

Set the following environment variables:
```
export GOOGLE_PROJECT=PROJECT_ID
export GOOGLE_REGION=us-central1
export GOOGLE_ZONE=us-central1-a
```
Replace PROJECT_ID with the ID of the Google Cloud project you are using for testing.
Optional: Some tests may require additional variables to be set, such as:
```
GOOGLE_ORG
GOOGLE_BILLING_ACCOUNT
```

Run automated tests#

GA Provider

Run unit tests and linters

cd $GOPATH/src/github.com/hashicorp/terraform-provider-google
make test
make lint

Run acceptance tests for only modified resources. (Full test runs can take over 9 hours.) See Go’s documentation for more information about -run and other flags.

MMv1 sample reference

Mon, 01 Jan 0001 00:00:00 +0000

MMv1 sample reference#

A sample is a collection of one or more steps, where each step represents a distinct Terraform configuration and test step (for example, create, update).

Each sample supports the following attributes at the top level, with more granular control inside each step.

Sample Attributes (Top-Level)#

These attributes are defined once for an entire sample.

name: snake_case name for the overall sample. This is used for generating test names.
primary_resource_id: The ID of the main resource under test for the entire sample. Tests use this to run additional checks automatically.
primary_resource_type: Optional resource type override of the primary resource. Used for import assertion validations.
bootstrap_iam: Specify member/role pairs that should exist before the test runs. This avoids race conditions on global IAM permissions. {project_number} and {organization_id} are replaced automatically.
min_version: Sets a minimum provider version for the entire sample (for example, beta). This can be overridden by the min_version attribute within a specific step.
exclude_test: If true, no tests are generated for this entire sample.
exclude_basic_doc: If true, excludes the first step of this sample from the generated documentation. By default, the first step is automatically included as a use case in the documentation. Use this if you want to skip it.
skip_vcr: If true, skips VCR testing for the entire sample.
skip_test: If not empty, the entire sample is skipped during tests. The value should be a link to a ticket explaining why.
skip_func: A custom function call to run to determine if tests should be skipped.
region_override: Overrides location/region identifiers specifically inside IAM assertion checks.
external_providers: A list of external providers (such as random, time) needed for the sample.
tgc_skip_test: Skips generated conversion tests specifically running inside the TGC (Terraform Google Conversion) suite (value should be a ticket link reason).

Step Attributes#

A sample contains a list of one or more steps. Each step has its own configuration and test-specific attributes.

Add a field to an existing resource

Mon, 01 Jan 0001 00:00:00 +0000

Add a field to an existing resource#

This page describes how to add a field to an existing resource in the google or google-beta Terraform provider using MMv1 and/or handwritten code. In general, Terraform resources should implement all configurable fields and all read-only fields. Even fields that seem like they would not be useful in Terraform (like update time or etag) often end up being requested by users, so it’s usually easier to just add them all at once. However, optional or read-only fields can be omitted when adding a resource if they would require significant additional work to implement.

Labels and annotations

Mon, 01 Jan 0001 00:00:00 +0000

Add labels and annotations support#

Note: This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.

The new labels model and the new annotations model are introduced in Terraform provider for Google Cloud 5.0.0.

make commands

Mon, 01 Jan 0001 00:00:00 +0000

`make` commands reference#

`magic-modules`#

`make` / `make provider`#

Generates the code for the downstream google and google-beta providers into the OUTPUT_PATH, overriding and deleting any local changes.

Note: Generation works best if the downstream provider has a commit checked out corresponding to the latest main branch commit that is present in your magic-modules working branch. This can generally be identified based on matching commit messages.

Examples:

make provider VERSION=ga OUTPUT_PATH="$GOPATH/src/github.com/hashicorp/terraform-provider-google"
make provider VERSION=beta OUTPUT_PATH="$GOPATH/src/github.com/hashicorp/terraform-provider-google-beta"

Arguments#

OUTPUT_PATH: Required. The location you are generating provider code into.
VERSION: Required. The version of the provider you are building into. Valid values are ga and beta.
PRODUCT: Limits generations to the specified folder within mmv1/products. Handwritten files from mmv1/third_party/terraform are always generated into the downstream regardless of this setting, so you can provide a non-existent product name to generate only handwritten code. Required if RESOURCE is specified. Using PRODUCT skips the pre-generation cleanup step. This is considered advanced usage; recommend running a full, clean build (make provider without PRODUCT) beforehand if repositories may be out of sync.
SKIP_CLEAN: If set to true, skips the default pre-generation cleanup of OUTPUT_PATH during a full provider build. Has no effect if PRODUCT is specified (as cleanup is already skipped). Example: make provider VERSION=ga OUTPUT_PATH=... SKIP_CLEAN=true.
RESOURCE: Limits generation to the specified resource within a particular product. For mmv1 resources, matches the resource’s name field (set in its configuration file).

Cleaning up old files#

Magic Modules will only generate on top of whatever is in the downstream repository. This means that, from time to time, you may end up with stale files or changes in your downstream that cause compilation or tests to fail.

Write release notes

Mon, 01 Jan 0001 00:00:00 +0000

Write release notes#

This guide explains best practices for composing accurate, end-user focused release notes for Magic Modules pull requests.

Every pull request must have at least one release note block in the opening comment. Release note blocks have the following format:

```release-note:TYPE
CONTENT
```

Replace TYPE with the correct release note type, and CONTENT with a release note written according to the guidelines in the following sections.

General guidelines#

Do	Don’t
Only have one `CONTENT` line per release note block. Use multiple blocks if there are multiple related changes in a single PR.	Don’t add multiple lines to a single release note block. Avoid combining multiple distinct types of changes into one release block.
If a change only affects the `google-beta` provider add `(beta)` to the end of the release note. If a change only affects the `google` provider add `(ga)` to the end of the release note.	Don’t add either suffix if the change affects both providers.
Set an appropriate release note type.	Don’t leave the type as `REPLACEME`.

Type-specific guidelines and examples#

New field(s)

Write your release note in the following format:

Metadata (meta.yaml) reference

Mon, 01 Jan 0001 00:00:00 +0000

Metadata (meta.yaml) reference#

This page documents the properties available in meta.yaml files. These files make it easy to access data about the provider implementation without needing to compile the provider. They are used for coverage metrics and CAI-related overrides.

Meta.yaml files are auto-generated for MMv1 generated resources.

Handwritten resources will have handwritten meta.yaml files in the appropriate service directory in mmv1/third_party/terraform/services/. The file name will be resource_PRODUCT_RESOURCE_meta.yaml(.tmpl). For example, resource_compute_instance_meta.yaml.tmpl Handwritten meta.yaml files with a .tmpl extension can use version guards ({{- if ne $.TargetVersionName "ga" }}...{{- else}}...{{- end}}) to exclude beta fields from the google provider.

Add IAM support

Mon, 01 Jan 0001 00:00:00 +0000

Add IAM support#

This page covers how to add IAM resources in Terraform if they are supported by a particular API resource (indicated by setIamPolicy and getIamPolicy methods in the API documentation for the resource).

For more information about types of resources and the generation process overall, see How Magic Modules works.

Before you begin#

Complete the steps in Set up your development environment to set up your environment and your Google Cloud project.

Ensure that your magic-modules, terraform-provider-google, and terraform-provider-google-beta repositories are up to date.

cd ~/magic-modules
git checkout main && git clean -f . && git checkout -- . && git pull
cd $GOPATH/src/github.com/hashicorp/terraform-provider-google
git checkout main && git clean -f . && git checkout -- . && git pull
cd $GOPATH/src/github.com/hashicorp/terraform-provider-google-beta
git checkout main && git clean -f . && git checkout -- . && git pull

Add IAM support#

MMv1

IAM support for MMv1-generated resources is configured within the ResourceName.yaml file, and will create the google_product_resource_iam_policy, google_product_resource_iam_binding, google_product_resource_iam_member resource, website, and test files for that resource target when an iam_policy block is present.

Common resource patterns

Mon, 01 Jan 0001 00:00:00 +0000

Common resource patterns#

Singletons#

Singletons are resources – often config or settings objects – that can only exist once. In some cases, it may be possible to create and delete the resource (but only one can exist at a time); in other cases the resource always exists and can only be read and updated.

Implementing resources like this may require some or all of the following:

If there isn’t a create endpoint, set the create_url to point to the update endpoint.
If there is a create endpoint, add pre-create custom code that implements “acquire-on-create” logic. The custom code should check whether the resource already exists with a read request, and if it does, run the update logic and return early. For example, see mmv1/templates/terraform/pre_create/firebasehosting_site.go.tmpl.
- Note: The main disadvantage of “acquire-on-create” logic is that users will not be presented with a diff between the resource’s old and new states – because from the terraform perspective, the resource is only being created. Please upvote https://github.com/hashicorp/terraform/issues/19017 to request better support for this workflow.
If there is no delete endpoint, set exclude_delete: true at the top level of the resource.

Tests for singletons can run into issues because they are modifying a shared state. To avoid the problems this can cause, ensure that the tests create dedicated parent resources instead of modifying the default test environment. If there need to be multiple test cases, make sure they either have individual parent resources, or that they run serially, like TestAccAccessContextManager.

Ruby to Go Migration

Mon, 01 Jan 0001 00:00:00 +0000

What has changed in the MMv1 Go migration#

The Magic Modules code generator has been rewritten from Ruby to Go. For experienced contributors, this reference document lists what the expected changes are to the previous development workflow in Ruby.

YAML changes#

.yaml files within mmv1/products have had adjustments to the attribute typing. The initial Ruby lines !ruby/object:Api::Type::<TYPE> have been removed and replaced with a simpler type: <TYPE> line.

Old Ruby YAML

Test Template Migration Guide

Mon, 01 Jan 0001 00:00:00 +0000

Test Template Migration Guide#

The test generation framework in Magic Modules has been updated to natively support multi-step tests (create and update) directly from the resource’s YAML definition. This guide is for experienced contributors who are familiar with the previous examples based workflow and provides a concise overview of what has changed.

Transition Timeline#

Recommended Path: The new samples configuration block is the recommended path for adding tests.
Legacy Support: The old examples block path is still supported until Mid May 2026.
Action Required: Contributors are encouraged to use samples for all new tests and migrate existing examples to samples.

YAML Changes: From `examples` to `samples` and `steps`#

The most significant change is the replacement of the examples block with a new samples block. Each sample can now contain one or more steps, where the first step corresponds to the resource creation and any subsequent steps correspond to updates.

Validation

Mon, 01 Jan 0001 00:00:00 +0000

Validation#

There are a number of ways to add client-side validation to resources. The benefit of client-side validation is that errors can be surfaced at plan time, instead of partway through a (potentially very long) apply process, allowing for faster iteration. However, the tradeoff is that client-side validation can get out of sync with server-side validation, creating additional maintenance burden for the provider and preventing users from accessing the latest features without upgrading.

Add a datasource

Mon, 01 Jan 0001 00:00:00 +0000

Datasources are like terraform resources except they don’t create anything.

Add custom resource code

Mon, 01 Jan 0001 00:00:00 +0000

Add custom resource code#

This document covers how to add “custom code” to MMv1 resources. Custom code can be used to add arbitrary logic to a resource while still generating most of the code; it allows for a balance between maintainability and supporting real-worlds APIs that deviate from what MMv1 can support. Custom code should only be added if the desired behavior can’t be achieved otherwise.

Most custom code attributes are strings that contain a path to a template file relative to the mmv1 directory. For example:

Promote to GA

Mon, 01 Jan 0001 00:00:00 +0000

Promote from beta to GA#

This document describes how to promote an existing resource or field that uses MMv1 and/or handwritten code from the google-beta provider to the google (also known as “GA”) provider.

Handwritten code (including custom_code) commonly uses “version guards” in the form of {{- if ne $.TargetVersionName "ga" }}...{{- end }} to wrap code that is beta-specific, which need to be removed during promotion.

For more information about types of resources and the generation process overall, see How Magic Modules works.

Update dependencies

Mon, 01 Jan 0001 00:00:00 +0000

Update provider dependencies#

The Magic Modules repository does not contain a complete Go module, preventing the use of automated tooling like go get from that repository. To add or update provider dependencies, use standard Go tooling to update the dependency in the terraform-provider-google provider and copy the results to the upstream files in Magic Modules.

Below are the steps you can follow to make the change:

Navigate to the local google provider directory:

cd $GOPATH/src/github.com/hashicorp/terraform-provider-google

Open the go.mod file and add the new entries or modify the versions of existing entries as needed
Update dependencies using either of the following methods
- run the following commands to update all dependencies:
```
go get
go mod tidy
```
- Alternatively, update a specific package to a desired version:
```
go get google.golang.org/api@v0.105.0 
go mod tidy
```
Copy the contents of the updated go.mod and go.sum file into mmv1/third_party/terraform/go.mod and mmv1/third_party/terraform/go.sum in the magic-modules respectively.
Create a pull request containing only the dependency changes.
Resolve any errors caused by the dependency upgrade.
After the dependency pull request is merged, continue with a separate pull request for any additional changes that were blocked by the upgrade.

Fix diffs

Mon, 01 Jan 0001 00:00:00 +0000

Fix diffs#

This page outlines best practices for fixing various kinds of diffs that can show up at plan time. These will often show up as test failures with the text: After applying this test step, the plan was not empty.. They can also show up for users at plan time, on fields that a user has not modified in their configuration. If the diff does not go away even after running terraform apply more than once with the same configuration, the diff is called a “permadiff”.

Generate the providers

Mon, 01 Jan 0001 00:00:00 +0000

Generate `google` and `google-beta` providers#

After making a change to the Terraform providers for Google Cloud, you must integrate your changes with the providers. This page explains how to generate provider changes to the google and google-beta Terraform providers.

Before you begin#

Set up your development environment.
Update magic-modules as needed. These updates could be any of the following changes:

By default, running a full make provider command cleans the output directory (OUTPUT_PATH) before generating code to prevent sync issues. This will override and delete any changes to that directory. See the make commands reference for details on advanced usage.

Client-side fields

Mon, 01 Jan 0001 00:00:00 +0000

Client-side fields#

Client-side fields are most often used as flags to modify the behavior of a Terraform resource. Because they don’t correspond to an API field, there are some additional considerations in terms of how to implement them.

MMv1

Add to the schema#

Instead of adding the field in parameters or properties, use a section called virtual_fields.

Example:

virtual_fields:
 - name: 'send_propagated_connection_limit_if_zero'
 type: Boolean
 default_value: false
 description: |
 Controls the behavior of propagated_connection_limit.
 When false, setting propagated_connection_limit to zero causes the provider to use to the API's default value.
 When true, the provider will set propagated_connection_limit to zero.
 Defaults to false.

Handwritten

Add to the schema#

Add the field to the schema as usual.

Overview on Magic Modules

Add documentation

Add documentation#

Before you begin#

Add documentation#

Add resource tests

Add resource tests#

Create a pull request

Create a pull request (PR)#

Requirements#

Code review#

Immutable fields

Immutable fields#

MMv1 resource reference

MMv1 resource reference#

Basic#

name#

description#

references#

Set up your development environment

Set up your development environment#

Types of breaking changes

Types of breaking changes#

Add a resource

Add a resource#

Before you begin#

Add a resource#

Add TGC conversion

Add TGC conversion#

Before you begin#

Getting a Terraform resource name from a GCP resource name#

Contribution process

Contribution process#

Before you begin#

Contribute code#

After your change is merged#

Deletion policy

Deletion policy#

Updating the default value of deletion_policy for a resource#

Handwritten docs style guide

Handwritten documentation style guide#

File name and location#

YAML frontmatter#

Make a breaking change

MMv1 field reference

MMv1 field reference#

Shared properties#

name#

type#

Review a pull request

Review a pull request#

Review#

Run tests

Run tests#

Before you begin#

Run automated tests#

MMv1 sample reference

MMv1 sample reference#

Sample Attributes (Top-Level)#

Step Attributes#

Add a field to an existing resource

Add a field to an existing resource#

Labels and annotations

Add labels and annotations support#

make commands

make commands reference#

magic-modules#

make / make provider#

Arguments#

Cleaning up old files#

Write release notes

Write release notes#

General guidelines#

Type-specific guidelines and examples#

Metadata (meta.yaml) reference

Metadata (meta.yaml) reference#

Add IAM support

Add IAM support#

Before you begin#

Add IAM support#

`name`#

`description`#

`references`#

Updating the default value of `deletion_policy` for a resource#

`name`#

`type`#

`make` commands reference#

`magic-modules`#

`make` / `make provider`#

YAML Changes: From `examples` to `samples` and `steps`#

Generate `google` and `google-beta` providers#