What is the meaning of "authoritative" and "authoritative" for GCP IAM bindings/members

Question

I am trying to understand the difference between google_service_account_iam_binding and google_service_account_iam_member in the GCP terraform provider at https://www.terraform.io/docs/providers/google/r/google_service_account_iam.html.

I understand that google_service_account_iam_binding is for granting a role to a list of members whereas google_service_account_iam_member is for granting a role to a single member, however I'm not clear on what is meant by "Authoritative" and "Non-Authoritative" in these definitions:

google_service_account_iam_binding: Authoritative for a given role. Updates the IAM policy to grant a role to a list of members. Other roles within the IAM policy for the service account are preserved.

google_service_account_iam_member: Non-authoritative. Updates the IAM policy to grant a role to a new member. Other members for the role for the service account are preserved.

Can anyone elaborate for me please?

Answer 1

This link helps a lot.
Basically it means:
if a role is bound to a set of IAM identities and you want to add more identities, authoritative one will require you to specify all the old identities again plus the new identies you wanna add otherwise any old identities you didn't specify will be unbinded from the role. It is quite close to the idea of force push in git cause it will overwrite any existing stuff. In our case it is identity.

Non-authoritative is the opposite: You only need to care the identity you are updating

Answer 2

"Authoritative" means to change all related privileges, on the other hand, "non-authoritative" means not to change related privileges, only to change ones you specified.

Otherwise, you can interpret authoritative as the single source of truth, and non-authoritative as a piece of truth.

Answer 3

Authoritative may remove existing configurations and destroy your project, while Non-Authoritative does not.

The consequence of using the Authoritative resource can be severely destructive. You may regret if you used them. Do not use them unless you are 100% confident that you must use Authoritative resources.

• Usability improvements for *_iam_policy and *_iam_binding resources #8354

I'm sure you know by now there is a decent amount of care required when using the *_iam_policy and *_iam_binding versions of IAM resources. There are a number of "be careful!" and "note" warnings in the resources that outline some of the potential pitfalls, but there are hidden dangers as well. For example, using the google_project_iam_policy resource may inadvertently remove Google's service agents' (https://cloud.google.com/iam/docs/service-agents) IAM roles from the project. Or, the dangers of using google_storage_bucket_iam_policy and google_storage_bucket_iam_binding, which may remove the default IAM roles granted to projectViewers:, projectEditors:, and projectOwners: of the containing project.

The largest issue I encounter with people running into the above situations is that the initial terraform plan does not show that anything is being removed. While the documentation for google_project_iam_policy notes that it's best to terraform import the resource beforehand, this is in fact applicable to all *_iam_policy and *_iam_binding resources. Unfortunately this is tedious, potentially forgotten, and not something that you can abstract away in a Terraform module.

See terraform/gcp - In what use cases we have no choice but to use authoritative resources? and reported issues.

A simple example. If you run the script, what you think will happen. Do you think you can continue using your GCP project?

resource "google_service_account" "last_editor_standing" {
  account_id   = "last_editor_standing"
  display_name = "last editor you will have after running this terraform"
}

resource "google_project_iam_binding" "last_editor_standing" {
  project = "ToBeDemised"
  members = [
    "serviceAccount:${google_service_account.last_editor_standing.email}"
  ]
  role     = "roles/editor"                                    
}

This will at least delete the Google APIs Service Agent which is essential to your project.

If you still think it is the type of resource to use, use at own your risk.