Comment 1 for bug 1775094

New to keystone and started by creating a VM and running the guide here:

https://docs.openstack.org/devstack/latest/

Saw that keystone was operational and started using the openstack cli tool along with the V3 API page:

https://developer.openstack.org/api-ref/identity/v3/index.html

"Domains¶
A domain is a collection of users, groups, and projects. Each group and project is owned by exactly one domain.

Each domain defines a namespace where certain API-visible name attributes exist, which affects whether those names must be globally unique or unique within that domain. In the Identity API, the uniqueness of these attributes is as follows:

Domain name. Globally unique across all domains.
Role name. Unique within the owning domain.
User name. Unique within the owning domain.
Project name. Unique within the owning domain.
Group name. Unique within the owning domain."

It says Role name unique within a domain. Along with users, projects, and groups it makes sense that when a role is created using the --domain option that it exists within the domain, and can only interact with things from that domain as a full fledged rule. I created users specifying the domain option, and projects specifying the domain option, why not rules as well? When running the openstack cli tool and showing the output of role assignments, it would list the role when running:

openstack role assignment list --user newyorker --names

yet the role is absent when running:

openstack role assignment list --user newyorker --names --effective

I was using the 'effective' option to show which roles were actually in affect, as in, would allow a user to receive a domain or project scoped token. I didn't understand the difference between the two especially since the documentation around effective kept talking about groups and that did not match up with what I was experiencing since groups were not in use.

Through helpful chat mates, kmalloc and lbragstad, they explained what was happening along with the link to: https://specs.openstack.org/openstack/keystone-specs/specs/mitaka/domain-specific-roles.html

There are two different style guides going on between the specs subdomain and the developer subdomain. Not sure if that is intentional, but if I came across the spec in search results I would assume the spec may not be relevant or may be outdated. Nothing can beat the word current at the top of a web page with a change log history as the introduction.... Perhaps link the API call to the spec that created it? That way there is more reading material and less web searching, looking at people's out dated blogs, which I did manage to find that passage a couple of times.