Add first draft of porting guide for 2.0
This commit is contained in:
Toshio Kuratomi
James Cammarata
parent
bf9f6ce09c
commit
4ad7135690
1 changed files with 160 additions and 0 deletions
160
docsite/rst/porting_guide_2.0.rst
Normal file
160
docsite/rst/porting_guide_2.0.rst
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
Porting Guide
|
||||
=============
|
||||
|
||||
|
||||
Playbook
|
||||
--------
|
||||
|
||||
* backslash escapes When specifying parameters in jinja2 expressions in YAML
|
||||
dicts, backslashes sometimes needed to be escaped twice. This has been fixed
|
||||
in 2.0.x so that escaping once works. The following example shows how
|
||||
playbooks must be modified::
|
||||
|
||||
# Syntax in 1.9.x
|
||||
- debug:
|
||||
msg: "{{ 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\\\2') }}"
|
||||
# Syntax in 2.0.x
|
||||
- debug:
|
||||
msg: "{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}"
|
||||
|
||||
# Output:
|
||||
"msg": "test1 1\\3"
|
||||
|
||||
To make an escaped string that will work on all versions you have two options::
|
||||
|
||||
- debug: msg="{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}"
|
||||
|
||||
uses key=value escaping which has not changed. The other option is to check for the ansible version::
|
||||
|
||||
"{{ (ansible_version|version_compare('ge', '2.0'))|ternary( 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') , 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\\\2') ) }}"
|
||||
|
||||
* trailing newline When a string with a trailing newline was specified in the
|
||||
playbook via yaml dict format, the trailing newline was stripped. When
|
||||
specified in key=value format, the trailing newlines were kept. In v2, both
|
||||
methods of specifying the string will keep the trailing newlines. If you
|
||||
relied on the trailing newline being stripped, you can change your playbook
|
||||
using the following as an example::
|
||||
|
||||
# Syntax in 1.9.x
|
||||
vars:
|
||||
message: >
|
||||
Testing
|
||||
some things
|
||||
tasks:
|
||||
- debug:
|
||||
msg: "{{ message }}"
|
||||
|
||||
# Syntax in 2.0.x
|
||||
vars:
|
||||
old_message: >
|
||||
Testing
|
||||
some things
|
||||
message: "{{ old_messsage[:-1] }}"
|
||||
- debug:
|
||||
msg: "{{ message }}"
|
||||
# Output
|
||||
"msg": "Testing some things"
|
||||
|
||||
* porting task includes
|
||||
* More dynamic. Corner-case formats that were not supposed to work now do not, as expected.
|
||||
* variables defined in the yaml dict format https://github.com/ansible/ansible/issues/13324
|
||||
* variable precedence
|
||||
* templating (variables in playbooks and template lookups) has improved with regard to keeping the original instead of turning everything into a string.
|
||||
If you need the old behavior, quote the value to pass it around as a string.
|
||||
Empty variables and variables set to null in yaml are no longer converted to empty strings. They will retain the value of `None`.
|
||||
You can override the `null_representation` setting to an empty string in your config file by setting the `ANSIBLE_NULL_REPRESENTATION` environment variable.
|
||||
* Extras callbacks must be whitelisted in ansible.cfg. Copying is no longer necessary but whitelisting in ansible.cfg must be completed.
|
||||
* dnf module has been rewritten. Some minor changes in behavior may be observed.
|
||||
* win_updates has been rewritten and works as expected now.
|
||||
|
||||
Deprecated
|
||||
----------
|
||||
|
||||
While all items listed here will show a deprecation warning message, they still work as they did in 1.9.x. Please note that they will be removed in 2.2 (Ansible always waits two major releases to remove a deprecated feature).
|
||||
|
||||
* Bare variables in with_ loops should instead use the “{{var}}” syntax, which helps eliminate ambiguity.
|
||||
* The ansible-galaxy text format requirements file. Users should use the YAML format for requirements instead.
|
||||
* Undefined variables within a with_ loop’s list currently do not interrupt the loop, but they do issue a warning; in the future, they will issue an error.
|
||||
* Using variables for task parameters is unsafe and will be removed in a future version. For example::
|
||||
|
||||
- hosts: localhost
|
||||
gather_facts: no
|
||||
vars:
|
||||
debug_params:
|
||||
msg: "hello there"
|
||||
tasks:
|
||||
- debug: "{{debug_params}}"
|
||||
|
||||
* Host patterns should use a comma (,) or colon (:) instead of a semicolon (;) to separate hosts/groups in the pattern.
|
||||
* Ranges specified in host patterns should use the [x:y] syntax, instead of [x-y].
|
||||
* Playbooks using privilege escalation should always use “become*” options rather than the old su*/sudo* options.
|
||||
* The “short form” for vars_prompt is no longer supported.
|
||||
For example::
|
||||
|
||||
vars_prompt:
|
||||
variable_name: "Prompt string"
|
||||
|
||||
* Specifying variables at the top level of a task include statement is no longer supported. For example::
|
||||
|
||||
- include: foo.yml
|
||||
a: 1
|
||||
|
||||
Should now be::
|
||||
|
||||
- include: foo.yml
|
||||
args:
|
||||
a: 1
|
||||
|
||||
* Setting any_errors_fatal on a task is no longer supported. This should be set at the play level only.
|
||||
* Bare variables in the `environment` dictionary (for plays/tasks/etc.) are no longer supported. Variables specified there should use the full variable syntax: ‘{{foo}}’.
|
||||
* Tags should no longer be specified with other parameters in a task include. Instead, they should be specified as an option on the task.
|
||||
For example::
|
||||
|
||||
- include: foo.yml tags=a,b,c
|
||||
|
||||
Should be::
|
||||
|
||||
- include: foo.yml
|
||||
tags: [a, b, c]
|
||||
|
||||
* The first_available_file option on tasks has been deprecated. Users should use the with_first_found option or lookup (‘first_found’, …) plugin.
|
||||
|
||||
|
||||
Porting plugins
|
||||
===============
|
||||
|
||||
In ansible-1.9.x, you would generally copy an existing plugin to create a new one. Simply implementing the methods and attributes that the caller of the plugin expected made it a plugin of that type. In ansible-2.0, most plugins are implemented by subclassing a base class for each plugin type. This way the custom plugin does not need to contain methods which are not customized.
|
||||
|
||||
.. note::
|
||||
|
||||
Lookup plugins
|
||||
--------------
|
||||
* lookup plugins ; import version
|
||||
|
||||
|
||||
Connection plugins
|
||||
------------------
|
||||
|
||||
* connection plugins
|
||||
|
||||
Action plugins
|
||||
--------------
|
||||
|
||||
* action plugins
|
||||
|
||||
Callback plugins
|
||||
----------------
|
||||
|
||||
* callback plugins
|
||||
|
||||
Connection plugins
|
||||
------------------
|
||||
|
||||
* connection plugins
|
||||
|
||||
|
||||
Porting custom scripts
|
||||
======================
|
||||
|
||||
Custom scripts that used the ``ansible.runner.Runner`` API in 1.x have to be ported in 2.x. Please refer to:
|
||||
https://github.com/ansible/ansible/blob/devel/docsite/rst/developing_api.rst
|
||||
Loading…
Reference in a new issue