yahoo-eng-team team mailing list archive

[Dolph Mathews <1498556@xxxxxxxxxxxxxxxxxx>]

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