After the long and contentious discussion about migration options,
Rodrigo and I have reached agreement about how we should handle them
that works for both of us, and I will share it here before Rodrigo
updates the spec. Discussion about the proposal can continue here on the
ML or in the spec, but the final decision will be made through the spec
approval process.
===============
The main assumptions that drive this conclusion are:
* The API design must not violate our agreed-upon versioning
(microversions) scheme as the API evolves over time.
* Actions requested by a client must result in behavior that is the same
across server versions. It's not okay to get "bonus" behaviors due to a
server upgrade if the client doesn't ask for them.
For the REST API, we propose that all the options are mandatory
booleans. There will be no defaults at the API level. Values of false
for options will always be compatible with the fallback/universal
migration strategy. The options will be:
* writable
* preserve-metadata
* non-disruptive
* preserve-snapshots
Omitting any one of these is an error. This ensures safety by making
clients send a value of true or false ensuring there are no surprise
downsides to performing a migration.
For future migration options, they will be added with a new microversion
and they will also be required options (in the new microversion). Newer
server versions will provide backwards compatibility by defaulting
options to false when clients invoke older microversions where that
option didn't exist.
For the pythonclient, we propose that options are mandatory on the CLI.
Again this provides safety by avoiding situations where users who don't
read the docs are surprised by the behavior they get. This ensures that
CLI scripts that invoke migrations will never break as long as the
client version remains the same, and that they will get consistent
behavior across all servers versions that support that client.
Updating to newer python clients may introduce new required parameters
though, which can break old scripts, so this will have the effect of
tying CLI scripts to specific client versions.
The client will provide backwards compatibility with older servers by
only allowing requests to be sent if the user specifies a value of false
for any option that doesn't exist on the server. This ensures that users
always get exactly what they ask for, or an error if what they asked for
can't be provided. It again avoids surprise behavior.
For the UI, options will always be specified as checkboxes, which will
default to checked (true).
===============
This proposal was arrived at after thinking through a long list of
hypothetical use cases involving newer and older clients and servers as
well as use of apps which import the client, usage of the client's CLI
interface, usage of the UI, and direct calls to the REST API without
using the client.
Also we specifically considered hypothetical future migration options
and how they would affect the API. I'm confident that this is as "safe"
as the API and CLIs can be, and the only downside I can see to this
approach is that it's more verbose than alternatives that include
implicit defaults.
-Ben Swartzlander
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
