Versioning of tower-cli¶
Tower-CLI is a command-line interface and python library to interact with Ansible Tower and AWX. Only versions of tower-cli can successfully interact with only a certain subset of versions of Ansible Tower or AWX, and this document is meant to outline the policy.
API Versions¶
Ansible Tower and AWX communicate with clients through a particular API version, so that each version forms a stable API for Ansible Tower. Each version of tower-cli also has a corresponding API version.
Supported Versions with Ansible Tower¶
The following table summarizes the policy of supported versions.
| tower-cli | API version | Tower version |
|---|---|---|
| 3.1.x | v1 | 3.2.x and earlier |
| current | v2 | 3.2.x and later |
This means that the release series 3.1.x is still open for fixes in order to support communication with the v1 API and all Tower versions that support that. Many elements of functionality are removed in the transition to v2, so they are no longer carried with the current tower-cli version.
Policy with AWX Versions¶
Compatibility between tower-cli and the AWX project is only considered for the most recent development version of tower-cli and most recent version of AWX.
API Version Upgrade Guide¶
If you upgrade tower-cli across an API version change, existing scripts will be broken.
This section highlights the most major backward-incompatible changes that need to be taken into account in order to migrate your scripts.
API v1->v2¶
In API v2, credentials have a new related model “credential_type”. This enables custom credential types, and that old types now need to reference the build-in credential types instead of the old flat-text kind field.
Additionally, to allow fully arbitrary credential types, the fields used by the credential in creating the necessary runtime environment are now nested inside of a dictionary called inputs.
old:
$ tower-cli credential create --name="AWS creds" --team=Ops --kind=aws --username=your_username --password=password
new:
$ tower-cli credential create --name="AWS creds" --team=Ops --credential-type="Amazon Web Services" --inputs='{"username": "your_username", "password": "password"}'
When attaching credentials to job templates, the related link structure has changed.
- API v1 options:
- –machine-credential
- –cloud-credential
- –network-credential
- API v2 options:
- –credential
- –vault-credential
- Related many-to-many extra_credentials
In order to add “extra” credentials (what used to be cloud credential), use the association method, tower-cli job_template associate_credential ….
In API v2, only “manual” groups can be created directly. The parameters that used to be provided to a group to sync to a cloud source now must be directly given to its inventory source.
old:
$ tower-cli group create --name=EC2 --credential="AWS creds" --source=ec2 --description="EC2 hosts" --inventory=Production
new:
$ tower-cli inventory_source create --name=EC2 --credential="AWS creds" --source=ec2 --description="EC2 hosts" --inventory=Production
To run an inventory update, use the tower-cli inventory_source update command.
Version-specific Secondary Install¶
In order to use different versions of tower-cli simultaneously in order to interact with different servers hosting different API versions, you can use this tool packaged in the source code.
For example:
$ make install_v1
This will install a new CLI entry point, tower-cli-v1, which will behave the same as tower-cli. However, this installation will persist even after upgrading the main program. This also provides the python package tower_cli_v1.
Important note: the configuration file is also separate from the secondary install, so you must re-enter your URL and credentials.
If you want to be sure that you re-install tower-cli-v1, you can do:
$ make v1-refresh
The v1 install is only possible with the v1 branch in the source tree. The master branch currently tracks API v2, and the prior instructions will work for a v2 secondary install, replacing v1 with v2.