From 05c3a471ae22e019424740db260f9f9048d7536c Mon Sep 17 00:00:00 2001 From: Monty Taylor Date: Tue, 11 Jul 2017 16:26:03 -0500 Subject: [PATCH] Add paragraph clarifying major and micro versions People get confused with major version discovery vs. microversion usage. Try to make it very clear what's going on. Change-Id: I2be8670998f531ee4777876413979a63279a59ab --- doc/source/using-sessions.rst | 87 +++++++++++++++++++++++++++++++---- 1 file changed, 78 insertions(+), 9 deletions(-) diff --git a/doc/source/using-sessions.rst b/doc/source/using-sessions.rst index e3676930..c0f3a055 100644 --- a/doc/source/using-sessions.rst +++ b/doc/source/using-sessions.rst @@ -34,10 +34,10 @@ Features - Standard service and version discovery Clients are not expected to have any knowledge of an identity token or any - other form of identification credential. Service, endpoint and version - discovery are handled by the Session and plugins. Discovery information is - automatically cached in memory, so the user need not worry about excessive - use of discovery metadata. + other form of identification credential. Service, endpoint, major version + discovery and microversion support discovery are handled by the Session and + plugins. Discovery information is automatically cached in memory, so the user + need not worry about excessive use of discovery metadata. Sessions for Users @@ -109,6 +109,67 @@ authentication data and token formats. Clients should be able to specify filter parameters for selecting the endpoint and have the parsing of the catalog managed for them. +Major Version Discovery and Microversion Support +------------------------------------------------ + +In OpenStack the root URLs of available services are distributed to the user +in an object called the Service Catalog, which is part of the token they +receive. Clients are expected to use the URLs from the Service Catalog rather +than have them provided. The root URL of a given service is referred to as the +`endpoint` of the service. The URL of a specific version of a service is +referred to as a `versioned endpoint`. REST requests for a service are made +against a given `versioned endpoint`. + +The topic of Major API versions and microversions can be confusing. As +`keystoneauth` provides facilities for discovery of versioned endpoints +associated with a Major API Version and for fetching information about +the microversions that versioned endpoint supports, it is important to be aware +of the distinction between the two. + +Conceptually the most important thing to understand is that a Major API Version +describes the URL of a discrete versioned endpoint, while a given versioned +endpoint might have properties that express that it supports a range of +microversions. + +When a user wants to make a REST request against a service, the user expresses +the Major API version and the type of service so that the appropriate versioned +endpoint can be found and used. For example, a user might request +version 2 of the compute service from cloud.example.com and end up with a +versioned endpoint of ``https://compute.example.com/v2``. + +Each service provides a discovery document at the root of each versioned +endpoint that contains information about that versioned endpoint. Each service +also provides a document at the root of the unversioned endpoint that contains +a list of the discovery documents for all of the available versioned endpoints. +By examining these documents, it is possible to find the versioned endpoint +that corresponds with the user's desired Major API version. + +Each of those documents may also indicate that the given versioned endpoint +supports microversions by listing a minimum and maximum microversion that it +understands. As a result of having found the versioned endpoint for the +requested Major API version, the user will also know which microversions, +if any, may be used in requests to that versioned endpoint. + +When a client makes REST requests to the Major API version's endpoint, the +client can, optionally, on a request-by-request basis, include a header +specifying that the individual request use the behavior defined by the given +microversion. If a client does not request a microversion, the service will +behave as if the minimum supported microversion was specified. + +.. note: The changes that each microversion reflects are documented elsewhere + and are not information provided by the discovery process. + +The overall transaction then has three parts: + +* What is the endpoint for a given Major API version of a given service? +* What are the minimum and maximum microversions supported at that endpoint? +* Which one of that range of microversions, if any, does the user want to use + for a given request? + +`keystoneauth` provides facilities for discovering the endpoint for a given +Major API of a given service, as well as reporting the available microversion +ranges that endpoint supports, if any. + Authentication -------------- @@ -124,10 +185,6 @@ token, by default a token is included if an authentication plugin is available:: Service Discovery ----------------- -In OpenStack the URLs of available services are distributed to the user in an -object called the Service Catalog, which is part of the token they receive. -Clients are expected to use the URLs from the Service Catalog rather than have -them provided. In general a client does not need to know the full URL for the server that they are communicating with, simply that it should send a request to a path @@ -146,6 +203,11 @@ the request needs to be specified:: 'max_version': '3.4', 'discover_versions': False}) +.. note:: The min_version and max_version arguments in this example indicate + acceptable range for finding the endpoint for the given Major API + versions. They are in the endpoint_filter, they are not requesting + the call to ``/users`` be made at a specific microversion. + `endpoint_filter` accepts a number of arguments with which it can determine an endpoint url: @@ -166,7 +228,7 @@ region_name the name of the region where the endpoint resides. version - the minimum version, restricted to a given major API. For instance, a + the minimum version, restricted to a given Major API. For instance, a `version` of ``2.2`` will match ``2.2`` and ``2.3`` but not ``2.1`` or ``3.0``. Mutually exclusive with `min_version` and `max_version`. @@ -185,6 +247,9 @@ max_version will match ``2.2``, ``2.10``, ``3.0``, and ``3.3``, but not ``1.42``, ``2.1``, or ``3.20``. Mutually exclusive with `version`. +.. note:: version, min_version and max_version are all used to help determine + the endpoint for a given Major API version of a service. + discover_versions whether or not version discovery should be run, even if not strictly necessary. It is often possible to fulfill an endpoint request purely @@ -260,6 +325,10 @@ methods, but is "mounted" on the endpoint that would be found by version=1) response = adapter.get('/volumes') +As with ``endpoint_filter`` on a Session, the ``version``, ``min_version`` +and ``max_version`` parameters exist to help determine the appropriate +endpoint for a Major API of a service. + Endpoint Metadata -----------------