Factor common IAM policy bits into 'google.cloud.iam'.

[tseaver]

Toward #1679.

Pubsub-specific roles, permissions left behind in google.cloud.pubsub.iam.

google.cloud.pubsub.iam.Policy subclasses the core one, extending it to deal with the pubsub-specific roles.

[theacodes]

/cc @elibixby

[elibixby]

I had a previous proposal to do this which got abandoned due to slow review cycle, but it's here: See #2031

The key takeaway: the API representation of bindings is really gross to interact with. Client side it would be much nicer if bindings were a dict with roles as keys, and member sets as values. So instead of code like:

def add_role(policy, my_role, my_member):
roles = [binding['role'] for binding in policy.bindings]
if my_role in roles:
members = policy.bindings[roles.index(my_role)]
if my_member not in members:
members.append(my_member)
else:
policy.bindings.append({'role': my_role, 'members': [my_member]})
return policy

We had code like:

def add_role(policy, my_role, my_member):
return policy.bindings.setdefault(my_role, set()).add(my_member)

[elibixby]

Additionally note that Roles are an API resource, and should be represented with an object. What does the resource.queryGrantableRoles method return? Raw JSON?

Both resource.queryGrantableRoles and resource.testIamPermissions are part of the IAM meta API and must be implemented on every resource that supports IAM.

Role resources will be user managed with the addition of custom roles (currently in alpha), and will have a list of iam permissions that they grant, which will be important for user protection of custom methods, and for identifying the necessary roles that a member needs to be granted. (combining resource.testIamPermissions and resource.queryGrantableRoles)

Further explanation of suggestions like these can be found in comment threads in #2031

EDIT: Slight correction: testIamPermissions is indeed part of the meta API, but queryGrantableRoles calls directly to the IAM API, but can be called with ANY one platform resource string, so it might make more sense to have it as a method on a Resource object that implements an IAM mixin anyway.

EDIT2: This can probably be tackled in a followup PR, but should be considered when defining the interface? Do we want to make policy.bindings a map <string: set> or a map <Role: set> I think likely still the former, since we wont be receiving role metadata along with a policy, but it's worth consideration.

[tseaver]

@elibixby I think I have addressed your concerns about supporting user-defined roles in b625017.

re: queryGrantableRoles: We can't propely target implementing support for not-yet-released APIs in the public repository: my current writ is to get storage up to the same level of IAM support that pubsub currently has. I will be adding storage-specific implementations of get_iam_policy, set_iam_policy, and test_iam_permissions in a separate PR.

[elibixby]

@tseaverqueryGrantableRoles isn't unreleased...https://cloud.google.com/iam/reference/rest/v1/roles/queryGrantableRoles

But I agree that this can be tackled in a follow-up PR.

Long term I still believe a common implementatoin for One Platform APIs will save you the most heartache. Storage is an oddball because it is so old (i.e. not a One Platform API) and IAM support was "backported" in a slightly weird way. But going forward all OP APIs will share a common IAM signature, and a Mixin could provide drop in support for that.

[lukesneeringer]

EDIT @lukesneeringer I think doing @tseaver approach and then moving to my approach immediately before GA is a reasonable approach, thoughts @tseaver?

This is fine with me also.

[lukesneeringer]

@tseaver Checking on the status of this. :-)

[tseaver]

@lukesneeringer I'm back at this, but can't figure out what the desired resolution would be. Here is a sketch at a way forward:

• Return frozenset instances from the getters for owners, editors, and viewers (breaking anybody who expects to mutate them in place, rather than re-assigning them).
• Emit DeprecationWarning from the setters for those properties, pointing people to the desired surface.

Then, the question is what the desired surface would be: I'm really leery of exposing the mutable bindings attribute as a dict: it allows us no way to do any checking at all. We could:

• Make the Policy class dict-like, with roles as keys and lists of principals as values. The __setitem__ implementation would give us the hook to do any required checking.

• Make Policy.bindings a dict-like object with a similar __setitem__.

• Add a Policy.bind(role, *principals) method, and use whatever backing store we like.

[lukesneeringer]

My personal preference is the first option (making Policy dict-like and defining __setitem__ to include appropriate validation).

[tseaver]

@lukesneeringer That is my preference as well. Update on the way.

[tseaver]

@lukesneeringer OK, I've updated Policy to be dict-like, and added deprecations for assignment to the "named" role attributes.

[lukesneeringer]

Approved, but giving @elibixby a chance to weigh in before merge.

[lukesneeringer]

Merging this when CI goes green.