Public bug reported:
There are 3 primary places where client can be configured to reference
domains. The actual parameter names vary based on the configuration
interface (a function's arguments, the env, CLI arguments, etc), but
I'll use environment variables here for the sake of general familiarity:
1. OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME: Used for specifying the
domain which owns the authenticating user.
2. OS_PROJECT_DOMAIN_ID and OS_PROJECT_DOMAIN_NAME: Used for specifying
the domain which owns the desired project scope.
3. OS_DOMAIN_ID and OS_DOMAIN_NAME: Used for specifying the desired
domain scope.
On the service side, a "default domain" is created which, by default,
looks like:
id="default"
name="Default"
The default domain is exclusively used on the service-side for scoping
v2 operations, which are not domain-aware, in the broader multi-domain
namespace exposed by v3. The default domain's ID is mutable via
configuration (CONF.identity.default_domain_id) and the domain name is
mutable via the API (PATCH /v3/domains/default, for example). Generally,
deployers should not have any reason to change the default domain ID
from it's default value of "default".
Both (1) and (2) refer to domains that provide context to other
configuration options. In single domain deployments, or deployments
wherein most users and projects exist in the "default domain", it would
benefit the user experience to assume that the user's and project exist
in the default domain. Specifically, this means that users have fewer
(if any) additional configuration options to set when migrating from v2
to v3, easing adoption of v3 overall. Deployments that opt into more
complex multi-domain arrangement are thus opting into consuming more
complex configuration options on the client side (they must specify
their non-default domains explicitly).
On (3), these values should always default to null values, and no
assumptions should ever be made about their values. If a non-null
default were to be set, then that means that the client should always
try to obtain a domain-scoped token which is almost never the intended
behavior.
There are three approaches to implementing this behavior. Two of them
are obvious at a high level, but easily fragile.
If OS_USER_DOMAIN_ID defaults to "default" to match the default
CONF.identity.default_domain_id value, then whenever the user sets a
OS_USER_DOMAIN_NAME, the OS_USER_DOMAIN_ID *must* be ignored in favor of
using the specified domain name. This is a potentially unreliable
behavior, as domain IDs are immutable and are thus more preferable as
reliable references.
If OS_USER_DOMAIN_NAME defaults to "Default" to match the default domain
name value, then whenever the user sets a OS_USER_DOMAIN_ID, the
OS_USER_DOMAIN_NAME *must* be ignored in favor of using the specified
domain ID. This is a potentially unreliable behavior, as assuming that
the default domain still has a default domain name of "Default" is
fragile considering that it's mutable through the regular HTTP API (a
deployer will inevitably change it, thus breaking the client's default
behavior). This approach is fragile.
The third option is a combination of the above two approaches, and must
happen at the "last minute" before requests are issued to keystone
(after all possible sources of configuration have been handled). That
is, both OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME default to null
values on the surface. When an actual HTTP request is built, normal
configuration precedence takes place (for example, in a CLI client):
1) If an --os-user-domain-id is specified, then that is used, ignoring
--os-user-domain-name, OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME. This
is the most specific, reliable configuration option available. A warning
could be issued about the ignored values being discarded to communicate
this sequence of precedence.
2) If an --os-user-domain-name is specified, then that is used, ignoring
OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME.
3) If an OS_USER_DOMAIN_ID, then that is used, ignoring
OS_USER_DOMAIN_NAME.
4) If an OS_USER_DOMAIN_NAME, then that is used.
5) Else, assume the domain id="default".
Everything above referencing a OS_USER_DOMAIN_ID + OS_USER_DOMAIN_NAME
applies equally to OS_PROJECT_DOMAIN_ID + OS_PROJECT_DOMAIN_NAME.
Note: a domain ID never needs to be specified in the same request as a
domain name. Both are absolute references that cannot be confused due to
namespace conflicts; the only difference between them is that domain IDs
are system-defined + immutable and domain names are user-defined +
mutable.
And again, the server should never, ever assume domain IDs anywhere for
any reason outside of v2 controllers assuming
CONF.identity.default_domain_id as the explicit scope. v3 should never
make any assumptions about domains: explicit is better than implicit
here.
** Affects: keystone
Importance: Medium
Status: Triaged
** Affects: keystoneauth
Importance: Medium
Status: Triaged
** Affects: keystonemiddleware
Importance: Medium
Status: Triaged
** Affects: python-keystoneclient
Importance: Medium
Status: Triaged
** Affects: python-openstackclient
Importance: Undecided
Status: New
** Affects: python-openstacksdk
Importance: Undecided
Status: New
** Tags: user-experience
** Also affects: keystoneauth
Importance: Undecided
Status: New
** Also affects: python-keystoneclient
Importance: Undecided
Status: New
** Also affects: python-openstackclient
Importance: Undecided
Status: New
** Also affects: keystonemiddleware
Importance: Undecided
Status: New
** Also affects: python-openstacksdk
Importance: Undecided
Status: New
** Changed in: keystoneauth
Status: New => Triaged
** Changed in: keystoneauth
Importance: Undecided => Medium
** Changed in: keystonemiddleware
Status: New => Triaged
** Changed in: keystonemiddleware
Importance: Undecided => Medium
** Changed in: python-keystoneclient
Status: New => Triaged
** Changed in: python-keystoneclient
Importance: Undecided => Medium
** Description changed:
There are 3 primary places where client can be configured to reference
- domains. The actual parameter names vary baed on the configuration
+ domains. The actual parameter names vary based on the configuration
interface (a function's arguments, the env, CLI arguments, etc), but
I'll use environment variables here for the sake of general familiarity:
1. OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME: Used for specifying the
domain which owns the authenticating user.
2. OS_PROJECT_DOMAIN_ID and OS_PROJECT_DOMAIN_NAME: Used for specifying
the domain which owns the desired project scope.
3. OS_DOMAIN_ID and OS_DOMAIN_NAME: Used for specifying the desired
domain scope.
On the service side, a "default domain" is created which, by default,
looks like:
- id="default"
+ id="default"
- name="Default"
+ name="Default"
The default domain is exclusively used on the service-side for scoping
v2 operations, which are not domain-aware, in the broader multi-domain
namespace exposed by v3. The default domain's ID is mutable via
configuration (CONF.identity.default_domain_id) and the domain name is
mutable via the API (PATCH /v3/domains/default, for example). Generally,
deployers should not have any reason to change the default domain ID
from it's default value of "default".
Both (1) and (2) refer to domains that provide context to other
configuration options. In single domain deployments, or deployments
wherein most users and projects exist in the "default domain", it would
benefit the user experience to assume that the user's and project exist
in the default domain. Specifically, this means that users have fewer
(if any) additional configuration options to set when migrating from v2
to v3, easing adoption of v3 overall. Deployments that opt into more
complex multi-domain arrangement are thus opting into consuming more
complex configuration options on the client side (they must specify
their non-default domains explicitly).
On (3), these values should always default to null values, and no
assumptions should ever be made about their values. If a non-null
default were to be set, then that means that the client should always
try to obtain a domain-scoped token which is almost never the intended
behavior.
There are three approaches to implementing this behavior. Two of them
are obvious at a high level, but easily fragile.
If OS_USER_DOMAIN_ID defaults to "default" to match the default
CONF.identity.default_domain_id value, then whenever the user sets a
OS_USER_DOMAIN_NAME, the OS_USER_DOMAIN_ID *must* be ignored in favor of
using the specified domain name. This is a potentially unreliable
behavior, as domain IDs are immutable and are thus more preferable as
reliable references.
If OS_USER_DOMAIN_NAME defaults to "Default" to match the default domain
name value, then whenever the user sets a OS_USER_DOMAIN_ID, the
OS_USER_DOMAIN_NAME *must* be ignored in favor of using the specified
domain ID. This is a potentially unreliable behavior, as assuming that
the default domain still has a default domain name of "Default" is
fragile considering that it's mutable through the regular HTTP API (a
deployer will inevitably change it, thus breaking the client's default
behavior). This approach is fragile.
The third option is a combination of the above two approaches, and must
happen at the "last minute" before requests are issued to keystone
(after all possible sources of configuration have been handled). That
is, both OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME default to null
values on the surface. When an actual HTTP request is built, normal
configuration precedence takes place (for example, in a CLI client):
1) If an --os-user-domain-id is specified, then that is used, ignoring
--os-user-domain-name, OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME. This
is the most specific, reliable configuration option available. A warning
could be issued about the ignored values being discarded to communicate
this sequence of precedence.
2) If an --os-user-domain-name is specified, then that is used, ignoring
OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME.
3) If an OS_USER_DOMAIN_ID, then that is used, ignoring
OS_USER_DOMAIN_NAME.
4) If an OS_USER_DOMAIN_NAME, then that is used.
5) Else, assume the domain id="default".
Note: a domain ID never needs to be specified in the same request as a
domain name. Both are absolute references that cannot be confused due to
namespace conflicts; the only difference between them is that domain IDs
are system-defined + immutable and domain names are user-defined +
mutable.
And again, the server should never, ever assume domain IDs anywhere for
any reason outside of v2 controllers assuming
CONF.identity.default_domain_id as the explicit scope. v3 should never
make any assumptions about domains: explicit is better than implicit
here.
** Description changed:
There are 3 primary places where client can be configured to reference
domains. The actual parameter names vary based on the configuration
interface (a function's arguments, the env, CLI arguments, etc), but
I'll use environment variables here for the sake of general familiarity:
1. OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME: Used for specifying the
domain which owns the authenticating user.
2. OS_PROJECT_DOMAIN_ID and OS_PROJECT_DOMAIN_NAME: Used for specifying
the domain which owns the desired project scope.
3. OS_DOMAIN_ID and OS_DOMAIN_NAME: Used for specifying the desired
domain scope.
On the service side, a "default domain" is created which, by default,
looks like:
id="default"
name="Default"
The default domain is exclusively used on the service-side for scoping
v2 operations, which are not domain-aware, in the broader multi-domain
namespace exposed by v3. The default domain's ID is mutable via
configuration (CONF.identity.default_domain_id) and the domain name is
mutable via the API (PATCH /v3/domains/default, for example). Generally,
deployers should not have any reason to change the default domain ID
from it's default value of "default".
Both (1) and (2) refer to domains that provide context to other
configuration options. In single domain deployments, or deployments
wherein most users and projects exist in the "default domain", it would
benefit the user experience to assume that the user's and project exist
in the default domain. Specifically, this means that users have fewer
(if any) additional configuration options to set when migrating from v2
to v3, easing adoption of v3 overall. Deployments that opt into more
complex multi-domain arrangement are thus opting into consuming more
complex configuration options on the client side (they must specify
their non-default domains explicitly).
On (3), these values should always default to null values, and no
assumptions should ever be made about their values. If a non-null
default were to be set, then that means that the client should always
try to obtain a domain-scoped token which is almost never the intended
behavior.
There are three approaches to implementing this behavior. Two of them
are obvious at a high level, but easily fragile.
If OS_USER_DOMAIN_ID defaults to "default" to match the default
CONF.identity.default_domain_id value, then whenever the user sets a
OS_USER_DOMAIN_NAME, the OS_USER_DOMAIN_ID *must* be ignored in favor of
using the specified domain name. This is a potentially unreliable
behavior, as domain IDs are immutable and are thus more preferable as
reliable references.
If OS_USER_DOMAIN_NAME defaults to "Default" to match the default domain
name value, then whenever the user sets a OS_USER_DOMAIN_ID, the
OS_USER_DOMAIN_NAME *must* be ignored in favor of using the specified
domain ID. This is a potentially unreliable behavior, as assuming that
the default domain still has a default domain name of "Default" is
fragile considering that it's mutable through the regular HTTP API (a
deployer will inevitably change it, thus breaking the client's default
behavior). This approach is fragile.
The third option is a combination of the above two approaches, and must
happen at the "last minute" before requests are issued to keystone
(after all possible sources of configuration have been handled). That
is, both OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME default to null
values on the surface. When an actual HTTP request is built, normal
configuration precedence takes place (for example, in a CLI client):
1) If an --os-user-domain-id is specified, then that is used, ignoring
--os-user-domain-name, OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME. This
is the most specific, reliable configuration option available. A warning
could be issued about the ignored values being discarded to communicate
this sequence of precedence.
2) If an --os-user-domain-name is specified, then that is used, ignoring
OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME.
3) If an OS_USER_DOMAIN_ID, then that is used, ignoring
OS_USER_DOMAIN_NAME.
4) If an OS_USER_DOMAIN_NAME, then that is used.
5) Else, assume the domain id="default".
+ Everything above referencing a OS_USER_DOMAIN_ID + OS_USER_DOMAIN_NAME
+ applies equally to OS_PROJECT_DOMAIN_ID + OS_PROJECT_DOMAIN_NAME.
+
Note: a domain ID never needs to be specified in the same request as a
domain name. Both are absolute references that cannot be confused due to
namespace conflicts; the only difference between them is that domain IDs
are system-defined + immutable and domain names are user-defined +
mutable.
And again, the server should never, ever assume domain IDs anywhere for
any reason outside of v2 controllers assuming
CONF.identity.default_domain_id as the explicit scope. v3 should never
make any assumptions about domains: explicit is better than implicit
here.
--
You received this bug notification because you are a member of Yahoo!
Engineering Team, which is subscribed to Keystone.
https://bugs.launchpad.net/bugs/1498556
Title:
Reasonable assumptions concerning domain references
Status in Keystone:
Triaged
Status in keystoneauth:
Triaged
Status in keystonemiddleware:
Triaged
Status in python-keystoneclient:
Triaged
Status in python-openstackclient:
New
Status in OpenStack SDK:
New
Bug description:
There are 3 primary places where client can be configured to reference
domains. The actual parameter names vary based on the configuration
interface (a function's arguments, the env, CLI arguments, etc), but
I'll use environment variables here for the sake of general
familiarity:
1. OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME: Used for specifying the
domain which owns the authenticating user.
2. OS_PROJECT_DOMAIN_ID and OS_PROJECT_DOMAIN_NAME: Used for
specifying the domain which owns the desired project scope.
3. OS_DOMAIN_ID and OS_DOMAIN_NAME: Used for specifying the desired
domain scope.
On the service side, a "default domain" is created which, by default,
looks like:
id="default"
name="Default"
The default domain is exclusively used on the service-side for scoping
v2 operations, which are not domain-aware, in the broader multi-domain
namespace exposed by v3. The default domain's ID is mutable via
configuration (CONF.identity.default_domain_id) and the domain name is
mutable via the API (PATCH /v3/domains/default, for example).
Generally, deployers should not have any reason to change the default
domain ID from it's default value of "default".
Both (1) and (2) refer to domains that provide context to other
configuration options. In single domain deployments, or deployments
wherein most users and projects exist in the "default domain", it
would benefit the user experience to assume that the user's and
project exist in the default domain. Specifically, this means that
users have fewer (if any) additional configuration options to set when
migrating from v2 to v3, easing adoption of v3 overall. Deployments
that opt into more complex multi-domain arrangement are thus opting
into consuming more complex configuration options on the client side
(they must specify their non-default domains explicitly).
On (3), these values should always default to null values, and no
assumptions should ever be made about their values. If a non-null
default were to be set, then that means that the client should always
try to obtain a domain-scoped token which is almost never the intended
behavior.
There are three approaches to implementing this behavior. Two of them
are obvious at a high level, but easily fragile.
If OS_USER_DOMAIN_ID defaults to "default" to match the default
CONF.identity.default_domain_id value, then whenever the user sets a
OS_USER_DOMAIN_NAME, the OS_USER_DOMAIN_ID *must* be ignored in favor
of using the specified domain name. This is a potentially unreliable
behavior, as domain IDs are immutable and are thus more preferable as
reliable references.
If OS_USER_DOMAIN_NAME defaults to "Default" to match the default
domain name value, then whenever the user sets a OS_USER_DOMAIN_ID,
the OS_USER_DOMAIN_NAME *must* be ignored in favor of using the
specified domain ID. This is a potentially unreliable behavior, as
assuming that the default domain still has a default domain name of
"Default" is fragile considering that it's mutable through the regular
HTTP API (a deployer will inevitably change it, thus breaking the
client's default behavior). This approach is fragile.
The third option is a combination of the above two approaches, and
must happen at the "last minute" before requests are issued to
keystone (after all possible sources of configuration have been
handled). That is, both OS_USER_DOMAIN_ID and OS_USER_DOMAIN_NAME
default to null values on the surface. When an actual HTTP request is
built, normal configuration precedence takes place (for example, in a
CLI client):
1) If an --os-user-domain-id is specified, then that is used, ignoring
--os-user-domain-name, OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME.
This is the most specific, reliable configuration option available. A
warning could be issued about the ignored values being discarded to
communicate this sequence of precedence.
2) If an --os-user-domain-name is specified, then that is used,
ignoring OS_USER_DOMAIN_ID, and OS_USER_DOMAIN_NAME.
3) If an OS_USER_DOMAIN_ID, then that is used, ignoring
OS_USER_DOMAIN_NAME.
4) If an OS_USER_DOMAIN_NAME, then that is used.
5) Else, assume the domain id="default".
Everything above referencing a OS_USER_DOMAIN_ID + OS_USER_DOMAIN_NAME
applies equally to OS_PROJECT_DOMAIN_ID + OS_PROJECT_DOMAIN_NAME.
Note: a domain ID never needs to be specified in the same request as a
domain name. Both are absolute references that cannot be confused due
to namespace conflicts; the only difference between them is that
domain IDs are system-defined + immutable and domain names are user-
defined + mutable.
And again, the server should never, ever assume domain IDs anywhere
for any reason outside of v2 controllers assuming
CONF.identity.default_domain_id as the explicit scope. v3 should never
make any assumptions about domains: explicit is better than implicit
here.
To manage notifications about this bug go to:
https://bugs.launchpad.net/keystone/+bug/1498556/+subscriptions
--
Mailing list: https://launchpad.net/~yahoo-eng-team
Post to : yahoo-eng-team@lists.launchpad.net
Unsubscribe : https://launchpad.net/~yahoo-eng-team
More help : https://help.launchpad.net/ListHelp
