This page describes how to use Infrastructure Manager to preview the deployment of
resources defined in a Terraform configuration.
A preview describes the actions to actuate a specific Terraform configuration.
Before you create a new deployment or update a deployment, you can preview the
deployment to verify the resources that are planned to be provisioned.
A preview executes the `Terraform plan` command. This page assumes you are
familiar with Terraform. For details, see
[Terraform and Infrastructure Manager](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt).
To create a preview, the Terraform configuration needs to be compatible with one
of the supported [Terraform versions](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt#terraform_versions).
## Before you begin
1. [Enable Infra Manager](https://docs.cloud.google.com/infrastructure-manager/docs/enable-service.md.txt).
2. Ensure that you have the IAM permissions needed to create previews: `roles/config.admin`.
3. Ensure you have a service account with the needed permissions. For details, see [Configure the service account](https://docs.cloud.google.com/infrastructure-manager/docs/configure-service-account.md.txt).
4. Identify the Terraform configuration to preview. Ensure this Terraform configuration complies with the [constraints](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt#constraints), including that the configuration does not contain sensitive data.
## Preview an update to a deployment
The Terraform configuration that you use to update a deployment can be in a
storage bucket or in a Git repository.
You also use this Terraform configuration to preview the update.
### Preview using a Terraform configuration stored in a Cloud Storage bucket
When you update a deployment, some of the existing resources might not
change. Previewing an update shows you what resources are planned to be
provisioned or deleted and what resources are not planned to be modified.
1. Identify the deployment that you want to update.
2. Ensure that the Terraform configuration is uploaded to a
Cloud Storage bucket. See
[Upload a configuration to a storage bucket](https://docs.cloud.google.com/infrastructure-manager/docs/upload-terraform-configuration.md.txt)
for more details.
A storage bucket lets you control access to the configuration. You
can also deploy a Terraform configuration that is stored in a
Git repository, or stored on your
local machine.
3. To preview the update:
```bash
gcloud infra-manager previews create projects/PROJECT_ID/locations/LOCATION/previews/PREVIEW_ID \
--service-account projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT \
--deployment=projects/PROJECT_ID/locations/LOCATION/deployments/DEPLOYMENT_ID \
--gcs-source gs://BUCKET_NAME/OBJECT_NAME \
--input-values=INPUT_1_NAME=VALUE,INPUT_2_NAME=VALUE \
--tf-version-constraint=TERRAFORM_VERSION \
--provider-source=SERVICE_MAINTAINED
```
Replace:
- PROJECT_ID is the project ID where Infrastructure Manager runs.
- LOCATION is the location where Infra Manager runs. See [Infrastructure Manager locations](https://docs.cloud.google.com/infrastructure-manager/docs/locations.md.txt) for the list of valid locations.
- PREVIEW_ID is the preview identifier that you specify. See [Preview name](https://docs.cloud.google.com/infrastructure-manager/docs/deployments-revisions.md.txt#preview_name) for details about constraints on the preview identifier.
- SERVICE_ACCOUNT is the name of the service account you use to call Infra Manager.
- SERVICE_ACCOUNT_PROJECT_ID is the project ID of the service account. It's common for this to be the same project where Infra Manager runs.
- DEPLOYMENT_ID is the deployment identifier of the deployment you want to update.
- BUCKET_NAME is the name of the storage bucket where the configuration is stored.
- OBJECT_NAME is the object name of configuration file. This
object can be a directory or a zip file, but not a Terraform file. If
you are using object versioning, you can also specify the
object's generation number. For more details, see
[Use versioned objects](https://docs.cloud.google.com/storage/docs/object-versioning.md.txt).
If the storage bucket is the root path of the Terraform configuration,
then OBJECT_NAME is optional.
- INPUT_1_NAME=VALUE and INPUT_2_NAME=VALUE: any
input values in the Terraform configuration, including ones that are
not defined by default. For example, you could specify the project
where you deploy the resources as `project_id=my-project`.
If all input values are defined by default in the configuration, then
this flag is optional.
- Optional: TERRAFORM_VERSION: the version of Terraform for
Infra Manager to use to preview the deployment update. See
[supported Terraform version](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt#terraform_versions)
for the list of supported versions. If you remove this optional flag,
Infra Manager uses the Terraform version of the existing
deployment, or defaults to the latest supported free tier version
(`1.5.7`). Previews don't incur charges for paid Terraform versions.
- Optional: PROVIDER_SOURCE: Determines which Terraform provider for Google Cloud the deployment uses. Set to `SERVICE_MAINTAINED` to use the Infra Manager maintained Terraform provider. Omit this field to use the HashiCorp-maintained Terraform provider. For more information, see [Use the Terraform provider for Google Cloud](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt#terraform-provider).
Fields from the deployment like the Terraform configuration, variables, and
service account are automatically merged into preview unless you specify
new values in the preview command.
Now that you have created a preview, you can
[export and view the results](https://docs.cloud.google.com/infrastructure-manager/docs/export-view-preview-results.md.txt)
to review the plan for the deployment.
### Preview using a Terraform configuration stored in a Git repository
When you update a deployment, some of the existing resources might not
change. Previewing an update shows you what resources are planned to be
provisioned or deleted and what resources are not planned to be modified.
1. If your Terraform configuration is stored in a private Git repository and you have not done so already, ensure that you have connected to [your GitHub host](https://docs.cloud.google.com/build/docs/automating-builds/github/connect-repo-github.md.txt?generation=2nd-gen#gcloud) and [GitHub repository](https://docs.cloud.google.com/build/docs/automating-builds/github/connect-repo-github.md.txt?generation=2nd-gen#connecting_a_github_repository_2) using Cloud Build to provide Infra Manager access to your repository.
2. To update a deployment:
```bash
gcloud infra-manager previews create projects/PROJECT_ID/locations/LOCATION/previews/PREVIEW_ID \
--service-account projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT \
--deployment=projects/PROJECT_ID/locations/LOCATION/deployments/DEPLOYMENT_ID \
--git-source-repo="GIT_REPO" \
--git-source-directory="DIRECTORY" \
--git-source-ref="REF" \
--input-values=INPUT_1_NAME=VALUE,INPUT_2_NAME=VALUE \
--tf-version-constraint=TERRAFORM_VERSION \
--provider-source=SERVICE_MAINTAINED
```
Replace:
- PROJECT_ID is the project ID where Infrastructure Manager runs.
- LOCATION is the location where Infra Manager runs. See [Infrastructure Manager locations](https://docs.cloud.google.com/infrastructure-manager/docs/locations.md.txt) for the list of valid locations.
- PREVIEW_ID is the preview identifier that you specify. See [Preview name](https://docs.cloud.google.com/infrastructure-manager/docs/deployments-revisions.md.txt#preview_name) for details about constraints on the preview identifier.
- SERVICE_ACCOUNT is the name of the service account you use to call Infra Manager.
- SERVICE_ACCOUNT_PROJECT_ID is the project ID of the service account. It's common for this to be the same project where Infra Manager runs.
- DEPLOYMENT_ID is the deployment identifier of the deployment you want to update.
- GIT_REPO: the Git repository.
- DIRECTORY: the directory that has the Terraform configuration.
- REF: the Git reference of the configuration. The reference is optional. If you don't specify the reference, the Git repository's default configured branch is used.
- INPUT_1_NAME=VALUE and INPUT_2_NAME=VALUE: any
input values in the Terraform configuration, including ones that are
not defined by default. For example, you could specify the project
where you deploy the resources as `project_id=my-project`.
If all input values are defined by default in the configuration, then
this flag is optional.
- Optional: TERRAFORM_VERSION: the version of Terraform for
Infra Manager to use to preview the deployment update. See
[supported Terraform version](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt#terraform_versions)
for the list of supported versions. If you remove this optional flag,
Infra Manager uses the Terraform version of the existing
deployment, or defaults to the latest supported free tier version
(`1.5.7`). Previews don't incur charges for paid Terraform versions.
- Optional: PROVIDER_SOURCE: Determines which Terraform provider for Google Cloud the deployment uses. Set to `SERVICE_MAINTAINED` to use the Infra Manager maintained Terraform provider. Omit this field to use the HashiCorp-maintained Terraform provider. For more information, see [Use the Terraform provider for Google Cloud](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt#terraform-provider).
Fields from the deployment like the Terraform configuration, variables, and
service account are automatically merged into preview unless you specify
new values in the preview command.
Now that you have created a preview, you can
[export and view the results](https://docs.cloud.google.com/infrastructure-manager/docs/export-view-preview-results.md.txt)
to review the plan for the deployment.
## What's next
- [Export and view preview results](https://docs.cloud.google.com/infrastructure-manager/docs/export-view-preview-results.md.txt)
- Use Infra Manager to [deploy resources](https://docs.cloud.google.com/infrastructure-manager/docs/deploy-resources.md.txt).
- [Automate deployments](https://docs.cloud.google.com/infrastructure-manager/docs/automate-git.md.txt).
- Learn more about [Terraform with Infra Manager](https://docs.cloud.google.com/infrastructure-manager/docs/infra-manager-terraform.md.txt).