Rename scope prefix "assume:" to "role:"

RESOLVED WONTFIX

Status

RESOLVED WONTFIX
3 years ago
3 years ago

People

(Reporter: pmoore, Unassigned)

Tracking

Details

(Reporter)

Description

3 years ago
The scope "assume:<role-id>" expands to all scopes of role "<role-id>".

The interplay between roles and scopes, role prefixes and scope prefixes, role expansions and scope expansions, assigned scopes and required scopes, can be confusing, especially for new users.

To lessen this confusion and remove some of the "magic" it would be simpler for the scope "role:<role-id>" to expand to all scopes of role "<role-id>" rather than the scope "assume:<role-id>".

Reasoning:

1) You have the scope "assume:governor". Is governor a role, a scope, a user, or a client-id? It is hard to say. If you have the scope "role:governor" it is quite reasonable to assume that "governor" is in fact a role.

2) We do this with other special prefixes. For example the role prefix "client-id:" prefixes a client-id. If you see the role "client-id:pmoore" you can easily reason that  there is probably a client-id called "pmoore" and that the role "client-id:pmoore" will be a role which is given to this client-id. In terms of nomenclature, the role naming "role:<role>" is consistent with the scope naming "client-id:<client-id>". It says what it is, and makes it easy for users to infer what it relates to, and thereby what it might mean.

I think it is important to change this *soon* since the longer we wait, the more difficult this will be to change. And this fundamentally impacts userbility - the easier the system is to reason about, the better it will be. The longer we wait to change this, the more it will cost to change it.
not a bug.. just a matter of taste...

  assume:<role>:<specifier>

isn't bad, example:
  assume:worker-type:aws-provisioner-v1/b2gtest

This scopes reads as:
  Authority to "assume" the "worker-type" named "aws-provisioner-v1/b2gtest".
Status: NEW → RESOLVED
Last Resolved: 3 years ago
Resolution: --- → WONTFIX
(Reporter)

Comment 2

3 years ago
(In reply to Jonas Finnemann Jensen (:jonasfj) from comment #1)
> not a bug.. just a matter of taste...
> 
>   assume:<role>:<specifier>
> 
> isn't bad, example:
>   assume:worker-type:aws-provisioner-v1/b2gtest
> 
> This scopes reads as:
>   Authority to "assume" the "worker-type" named "aws-provisioner-v1/b2gtest".

I'm afraid this is a misunderstanding - in this bug I am not challenging how understandable the term "assume" is - as you illustrate above, it is quite easy to infer what the *meaning* is.

This bug addresses the following: after establishing that this scope provides you with the authority to assume the identity of the worker-type "aws-provisioner/b2gtest", how do you find out how that is achieved, which lower level scopes this relates to, and how are those controlled/maintained? The answer is that there is a *role* called "worker-type:aws-provisioner-v1/b2gtest". This is the place to look. If instead this scope was called "role:worker-type:aws-provisioner-v1/b2gtest" it would be trivial to see that this scope expands to a set of scopes via the role "worker-type:aws-provisioner-v1/b2gtest".

The problem with issues like these, is that it is extremely easy for people _who work on the project_ to understand what these naming means, but very difficult for people outside with little exposure, to infer about. Tribal knowledge becomes necessary, whereas with more explicit naming, nobody can ever be confused by this topic. Such obstacles when trying to understand a system become barriers to adoption, hinder progress, and cause confusion.

I still advocate that we adapt the name.
Status: RESOLVED → REOPENED
Resolution: WONTFIX → ---
I see your point, and I agree that removing obstacles is important.

However, this particular area of TC is never going to be documentation-free -- even if you guess that the "role:foo" in a list of scopes you see somewhere refers to a role named foo, and thus open the "roles" section of tools.tc.net, you still won't know how *'s work, what the final scopes mean, etc.

Documentation's a real weak point right now, and we actually don't have any narrative docs about roles and scopes.  But when we do, we just define the verb "assume" and its relationship to the noun "role":

  A client can *assume* a role, gaining all of the scopes implied by that role, by adding the special scope 
  `assume:$role` to its list of scopes.  For example: ..

"role" just doesn't make a very good verb :)

On a related note, I want to get away from checking for roles, e.g., queue.claimTask requiring `assume:worker-id:xx/yy`.  Just because it's elegant in the backend, doesn't mean we should do it.  It confuses authentication ("I am worker xx/yy") with authorization ("I can claim this sort of task") and in many cases leads to clients claiming identities they do not have (e.g., I have to pretend to be a scheduler to re-run a task).  That's another fleet of bugs, but relevant here as a point of confusion on the topic of roles.
(Reporter)

Comment 4

3 years ago
Thanks Dustin for your feedback.

> However, this particular area of TC is never going to be documentation-free -- even if you guess that the "role:foo" in a list of scopes you see somewhere refers to a role named foo, and thus open the "roles" section of tools.tc.net, you still won't know how *'s work, what the final scopes mean, etc.

I think this is a https://en.wikipedia.org/wiki/Straw_man - I don't propose that TC is documentation-free, only that in this case where something can be intuitively inferred, we should support it. Just because not all things can be inferred, does not mean none of them should be inferable, so I'd say reducing obstacles shouldn't be denied because we can't remove all obstacles.

> "role" just doesn't make a very good verb :)

I don't think there is any requirement to chain verbs and nouns together to make scopes match sentence structure. We have roles called client-id:<client-id> that are intuitive, and do not contain verbs. Think of it as a compound noun instead. :)

Maybe it is best if we discuss as a team in the next team meeting. It might be easier to reach consensus if we discuss face-to-face.
(Reporter)

Comment 5

3 years ago
So a reason for not doing this is that assume:<x> does not necessarily mean you have the roles of role <x> - instead x is an expression which can match multiple roles.

For example:

Scope:
    assume:repo:github.com/taskcluster/*

would provides scopes defined in roles:
    repo:github.com/*
    repo:*

without there being a role called "repo:github.com/taskcluster/*".

In other words, "x" itself is not a role, but a string which is matched against roles, which can return zero or more.
Status: REOPENED → RESOLVED
Last Resolved: 3 years ago3 years ago
Resolution: --- → WONTFIX
You need to log in before you can comment on or make changes to this bug.