Update a deployment

This page describes how to use Infrastructure Manager to update a deployment. Cases where you may update a deployment include:

  • To return your infrastructure to a desired state.

    When you create a deployment, after some time resources may have changed. For example, some of the resources may have been modified by someone working in the console. You can update the deployment using the original Terraform configuration to return it to the desired state.

  • To implement changes to the infrastructure.

    After you create a deployment, you may want to modify the infrastructure. For example, adding new resources or changing some of the configuration. You can update the deployment using a Terraform configuration that describes the new desired infrastructure.

To update a deployment, you deploy a configuration using the same deployment name, and this creates a revision. For more details, see Deployments and revisions overview.

If you do not have an existing deployment, see Deploy infrastructure using Infrastructure Manager.

To preview an update without provisioning resources, see Preview a deployment.

This page assumes you are familiar with Terraform. For details, see Terraform and Infrastructure Manager.

Before you begin

  1. Ensure Infra Manager is enabled.
  2. Ensure that you have the IAM permissions needed to create deployments: roles/config.admin
  3. Ensure you have a service account with the needed permissions. For details, see Configure the service account.
  4. Identify the Infra Manager deployment to update.

  5. Identify the Terraform configuration to deploy for the update. Any configuration can be used for a revision. This configuration is often an identical or updated version of the configuration already deployed.

    Ensure this Terraform configuration complies with the constraints,including that the configuration does not contain sensitive data.

  6. Confirm your organization's quota for products associated with your intended infrastructure. You may face deployment errors if your intended infrastructure exceeds your organization's quota for the products your deployment uses. See quotas and limits for more information.

  7. Take any necessary steps for data migration or service continuity for the resources that you are modifying.

  8. If you want to preview the update before configuring resources, then see Preview an update to a deployment.

Grant permissions specific to the configuration

To deploy Google Cloud resources that are specified in the Terraform configuration, the service account that you use to call Infra Manager needs permissions that are specific to:

  • Google Cloud resources defined in the configuration that you are using for the revision.

  • If the configuration you're using for the revision defines different resources than the configuration used for the deployment, then you need permissions for the resources defined in both configurations.

The permissions specific to the resources defined in the configuration are in addition to the permissions that the service account needs to use the Infra Manager service.

For details about granting permissions for the Google Cloud resources and ensuring you have access to the needed projects, see Configure the service account.

Update using a Terraform configuration stored in a Cloud Storage bucket

This section describes how to work with a Terraform configuration that is stored in a Cloud Storage bucket. You can also deploy a Terraform configuration that is stored in a Git repository, or stored on your local machine.

To deploy the configuration and create a revision:

  1. Ensure the Terraform configuration is in a Cloud Storage bucket. See Upload a Terraform configuration to a storage bucket for more details.

  2. If the storage bucket is in a different project from the project where you are running Infra Manager, then you need to ensure that Infra Manager's service account has read permission for the bucket. See Configure the service account for more details.

    If the storage bucket is in the same project as Infra Manager, read permission to the bucket is already enabled.

  3. Deploy the Terraform configuration:

    gcloud infra-manager deployments apply projects/PROJECT_ID/locations/LOCATION/deployments/DEPLOYMENT_ID \
    --service-account projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT \
    --gcs-source gs://BUCKET_NAME/OBJECT_NAME \
    --quota-validation=QUOTA_VALIDATION \
    --input-values=INPUT_1_NAME=VALUE,INPUT_2_NAME=VALUE
    --tf-version-constraint=TERRAFORM_VERSION \
    --annotation="ANNOTATION_KEY=ANNOTATION_VALUE"
    • PROJECT_ID is the project ID where Infrastructure Manager runs.
    • LOCATION is the location where Infra Manager runs. See Infrastructure Manager locations for the list of valid locations.
    • DEPLOYMENT_ID is the deployment identifier of the deployment you're updating.
    • 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.
    • 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.

      If the storage bucket is the root path of the Terraform configuration, then OBJECT_NAME is optional.

    • Optional: QUOTA_VALIDATION: the value that determines whether quota validation for resources in your Terraform configuration files is enabled or enforced when you create a deployment. Possible values include:

      • ENABLED: Enable computing quota validation for resources in Terraform configuration files. Provides visibility on resources with insufficient quotas.
      • ENFORCED: Enforce quota validation so that your deployment will fail if there isn't sufficient quota available for the infrastructure defined in your Terraform configuration file

      If quota-validation is not defined, quota validation on Terraform configuration files will be disabled. This is the default value. Quota validation applies on limited Google Cloud resources. For more information, see Quotas and limits

    • 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 create the deployment. See supported Terraform version for the list of supported versions. If you remove this optional flag, the latest supported version of Terraform is used.

    • Optional: ANNOTATION_KEY and ANNOTATION_VALUE represent a key-value pair of free-form text that can be attached to your Infra Manager deployments. For more information about the use and constraints of annotations and labels, see Annotations and labels.

Update using a Terraform configuration stored in a Git repository

This section describes how to work with a Terraform configuration that is stored in a Git repository. You can also deploy a Terraform configuration that is stored in a storage bucket, or stored on your local machine.

