Add provider documentation describing use of user_project_override and where APIs need to be enabled relative to which project Terraform's identity is in

[SarahFrench]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request.
• Please do not leave +1 or me too comments, they generate extra noise for issue followers and do not help prioritize the request.
• If you are interested in working on this issue or have submitted a pull request, please leave a comment.
• If an issue is assigned to a user, that user is claiming responsibility for the issue.
• Customers working with a Google Technical Account Manager or Customer Engineer can ask them to reach out internally to expedite investigation and resolution of this issue.

Description

There are various factors that affect if a user encounters a permissions error/service not enabled error:

• setting user_project_override
• setting user_project_override in combination with billing_project
• where different APIs are enabled or disabled in the context of a multi-project setup, also in the context of the above two provider arguments being set or not.

This problem also surfaces when users create a new project and try to enable APIs in the new service. Depending on their setup that API will need to be enabled in the project that the service account they are using as Terraform's identity is provisioned in. This is confusing and results in erroneous bug reports.

This is also a reason why enabling the service usage API in projects by default (https://github.com/hashicorp/terraform-provider-google/issues/14174) is a feature request that's unlikely to be implemented soon; users would need to set user_project_override correctly to avoid tainting the provisioned project resource if API call to activate the service usage API failing due to lack of permissions.

---

We should write up some provider documentation that covers all the different scenarios possible with these settings, including scenarios like:

• enabling an API in a newly provisioned project
• working in a multi-project environment

There is an existing guide here about use of google_project_service that might need updating/extending: https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/google_project_service

The guide would need to cover concepts like:

• "consumer projects"
• "resource projects"
• Where an API needs to be enabled relative to the service account used to authenticate Terraform
• How user project overrides can impact the above, and how that intersects with consumer/resource projects
  • X-Goog-User-Project header

New or Affected Resource(s)

• google_project_service

Potential Terraform Configuration

N/A

References

• https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/google_project_service
• https://github.com/hashicorp/terraform-provider-google/issues/14174

b/343221059

[SarahFrench]

Here's another data point about where APIs need to be enabled: https://github.com/hashicorp/terraform-provider-google/issues/11255#issuecomment-2188681866

[SarahFrench]

Another example: https://github.com/hashicorp/terraform-provider-google/issues/18281