Change CLI default API version to latest known ironic API version¶
When using ironic CLI or the OpenStack CLI (OSC), ironic API version 1.9 is used by default. This spec proposes raising the default ironic API version used in both CLIs to the latest compatible API version.
Currently, ironic CLI and the baremetal OSC plugin default to using an API version that dates to the Liberty release. 
This means that any new user using the CLI who doesn’t specify the version can only use features that are almost 2 years old as of the time of this writing. This limits discoverability and usability of new features.
Also, if we ever bump up the minimum supported API version in the API, we will have to deal with raising the minimum CLI version anyway.
For the Pike cycle, a warning message will be printed when a user runs either CLI without specifying the version, indicating that the CLI will soon default to using the latest compatible API version. The proposed wording for the OSC plugin is as follows:
You are using the default API version of the OpenStack CLI baremetal (ironic) plugin. This is currently API version 1.9. In the future, the default will be the latest API version understood by both API and CLI. You can preserve the current behavior by passing the –os-baremetal-api-version argument with the desired version or using the OS_BAREMETAL_API_VERSION environment variable.
A similar wording will be used for the
You are using the default API version of the
ironicCLI tool. This is currently API version 1.9. In the future, the default will be the latest API version understood by both API and CLI. You can preserve the current behavior by passing the –ironic-api-version argument with the desired version or using the IRONIC_API_VERSION environment variable.
If the user wishes to continue using API version 1.9, they should specify so on the command line.
During the Queens cycle, the default API version used by the CLI will change to the latest version of the API compatible with the CLI. If only the major version is specified (for example,
--os-baremetal-api-version=1), the latest compatible version of that major version will be used (e.g. 1.32 if that’s the latest 1.XX version).
The latest compatible version will be determined via version negotiation between the CLI and ironic. The CLI will first make a request to the root endpoint of the ironic API, which returns the version of the ironic API.  If the ironic API version is lower than the maximum version the client is compatible with, the CLI will use the version running on the API service to ensure compatibility. Otherwise, the maximum ironic API version that can be handled by the client will be used.
We may deprecate the
ironictool in the Queens cycle. If this happens, we may decide to skip applying this change to this tool, and proceed with the deprecation instead. This is subject to a separate spec.
Changes to the client library are out of scope for this spec.
This change was discussed in detail at the Pike PTG. 
We could periodically bump the default API version used by the CLI. This has the disadvantage of being unpredictable from a user standpoint and doesn’t solve the discoverability issue for the latest features. It’s also not ideal for maintainability of the CLI codebase.
We could keep the default as 1.9 and always log a warning, without ever changing the default to the latest version. This doesn’t solve the ease of use or discoverability issues, and it permanently adds an extra annoyance to users who don’t wish to specify a version every time the CLI is invoked.
We could just pass
latestto the API when no version is provided. However, this approach would lead to potentially broken behavior if we ever land a breaking change to our API.
Data model impact¶
State Machine Impact¶
REST API impact¶
Client (CLI) impact¶
A warning will be logged when ironic CLI is invoked without specifying
--ironic-api-version, indicating that the default will soon be the latest
compatible API version.
After the deprecation period, the default will be changed accordingly, assuming that ironic CLI itself is not deprecated beforehand.
“openstack baremetal” CLI¶
A warning will be logged when the OSC baremetal plugin is invoked without
--os-baremetal-api-version, indicating that the default will
soon be the latest compatible API version.
After the deprecation period, the default will be changed accordingly.
RPC API impact¶
Driver API impact¶
Nova driver impact¶
Other end user impact¶
Other deployer impact¶
- Primary assignee:
- Other contributors:
Add the warning message
After the standard deprecation period (release boundary or 3 months, whichever is longer), change the default API version used by the CLI.
Appropriate unit and functional testing will be added.
Upgrades and Backwards Compatibility¶
If a user has scripts or tooling that use the CLI without specifying the version, those will need to be updated to specify the version.
None. Appropriate release notes will be added.