Troubleshoot deployment errors

This page describes:

Inspect deployment details and logs

You can inspect details and logs for both deployment and individual revisions.

Inspect the state of the deployment

Each deployment has information about its current state, error code, and details about failure causes.

For any errors, start by viewing the state of a deployment.

Inspect the state of a revision

If a deployment fails with error code REVISION_FAILED, you can view the state of a revision.

In the output of the revision's state, look at the stateDetail and errorCode fields.

The state of the revision includes the same information as for a deployment. In addition, it includes the build ID.

Inspect the Cloud Build logs

View the state of a revision and get the build ID of the Cloud Build used by the revision.

Use the build ID to inspect the Cloud Build logs. See View build results for details about inspecting build results.

Common errors

This section describes common errors you might see when deploying a Terraform configuration with Infra Manager.

Failed deployment

If the deployment state is FAILED the deployment has encountered an unexpected error.

View the state of the deployment and inspect the stateDetail and errorCode fields for more information.

If a deployment fails with error code REVISION_FAILED, you can inspect the state of the revision.

Configuration errors

If the deployment's state is FAILED, it might have failed because of configuration errors with the Terraform configuration.

If the deployment error is related to your configuration, tfErrors and errorLogs fields are included in the output of the state of the deployment. Examples of configuration errors include an invalid configuration or missing permissions.

View the errors from Terraform. In the output of the state of the deployment:

  • tfErrors is a summary of the errors encountered by Terraform (limited by Infra Manager to 10 errors in this list).
  • errorLogs point to a Cloud Storage object in your artifacts bucket. This bucket contains all tfErrors in new line delimited JSON format.

Each tfError has a resource address and human readable error description in the errorDescription field. If the resource fails due an HTTP error code returned from a Google Cloud API, the httpResponseCode field is also populated. Any additional API failure information is recorded in the error field.

Service account missing permissions to fetch configuration

You see the following error:

  error downloading 'GCS_LOCATION': googleapi: Error 403: SA_EMAIL does
  not have storage.objects.list access to the Google Cloud Storage bucket.

You see this error because Infra Manager doesn't have permission to get the Terraform configuration from Cloud Storage bucket.

To address the issue, grant the storage.objectViewer role to the service account. For details about granting permissions to the service account, see Configure the service account.

Incorrect location to fetch configuration

You see the following error:

  `blueprint fetch failed: invalid path`

You see this error when an invalid location is specified to fetch the Terraform configuration. Infra Manager uses the term blueprint to refer to a Terraform configuration.

To address this error, verify the location of the Terraform configuration, and ensure that the location is formatted correctly in your command.

Incorrect permission to actuate resources

Errors are usually under tfErrors with the 403 response code for the resources that couldn't be deployed.

You see this error when the service account doesn't have enough permission to create, read, update, or delete resources defined in the Terraform configuration.

To address this error, see Grant the service account IAM permissions.

Configuration with backend

You see the following error:

  `blueprint invalid: found backend config in file.tf`

You see this error when the Terraform configuration has a backend block. Infrastructure Manager manages the backend, so a backend block cannot be defined in the Terraform configuration.

To address this error, remove the backend block from the configuration.

Validate Cloud Build repository configuration

If Infra Manager cannot access your Git repository (using a private Git repository or Cloud Build automated workflow), you may need to validate that your Cloud Build repository has been configured correctly.

To validate that the Cloud Build repository has been configured to provide access to the private repository, see Connect to a GitHub repository.

Infra Manager uses the first connection where the Cloud Build repository URL matches the Terraform configuration (referenced in --git-source-repo), and where it is able to generate a read-only token. The repository connection is validated directly by a call to the accessReadToken API on the selected Cloud Build repository.

Run this command using the Infra Manager service account to verify that the permissions are correct:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token \
--impersonate-service-account=SERVICE_ACCOUNT)" \
"https://cloudbuild.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/connections/CB_CONNECTION/repositories/CB_REPO:accessReadToken"

What's next