To update a deployment stored in a private Git repository, ensure that you have connected to your GitHub host and repository using Cloud Build to provide Infra Manager access to your repository.

To deploy the configuration and create a revision:

  1. If you are using a private Git repository, use the following steps to connect Cloud Build to your Git host and repository. If you have already connected your Git host and repository to Cloud Build, you can skip this step:

    GitHub

    Connect to your GitHub host and your GitHub repository using Cloud Build.

    GitHub Enterprise

    Connect to your GitHub Enterprise host and your GitHub Enterprise repository using Cloud Build.

    GitLab

    Connect to your GitLab host and your GitLab repository using Cloud Build.

    GitLab Enterprise Edition

    Connect to your GitLab Enterprise Edition host and your GitLab Enterprise Edition repository using Cloud Build.

  2. Deploy the configuration and create a revision:

    gcloud infra-manager deployments apply projects/PROJECT_ID/locations/LOCATION/deployments/DEPLOYMENT_NAME \
   --service-account projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT \
   --git-source-repo="GIT_REPO" \
   --git-source-directory="DIRECTORY" \
   --git-source-ref="REF" \
   --quota-validation=QUOTA_VALIDATION \
   --input-values=VALUE_1,
   VALUE_2
   --tf-version-constraint=TERRAFORM_VERSION \
   --annotation="ANNOTATION_KEY=ANNOTATION_VALUE"
    • PROJECT_ID is the project ID where Infrastructure Manager runs.
    • LOCATION is the location where Infra Manager runs. See Infrastructure Manager locations for the list of valid locations.
    • DEPLOYMENT_ID is the deployment identifier of the deployment you're updating.
    • 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.
    • GIT_REPO is the Git repository.
    • DIRECTORY is the directory that has the Terraform configuration.
    • REF is the Git reference of the configuration.

    • Optional: QUOTA_VALIDATION: the value that determines whether quota validation for resources in your Terraform configuration files is enabled or enforced when you create a deployment. Possible values include:

      • ENABLED: Enable computing quota validation for resources in Terraform configuration files. Provides visibility on resources with insufficient quotas.
      • ENFORCED: Enforce quota validation so that your deployment will fail if there isn't sufficient quota available for the infrastructure defined in your Terraform configuration files.

      If quota-validation is not defined, quota validation on Terraform configuration files will be disabled. This is the default value. Quota validation applies on limited Google Cloud resources. For more information, see Quotas and limits.

    • 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 create the deployment. See supported Terraform version for the list of supported versions. If you remove this optional flag, the latest supported version of Terraform is used.

    • Optional: ANNOTATION_KEY and ANNOTATION_VALUE represent a key-value pair of free-form text that can be attached to your Infra Manager deployments. For more information about the use and constraints of annotations and labels, see Annotations and labels.

Update using a Terraform configuration stored on your local machine

This section describes how to work with a Terraform configuration that is stored in Cloud Shell or locally. You can also deploy a Terraform configuration that is stored in a storage bucket, or stored in a Git repository.

  1. If you use Cloud Shell, then you need to upload the configuration to Cloud Shell. For details, see Manage files with Cloud Shell.

  2. To deploy the configuration and create a revision:

    gcloud infra-manager deployments apply projects/PROJECT_ID/locations/LOCATION/deployments/DEPLOYMENT_ID \
--service-account projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT \
--local-source="LOCAL_DIRECTORY" \
--quota-validation=QUOTA_VALIDATION \
--input-values=VALUE_1,VALUE_2
--tf-version-constraint=TERRAFORM_VERSION \
--annotation="ANNOTATION_KEY=ANNOTATION_VALUE"
    • PROJECT_ID is the project ID where Infrastructure Manager runs.
    • LOCATION is the location where Infra Manager runs. See Infrastructure Manager locations for the list of valid locations.
    • DEPLOYMENT_ID is the deployment identifier of the deployment you're updating.
    • 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.
    • LOCAL_DIRECTORY: the local directory storing the Terraform configuration. If you are using Cloud Shell, this is the directory in Cloud Shell where the configuration is stored.

    • Optional: QUOTA_VALIDATION: the value that determines whether quota validation for resources in your Terraform configuration files is enabled or enforced when you create a deployment. Possible values include:

      • ENABLED: Enable computing quota validation for resources in Terraform configuration files. Provides visibility on resources with insufficient quotas.
      • ENFORCED: Enforce quota validation so that your deployment will fail if there isn't sufficient quota available for the infrastructure defined in your Terraform configuration file

      If quota-validation is not defined, quota validation on Terraform configuration files will be disabled. This is the default value. Quota validation applies on limited Google Cloud resources. For more information, see Quotas and limits.

    • 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 create the deployment. See supported Terraform version for the list of supported versions. If you remove this optional flag, the latest supported version of Terraform is used.

    • Optional: ANNOTATION_KEY and ANNOTATION_VALUE represent a key-value pair of free-form text that can be attached to your Infra Manager deployments. For more information about the use and constraints of annotations and labels, see Annotations and labels.

What's next