ansible/docs/docsite/rst/python_3_support.rst

97 lines
3.9 KiB
ReStructuredText
Raw Normal View History

2016-10-26 00:12:52 +02:00
================
Python 3 Support
================
Ansible 2.2, 2.3, and 2.4 feature a tech preview of Python 3 support. This topic discusses how you can test to make sure your modules and playbooks work with Python 3.
2016-10-26 00:12:52 +02:00
.. note:: Ansible supports Python version 3.5 and above only.
2016-10-26 00:12:52 +02:00
.. note:: Technology preview features provide early access to upcoming product innovations,
enabling you to test functionality and provide feedback during the development process.
Please be aware that tech preview features may not be functionally complete and are not
intended for production use. To report a Python 3 bug, please see `Community Information & Contributing <http://docs.ansible.com/ansible/community.html#i-d-like-to-report-a-bug>`_.
Testing Python 3 with commands and playbooks
--------------------------------------------
2016-10-26 00:12:52 +02:00
* Run Ansible 2.2+ :ref:`from source <from_source>`
2016-10-26 00:12:52 +02:00
* To test Python 3 on the controller, run your ansible command via
2017-04-12 19:49:26 +02:00
``python3``. For example:
2016-10-26 00:12:52 +02:00
.. code-block:: shell
2016-10-26 00:12:52 +02:00
$ python3 /usr/bin/ansible localhost -m ping
$ python3 /usr/bin/ansible-playbook sample-playbook.yml
2016-10-26 00:12:52 +02:00
You can also install Ansible using :program:`pip` for Python3 which will make the default
:command:`/usr/bin/ansible` run with Python3:
.. code-block:: shell
$ virtualenv --python=python3 py3-ansible
$ source ./py3-ansible/bin/activate
$ pip3 install ansible
$ ansible --version | grep "python version"
python version = 3.6.2 (default, Sep 22 2017, 08:28:09) [GCC 7.2.1 20170915 (Red Hat 7.2.1-2)]
On systems with SELinux installed, such as Red Hat Enterprise Linux or Fedora, the SELinux Python libraries also need to be copied over.
.. code-block:: shell
$ cp -r -v /usr/lib64/python3.*/site-packages/selinux/ ./py3-ansible/lib64/python3.*/site-packages/
$ cp -v /usr/lib64/python3.*/site-packages/*selinux*.so ./py3-ansible/lib64/python3.*/site-packages/
.. note:: Individual Linux distribution packages may be packaged for Python2 or Python3. When running from
distro packages you'll only be able to use Ansible with the Python version for which it was
installed. Sometimes distros will provide a means of installing for several Python versions
(via a separate package or via some commands that are run after install). You'll need to check
with your distro to see if that applies in your case.
2016-10-26 00:12:52 +02:00
Testing Python 3 module support
--------------------------------
* Set the ansible_python_interpreter configuration option to
:command:`/usr/bin/python3`. The ``ansible_python_interpreter`` configuration option is
usually set per-host as an inventory variable associated with a host or group of hosts:
2016-10-26 00:12:52 +02:00
.. code-block:: ini
2016-10-26 00:12:52 +02:00
# Example inventory that makes an alias for localhost that uses python3
[py3-hosts]
localhost-py3 ansible_host=localhost ansible_connection=local
2016-10-26 00:12:52 +02:00
[py3-hosts:vars]
ansible_python_interpreter=/usr/bin/python3
2016-10-26 00:12:52 +02:00
See the :ref:`inventory documentation <inventory>` for more information.
* Run your command or playbook:
.. code-block:: shell
$ ansible localhost-py3 -m ping
$ ansible-playbook sample-playbook.yml
Note that you can also use the :option:`-e` command line option to manually
set the python interpreter when you run a command. For example:
.. code-block:: shell
$ ansible localhost -m ping -e 'ansible_python_interpreter=/usr/bin/python3'
$ ansible-playbook sample-playbook.yml -e 'ansible_python_interpreter=/usr/bin/python3'
What to do if an incompatibility is found
-----------------------------------------
If you find a bug while testing modules with Python3 you can submit a bug
2017-04-04 20:40:41 +02:00
report on `Ansible's GitHub project
2017-04-12 19:49:26 +02:00
<https://github.com/ansible/ansible/issues/>`_. Be sure to mention Python3 in
the bug report so that the right people look at it.
If you would like to fix the code and submit a pull request on github, you can
refer to :doc:`dev_guide/developing_python3` for information on how we fix
common Python3 compatibility issues in the Ansible codebase.