mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-05-08 06:12:51 +00:00
Update info on python support (#38855)
* Update the documentation to list Python 3 as official
* Add some reference targets for inventory variables so we can link to docs
* Add a platform FAQ section
Populate it with
* virtualenv info (previously on the python3 support page)
* BSD (Link to the working with BSD page)
* Solaris (Document how to work around the non-POSIX shell on some
Solaris hosts)
Fixes #21594
* Fix some refs in the release_and_maintenance document
* Fix unindent error in module template
Fix for the module/plugin template unintentionally unindented inside of
a raw block, leading to errors like:
ERROR: docs/docsite/rst/modules/redshift_facts_module.rst:289:0: Explicit markup ends without a blank line; unexpected unindent.
* Make wording for Solaris troubleshooting better.
This commit is contained in:
Toshio Kuratomi
GitHub
@@ -105,26 +105,104 @@ and run Ansible from there.
|
||||
|
||||
.. _python_interpreters:
|
||||
|
||||
How do I handle python pathing not having a Python 2.X in /usr/bin/python on a remote machine?
|
||||
How do I handle python not having a Python interpreter at /usr/bin/python on a remote machine?
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
While you can write ansible modules in any language, most ansible modules are written in Python, and some of these
|
||||
are important core ones.
|
||||
While you can write Ansible modules in any language, most Ansible modules are written in Python,
|
||||
including the ones central to letting Ansible work.
|
||||
|
||||
By default, Ansible assumes it can find a /usr/bin/python on your remote system that is a 2.X version of Python, specifically
|
||||
2.6 or higher.
|
||||
By default, Ansible assumes it can find a :command:`/usr/bin/python` on your remote system that is
|
||||
either Python2, version 2.6 or higher or Python3, 3.5 or higher.
|
||||
|
||||
Setting the inventory variable 'ansible_python_interpreter' on any host will allow Ansible to auto-replace the interpreter
|
||||
used when executing python modules. Thus, you can point to any python you want on the system if /usr/bin/python on your
|
||||
system does not point to a Python 2.X interpreter.
|
||||
Setting the inventory variable ``ansible_python_interpreter`` on any host will tell Ansible to
|
||||
auto-replace the Python interpreter with that value instead. Thus, you can point to any Python you
|
||||
want on the system if :command:`/usr/bin/python` on your system does not point to a compatible
|
||||
Python interpreter.
|
||||
|
||||
Some Linux operating systems, such as Arch, may only have Python 3 installed by default. This is not sufficient and you will
|
||||
get syntax errors trying to run modules with Python 3. Python 3 is essentially not the same language as Python 2. Python 3
|
||||
support is being worked on but some Ansible modules are not yet ported to run under Python 3.0. This is not a problem though
|
||||
as you can just install Python 2 also on a managed host.
|
||||
Some platforms may only have Python 3 installed by default. If it is not installed as
|
||||
:command:`/usr/bin/python`, you will need to configure the path to the interpreter via
|
||||
``ansible_python_interpreter``. Although most core modules will work with Python 3, there may be some
|
||||
special purpose ones which do not or you may encounter a bug in an edge case. As a temporary
|
||||
workaround you can install Python 2 on the managed host and configure Ansible to use that Python via
|
||||
``ansible_python_interpreter``. If there's no mention in the module's documentation that the module
|
||||
requires Python 2, you can also report a bug on our `bug tracker
|
||||
<https://github.com/ansible/ansible/issues>`_ so that the incompatibility can be fixed in a future release.
|
||||
|
||||
Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time.
|
||||
|
||||
Common Platform Issues
|
||||
++++++++++++++++++++++
|
||||
|
||||
Running in a virtualenv
|
||||
-----------------------
|
||||
|
||||
You can install Ansible into a virtualenv on the controller quite simply:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ virtualenv ansible
|
||||
$ source ./ansible/bin/activate
|
||||
$ pip install ansible
|
||||
|
||||
If you want to run under Python 3 instead of Python 2 you may want to change that slightly:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ virtualenv ansible
|
||||
$ source ./ansible/bin/activate
|
||||
$ pip3 install ansible
|
||||
|
||||
If you need to use any libraries which are not available via pip (for instance, SELinux Python
|
||||
bindings on systems such as Red Hat Enterprise Linux or Fedora that have SELinux enabled) then you
|
||||
need to install them into the virtualenv. There are two methods:
|
||||
|
||||
* When you create the virtualenv, specify ``--system-site-packages`` to make use of any libraries
|
||||
installed in the system's Python:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ virtualenv ansible --system-site-packages
|
||||
|
||||
* Copy those files in manually from the system. For instance, for SELinux bindings you might do:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ virtualenv ansible --system-site-packages
|
||||
$ 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/
|
||||
|
||||
|
||||
Running on BSD
|
||||
--------------
|
||||
|
||||
.. seealso:: :ref:`working_with_bsd`
|
||||
|
||||
|
||||
Running on Solaris
|
||||
------------------
|
||||
|
||||
By default, Solaris 10 and earlier run a non-POSIX shell which does not correctly expand the default
|
||||
tmp directory Ansible uses ( :file:`~/.ansible/tmp`). If you see module failures on Solaris machines, this
|
||||
is likely the problem. There are several workarounds:
|
||||
|
||||
* You can set :ref:`remote_tmp` to a path that will expand correctly with the Solaris shell. For
|
||||
example, in the ansible config file you can set::
|
||||
|
||||
remote_tmp=$HOME/.ansible/tmp
|
||||
|
||||
In Ansible 2.5 and later, you can also set it per-host like this::
|
||||
|
||||
solaris1 ansible_remote_tmp=$HOME/.ansible/tmp
|
||||
|
||||
* You can set :ref:`ansible_shell_executable` to the path to a POSIX compatible shell. For
|
||||
instance, many Solaris hosts have a POSIX shell located at :file:`/usr/xpg4/bin/sh` so you can set
|
||||
this in inventory like so::
|
||||
|
||||
solaris1 ansible_shell_executable=/usr/xpg4/bin/sh
|
||||
|
||||
(bash, ksh, and zsh should also be POSIX compatible if you have any of those installed).
|
||||
|
||||
|
||||
.. _use_roles:
|
||||
|
||||
What is the best way to make content reusable/redistributable?
|
||||
|
||||
@@ -2,45 +2,32 @@
|
||||
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.
|
||||
Ansible 2.5 and above have support for Python 3. Previous to 2.5, the Python 3 support was
|
||||
considered a tech preview. This topic discusses how to setup your controller and managed machines
|
||||
to use Python 3.
|
||||
|
||||
.. note:: Ansible supports Python version 3.5 and above only.
|
||||
|
||||
On the controller side
|
||||
----------------------
|
||||
|
||||
.. 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
|
||||
--------------------------------------------
|
||||
|
||||
* Run Ansible 2.2+ - See :ref:`from_source`
|
||||
* To test Python 3 on the controller, run your ansible command via
|
||||
``python3``. For example:
|
||||
The easiest way to run :command:`/usr/bin/ansible` under Python 3 is to install it with the Python3
|
||||
version of pip. This will make the default :command:`/usr/bin/ansible` run with Python3:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ python3 /usr/bin/ansible localhost -m ping
|
||||
$ python3 /usr/bin/ansible-playbook sample-playbook.yml
|
||||
|
||||
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.
|
||||
If you are running Ansible :ref:`from_source` and want to use Python 3 with your source checkout, run your
|
||||
command via ``python3``. For example:
|
||||
|
||||
.. 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/
|
||||
$ source ./hacking/env-setup
|
||||
$ python3 $(which ansible) localhost -m ping
|
||||
$ python3 $(which ansible-playbook) sample-playbook.yml
|
||||
|
||||
.. 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
|
||||
@@ -49,23 +36,27 @@ On systems with SELinux installed, such as Red Hat Enterprise Linux or Fedora, t
|
||||
with your distro to see if that applies in your case.
|
||||
|
||||
|
||||
Testing Python 3 module support
|
||||
--------------------------------
|
||||
Using Python 3 on the managed machines with commands and playbooks
|
||||
------------------------------------------------------------------
|
||||
|
||||
* 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:
|
||||
* Set the ``ansible_python_interpreter`` configuration option to :command:`/usr/bin/python3`. The
|
||||
``ansible_python_interpreter`` configuration option is usually set as an inventory
|
||||
variable associated with a host or group of hosts:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
# Example inventory that makes an alias for localhost that uses python3
|
||||
# Example inventory that makes an alias for localhost that uses Python3
|
||||
localhost-py3 ansible_host=localhost ansible_connection=local ansible_python_interpreter=/usr/bin/python3
|
||||
|
||||
# Example of setting a group of hosts to use Python3
|
||||
[py3-hosts]
|
||||
localhost-py3 ansible_host=localhost ansible_connection=local
|
||||
ubuntu16
|
||||
fedora27
|
||||
|
||||
[py3-hosts:vars]
|
||||
ansible_python_interpreter=/usr/bin/python3
|
||||
|
||||
See :ref:`intro_inventory` for more information.
|
||||
.. seealso:: :ref:`intro_inventory` for more information.
|
||||
|
||||
* Run your command or playbook:
|
||||
|
||||
@@ -76,7 +67,8 @@ See :ref:`intro_inventory` for more information.
|
||||
|
||||
|
||||
Note that you can also use the `-e` command line option to manually
|
||||
set the python interpreter when you run a command. For example:
|
||||
set the python interpreter when you run a command. This can be useful if you want to test whether
|
||||
a specific module or playbook has any bugs under Python 3. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -86,10 +78,14 @@ set the python interpreter when you run a command. For example:
|
||||
What to do if an incompatibility is found
|
||||
-----------------------------------------
|
||||
|
||||
If you find a bug while testing modules with Python3 you can submit a bug
|
||||
report on `Ansible's GitHub project
|
||||
<https://github.com/ansible/ansible/issues/>`_. Be sure to mention Python3 in
|
||||
the bug report so that the right people look at it.
|
||||
We have spent several releases squashing bugs and adding new tests so that Ansible's core feature
|
||||
set runs under both Python 2 and Python 3. However, bugs may still exist in edge cases and many of
|
||||
the modules shipped with Ansible are maintained by the community and not all of those may be ported
|
||||
yet.
|
||||
|
||||
If you find a bug running under Python 3 you can submit a bug report on `Ansible's GitHub project
|
||||
<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 :ref:`developing_python3` for information on how we fix
|
||||
|
||||
@@ -16,8 +16,8 @@ This cycle can be extended in order to allow for larger changes to be properly
|
||||
implemented and tested before a new release is made available.
|
||||
|
||||
Ansible has a graduated support structure that extends to three major releases.
|
||||
For more information, read about the :ref: `_development_and_stable_versiona_maintenance_workflow` or see
|
||||
the chart in :ref:`schedule` for the degrees to which current releases are supported.
|
||||
For more information, read about the :ref:`development_and_stable_version_maintenance_workflow` or
|
||||
see the chart in :ref:`release_schedule` for the degrees to which current releases are supported.
|
||||
|
||||
.. note:: Support for three major releases began with Ansible-2.4. Ansible-2.3 and older versions
|
||||
are only supported for two releases.
|
||||
@@ -70,7 +70,7 @@ devel `2.6` (unreleased, trunk) In development
|
||||
.. _support_life:
|
||||
.. _methods:
|
||||
|
||||
.. _development_and_stable_versiona_maintenance_workflow:
|
||||
.. _development_and_stable_version_maintenance_workflow:
|
||||
|
||||
Development and stable version maintenance workflow
|
||||
```````````````````````````````````````````````````
|
||||
|
||||
Reference in New Issue
Block a user