mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Merge pull request #4379 from cchurch/devel
Spelling corrections for docsite.
This commit is contained in:
commit
d01d9b3a6d
18 changed files with 42 additions and 42 deletions
|
@ -6,7 +6,7 @@ the Ansible python API to control nodes, you can extend Ansible to respond to va
|
|||
write various plugins, and you can plug in inventory data from external data sources. This document
|
||||
covers the Runner and Playbook API at a basic level.
|
||||
|
||||
If you are looking to use Ansible programatically from something other than Python, trigger events asynchronously,
|
||||
If you are looking to use Ansible programmatically from something other than Python, trigger events asynchronously,
|
||||
or have access control and logging demands, take a look at `AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx>`_
|
||||
as it has a very nice REST API that provides all of these things at a higher level.
|
||||
|
||||
|
|
|
@ -24,7 +24,7 @@ Tutorial
|
|||
Let's build a very-basic module to get and set the system time. For starters, let's build
|
||||
a module that just outputs the current time.
|
||||
|
||||
We are going to use Python here but any language is possible. Only File I/O and outputing to standard
|
||||
We are going to use Python here but any language is possible. Only File I/O and outputting to standard
|
||||
out are required. So, bash, C++, clojure, Python, Ruby, whatever you want
|
||||
is fine.
|
||||
|
||||
|
@ -224,7 +224,7 @@ only shorter in terms of code, they are actually FASTER in terms of execution ti
|
|||
|
||||
Rather than mention these here, the best way to learn is to read some of the `source of the modules <https://github.com/ansible/ansible/tree/devel/library>`_ that come with Ansible.
|
||||
|
||||
The 'group' and 'user' modules are reasonably non-trival and showcase what this looks like.
|
||||
The 'group' and 'user' modules are reasonably non-trivial and showcase what this looks like.
|
||||
|
||||
Key parts include always ending the module file with::
|
||||
|
||||
|
@ -341,7 +341,7 @@ and guidelines:
|
|||
|
||||
* Return codes from modules are not actually not signficant, but continue on with 0=success and non-zero=failure for reasons of future proofing.
|
||||
|
||||
* As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
|
||||
* As results from many hosts will be aggregated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
|
||||
|
||||
.. _module_dev_shorthand:
|
||||
|
||||
|
|
|
@ -4,8 +4,8 @@ Developing Plugins
|
|||
.. contents::
|
||||
:depth: 2
|
||||
|
||||
Ansible is pluggable in a lot of other ways seperate from inventory scripts and callbacks. Many of these features are there to cover fringe use cases and are infrequently needed, and others are pluggable simply because they are there to implement core features
|
||||
in ansible and were most convient to be made pluggable.
|
||||
Ansible is pluggable in a lot of other ways separate from inventory scripts and callbacks. Many of these features are there to cover fringe use cases and are infrequently needed, and others are pluggable simply because they are there to implement core features
|
||||
in ansible and were most convenient to be made pluggable.
|
||||
|
||||
This section will explore these features, though they are generally not common in terms of things people would look to extend quite
|
||||
as often.
|
||||
|
|
|
@ -156,7 +156,7 @@ Here is an example::
|
|||
- name: recursively copy files from management server to target
|
||||
local_action: command rsync -a /path/to/files $inventory_hostname:/path/to/target/
|
||||
|
||||
Note that you'll need passphrase-less SSH or ssh-agent set up to let rsync copy without prompting for a passphase or password.
|
||||
Note that you'll need passphrase-less SSH or ssh-agent set up to let rsync copy without prompting for a passphrase or password.
|
||||
|
||||
.. _shell_env:
|
||||
|
||||
|
|
|
@ -284,7 +284,7 @@ A datacenter or cloud architecture is full of many systems, playing many parts -
|
|||
monitoring systems, continuous integration systems, etc. In performing any process, it is necessary to touch systems in particular orders,
|
||||
often to simulate rolling updates or to deploy software correctly. Some system may perform some steps, then others, then previous systems
|
||||
already processed may need to perform more steps. Along the way, emails may need to be sent or web services contacted. Ansible
|
||||
orchestration is all about modelling that kind of process.
|
||||
orchestration is all about modeling that kind of process.
|
||||
|
||||
paramiko
|
||||
++++++++
|
||||
|
@ -360,7 +360,7 @@ Runner
|
|||
++++++
|
||||
|
||||
A core software component of Ansible that is the power behind /usr/bin/ansible directly -- and corresponds to the invocation
|
||||
of each task in a playbook. The Runner is something Ansible developers may talk about, but it's not really userland
|
||||
of each task in a playbook. The Runner is something Ansible developers may talk about, but it's not really user land
|
||||
vocabulary.
|
||||
|
||||
Serial
|
||||
|
|
|
@ -46,7 +46,7 @@ Ansible modules are resources that are distributed to remote nodes to make them
|
|||
state. Ansible follows a "batteries included" philosophy, so you have a lot of great modules for all manner of
|
||||
IT tasks in the core distribution. This means modules are well up-to-date and you don't have to hunt for an implementation
|
||||
that will work on your platform. You may think of the module library as a toolbox full of useful system management tools,
|
||||
and playbooks as the instructions for buildilng something using those tools.
|
||||
and playbooks as the instructions for building something using those tools.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
@ -121,7 +121,7 @@ AnsibleWorks AWX
|
|||
|
||||
`AnsibleWorks <http://ansibleworks.com>`_, who also sponsors the Ansible community, also produces 'AWX', which is a web-based solution that makes Ansible even more easy to use for IT teams of all kinds. It's designed to be the hub for all of your automation tasks.
|
||||
|
||||
AWX allows you to control access to who can access what, even allowing sharing of SSH credentials without someone being able to transfer those credentials. Inventory can be graphically managed or synced with a widde variety of cloud sources. It logs all of your jobs, integrates well with LDAP, and has an amazing browseable REST API. Command line tools are available for easy integration
|
||||
AWX allows you to control access to who can access what, even allowing sharing of SSH credentials without someone being able to transfer those credentials. Inventory can be graphically managed or synced with a wide variety of cloud sources. It logs all of your jobs, integrates well with LDAP, and has an amazing browsable REST API. Command line tools are available for easy integration
|
||||
with Jenkins as well.
|
||||
|
||||
Find out more about AWX features and how to download it on the `AWX webpage <http://ansibleworks.com/ansibleworks-awx>`_. AWX
|
||||
|
@ -157,7 +157,7 @@ IT automation solutions that work well for them. Should you wish to get more i
|
|||
Developer Information
|
||||
`````````````````````
|
||||
|
||||
Learn how to build modules of your own in any language, and also how to extend ansible through several kinds of plugins. Explore Ansible's Python API and write Python plugins to integrate with other solutions in your environment.
|
||||
Learn how to build modules of your own in any language, and also how to extend Ansible through several kinds of plugins. Explore Ansible's Python API and write Python plugins to integrate with other solutions in your environment.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
|
@ -14,7 +14,7 @@ quick, but don't want to save for later.
|
|||
|
||||
This is a good place to start to understand the basics of what ansible can do
|
||||
prior to learning the playbooks language -- ad-hoc commands can also be used
|
||||
to do quick things that you might not neccessarily want to write a full playbook
|
||||
to do quick things that you might not necessarily want to write a full playbook
|
||||
for.
|
||||
|
||||
Generally speaking, the true power of Ansible lies in playbooks.
|
||||
|
|
|
@ -245,9 +245,9 @@ legacy_playbook_variables
|
|||
|
||||
Ansible prefers to use Jinja2 syntax '{{ like_this }}' to indicate a variable should be substituted in a particular string. However,
|
||||
older versions of playbooks used a more Perl-style syntax. This syntax was undesirable as it frequently conflicted with bash and
|
||||
was hard to explain to new users when deferencing complicated variable hierarchies, so we have standardized on the '{{ jinja2 }}' way.
|
||||
was hard to explain to new users when referencing complicated variable hierarchies, so we have standardized on the '{{ jinja2 }}' way.
|
||||
|
||||
To ensure a string like '$foo' is not inadvertedly replaced in a Perl or Bash script template, the old form of templating (which is
|
||||
To ensure a string like '$foo' is not indadvertedly replaced in a Perl or Bash script template, the old form of templating (which is
|
||||
still enabled as of Ansible 1.4) can be disabled like so ::
|
||||
|
||||
legacy_playbook_variables = no
|
||||
|
@ -261,7 +261,7 @@ This is the default location Ansible looks to find modules::
|
|||
|
||||
library = /usr/share/ansible
|
||||
|
||||
Ansible knows how to look in multiple locations if you feed it a colon seperated path, and it also will look for modules in the
|
||||
Ansible knows how to look in multiple locations if you feed it a colon separated path, and it also will look for modules in the
|
||||
"./library" directory alongside a playbook.
|
||||
|
||||
.. _log_path:
|
||||
|
@ -358,7 +358,7 @@ value here to avoid re-specifying --ansible-private-keyfile with every invocatio
|
|||
remote_port
|
||||
===========
|
||||
|
||||
This sets the default SSH port on all of your systems, for systems that didn't specify an alternative value in inventroy.
|
||||
This sets the default SSH port on all of your systems, for systems that didn't specify an alternative value in inventory.
|
||||
The default is the standard 22::
|
||||
|
||||
remote_port = 22
|
||||
|
@ -563,6 +563,6 @@ This setting controls the timeout for the socket connect call, and should be kep
|
|||
|
||||
accelerate_connect_timeout = 1.0
|
||||
|
||||
Note, this value can be set to less than one second, however it is probably not a good idea to do so unless you're on a very fast and reliable LAN. If you're connecting to systems over the internet, it may be neccessary to increase this timeout.
|
||||
Note, this value can be set to less than one second, however it is probably not a good idea to do so unless you're on a very fast and reliable LAN. If you're connecting to systems over the internet, it may be necessary to increase this timeout.
|
||||
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@ or a piece of expensive enterprisey CMDB software.
|
|||
|
||||
Ansible easily supports all of these options via an external inventory system. The plugins directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
|
||||
|
||||
`AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx/>`_ also provides a database to store inventory results that is both web and REST Accessible. AWX syncs with all Ansible dynamic inventory sources. By having a database record of all of your hosts, it's easy to corrolate past event history and see which ones have had failures on their last playbook runs.
|
||||
`AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx/>`_ also provides a database to store inventory results that is both web and REST Accessible. AWX syncs with all Ansible dynamic inventory sources. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs.
|
||||
|
||||
For information about writing your own dynamic inventory source, see :doc:`developing_inventory`.
|
||||
|
||||
|
@ -220,7 +220,7 @@ Using Multiple Inventory Sources
|
|||
````````````````````````````````
|
||||
|
||||
If the location given to -i in Ansible is a directory (or as so configured in ansible.cfg), Ansible can use multiple inventory sources
|
||||
at thes same time. When doing so, it is possible to mix both dynamic and staticly managed inventory sources in the same ansible run. Instant
|
||||
at thes same time. When doing so, it is possible to mix both dynamic and statically managed inventory sources in the same ansible run. Instant
|
||||
hybrid cloud!
|
||||
|
||||
.. seealso::
|
||||
|
|
|
@ -13,7 +13,7 @@ Now that you've read :doc:`intro_installation` and installed Ansible, it's time
|
|||
started with some commands.
|
||||
|
||||
What we are showing first are not the powerful configuration/deployment/orchestration of Ansible, called playbooks.
|
||||
Playbooks are covered in a seperate section.
|
||||
Playbooks are covered in a separate section.
|
||||
|
||||
This section is about how to get going initially. Once you have these concepts down, read :doc:`intro_adhoc` for some more
|
||||
detail, and then you'll be ready to dive into playbooks and explore the most interesting parts!
|
||||
|
|
|
@ -32,7 +32,7 @@ machines, many users will actually track the development version.
|
|||
|
||||
Ansible's release cycles are usually about two months long. Due to this
|
||||
short release cycle, minor bugs will generally be fixed in the next release versus maintaining
|
||||
backports on the stable branch. Major bugs will still have maintaince releases when needed, though
|
||||
backports on the stable branch. Major bugs will still have maintenance releases when needed, though
|
||||
these are infrequent.
|
||||
|
||||
If you are wishing to run the latest released version of Ansible and you are running Red Hat Enterprise Linux (TM), CentOS, Fedora, Debian, or Ubuntu, we recommend using the OS package manager.
|
||||
|
@ -40,7 +40,7 @@ If you are wishing to run the latest released version of Ansible and you are run
|
|||
For other installation options, we recommend installing via "pip", which is the Python package manager, though other options are also available.
|
||||
|
||||
If you wish to track the development release to use and test the latest features, we will share
|
||||
information about running from source. It's not neccessary to install the program to run from source.
|
||||
information about running from source. It's not necessary to install the program to run from source.
|
||||
|
||||
.. _control_machine_requirements:
|
||||
|
||||
|
|
|
@ -179,7 +179,7 @@ is an excellent way to track changes to your inventory and host variables.
|
|||
List of Behavioral Inventory Parameters
|
||||
+++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
As aluded to above, setting the following variables controls how ansible interacts with remote hosts. Some we have already
|
||||
As alluded to above, setting the following variables controls how ansible interacts with remote hosts. Some we have already
|
||||
mentioned::
|
||||
|
||||
ansible_ssh_host
|
||||
|
@ -195,7 +195,7 @@ mentioned::
|
|||
ansible_ssh_private_key_file
|
||||
Private key file used by ssh. Useful if using multiple keys and you don't want to use SSH agent.
|
||||
ansible_python_interpreter
|
||||
The target host python path. This is userful for systems with more
|
||||
The target host python path. This is useful for systems with more
|
||||
than one Python or not located at "/usr/bin/python" such as \*BSD, or where /usr/bin/python
|
||||
is not a 2.X series Python. We do not use the "/usr/bin/env" mechanism as that requires the remote user's
|
||||
path to be set right and also assumes the "python" executable is named python, where the executable might
|
||||
|
|
|
@ -32,7 +32,7 @@ It is also possible to address a specific host or set of hosts by name::
|
|||
192.168.1.50
|
||||
192.168.1.*
|
||||
|
||||
The following patterns address one or more groups. Groups seperated by a colon indicate an "OR" configuration.
|
||||
The following patterns address one or more groups. Groups separated by a colon indicate an "OR" configuration.
|
||||
This means the host may be in either one group or the other::
|
||||
|
||||
webservers
|
||||
|
|
|
@ -180,7 +180,7 @@ is not provided though, the string fed to 'action' will be used for
|
|||
output.
|
||||
|
||||
Tasks can be declared using the legacy "action: module options" format, but
|
||||
it is recommeded that you use the more conventional "module: options" format.
|
||||
it is recommended that you use the more conventional "module: options" format.
|
||||
This recommended format is used throughout the documentation, but you may
|
||||
encounter the older format in some playbooks.
|
||||
|
||||
|
@ -265,7 +265,7 @@ triggered once even if notified by multiple different tasks.
|
|||
|
||||
For instance, multiple resources may indicate
|
||||
that apache needs to be restarted because they have changed a config file,
|
||||
but apache will only be bounced once to avoid unneccessary restarts.
|
||||
but apache will only be bounced once to avoid unnecessary restarts.
|
||||
|
||||
Here's an example of restarting two services when the contents of a file
|
||||
change, but only if the file changes::
|
||||
|
@ -330,7 +330,7 @@ Ansible-Pull
|
|||
````````````
|
||||
|
||||
Should you want to invert the architecture of Ansible, so that nodes check in to a central location, instead
|
||||
of pushing configuraiton out to them, you can.
|
||||
of pushing configuration out to them, you can.
|
||||
|
||||
Ansible-pull is a small script that will checkout a repo of configuration instructions from git, and then
|
||||
run ansible-playbook against that content.
|
||||
|
|
|
@ -20,7 +20,7 @@ the SSH connection (this key is different for every host, and is also regenerate
|
|||
|
||||
By default, Ansible will use port 5099 for the accelerated connection, though this is configurable. Once running, the daemon will accept connections for 30 minutes, after which time it will terminate itself and need to be restarted over SSH.
|
||||
|
||||
Accelerated mode offers several improvments over the original fireball mode from which it was based:
|
||||
Accelerated mode offers several improvements over the original fireball mode from which it was based:
|
||||
|
||||
* No bootstrapping is required, only a single line needs to be added to each play you wish to run in accelerated mode.
|
||||
* Support for sudo commands (see below for more details and caveats) is available.
|
||||
|
|
|
@ -42,8 +42,8 @@ Maximum Failure Percentage
|
|||
.. versionadded:: 1.3
|
||||
|
||||
By default, Ansible will continue executing actions as long as there are hosts in the group that have not yet failed.
|
||||
In some situations, such as with the rolling updates described above, it may be desireable to abort the play when a
|
||||
certain threshold of failures have been reached. To acheive this, as of version 1.3 you can set a maximum failure
|
||||
In some situations, such as with the rolling updates described above, it may be desirable to abort the play when a
|
||||
certain threshold of failures have been reached. To achieve this, as of version 1.3 you can set a maximum failure
|
||||
percentage on a play as follows::
|
||||
|
||||
- hosts: webservers
|
||||
|
|
|
@ -10,7 +10,7 @@ Introduction
|
|||
While it is possible to write a playbook in one very large file (and you might start out learning playbooks this way),
|
||||
eventually you'll want to reuse files and start to organize things.
|
||||
|
||||
At a basic level, including task files allows you to break up bits of configuration policy into smaller files. Taks includes
|
||||
At a basic level, including task files allows you to break up bits of configuration policy into smaller files. Task includes
|
||||
pull in tasks from other files. Since handlers are tasks too, you can also include handler files from the 'handlers:' section.
|
||||
|
||||
See :doc:`playbooks` if you need a review of these concepts.
|
||||
|
@ -18,7 +18,7 @@ See :doc:`playbooks` if you need a review of these concepts.
|
|||
Playbooks can also include plays from other playbook files. When that is done, the plays will be inserted into the playbook to form
|
||||
a longer list of plays.
|
||||
|
||||
When you start to think about it -- tasks, handlers, variables, and so -- begin to form larger concepts. You start to think about modelling
|
||||
When you start to think about it -- tasks, handlers, variables, and so -- begin to form larger concepts. You start to think about modeling
|
||||
what something is, rather than how to make something look like something. It's no longer "apply this handful of THINGS" to these hosts, you say "these hosts are a dbservers" or "these hosts are webservers". In programming, we might call that 'encapsulating' how things work. For instance,
|
||||
you can drive a car without knowing how the engine works.
|
||||
|
||||
|
@ -29,7 +29,7 @@ We'll start with understanding includes so roles make more sense, but our ultima
|
|||
are great and you should use them every time you write playbooks.
|
||||
|
||||
See the 'ansible-examples' repository on github for lots of examples of all of this
|
||||
put together. You may wish to have this open in a seperate tab as you dive in.
|
||||
put together. You may wish to have this open in a separate tab as you dive in.
|
||||
|
||||
Task Include Files And Encouraging Reuse
|
||||
````````````````````````````````````````
|
||||
|
@ -148,7 +148,7 @@ Now that you have learned about vars_files, tasks, and handlers, what is the bes
|
|||
The short answer is to use roles! Roles are ways of automatically loading certain vars_files, tasks, and
|
||||
handlers based on a known file structure. Grouping content by roles also allows easy sharing of roles with other users.
|
||||
|
||||
Roles are just automation around 'include' directives as redescribed above, and really don't contain much
|
||||
Roles are just automation around 'include' directives as described above, and really don't contain much
|
||||
additional magic beyond some improvements to search path handling for referenced files. However, that can be a big thing!
|
||||
|
||||
Example project structure::
|
||||
|
|
|
@ -475,7 +475,7 @@ Similarly, the hostname as the system reports it is::
|
|||
|
||||
Facts are frequently used in conditionals (see `playbook_conditionals`) and also in templates.
|
||||
|
||||
Facts can be also used to create dynamic groups of hosts that match particular critera, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter.
|
||||
Facts can be also used to create dynamic groups of hosts that match particular criteria, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter.
|
||||
|
||||
.. _disabling_facts:
|
||||
|
||||
|
@ -561,7 +561,7 @@ While it's mentioned elsewhere in that document too, here's a quick syntax examp
|
|||
when: foo_result.rc == 5
|
||||
|
||||
Registered variables are valid on the host the remainder of the playbook run, which is the same as the lifetime of "facts"
|
||||
in Ansible. Effectively registerd variables are just like facts.
|
||||
in Ansible. Effectively registered variables are just like facts.
|
||||
|
||||
.. _accessing_complex_variable_data:
|
||||
|
||||
|
@ -792,7 +792,7 @@ control you might want over values.
|
|||
First off, group variables are super powerful.
|
||||
|
||||
Site wide defaults should be defined as a 'group_vars/all' setting. Group variables are generally placed alongside
|
||||
your inventory file. They can also be returned by a dynamic inventroy script (see `intro_dynamic_inventory`) or defined
|
||||
your inventory file. They can also be returned by a dynamic inventory script (see `intro_dynamic_inventory`) or defined
|
||||
in things like AnsibleWorks AWX from the UI or API::
|
||||
|
||||
---
|
||||
|
@ -830,7 +830,7 @@ See `intro_roles` for more info about this::
|
|||
# if not overriden in inventory or as a parameter, this is the value that will be used
|
||||
http_port: 80
|
||||
|
||||
if you are writing a role and want to ensure the value in the role is absolutely used in that role, and is not going to be overriden
|
||||
if you are writing a role and want to ensure the value in the role is absolutely used in that role, and is not going to be overridden
|
||||
by inventory, you should but it in roles/x/vars/main.yml like so, and inventory values cannot override it. -e however, still will::
|
||||
|
||||
----
|
||||
|
@ -849,7 +849,7 @@ If you are using a role and want to override a default, pass it as a parameter t
|
|||
roles:
|
||||
- { name: apache, http_port: 8080 }
|
||||
|
||||
This makes it clear to the playbook reader that you've made a concious choice to override some default in the role, or pass in some
|
||||
This makes it clear to the playbook reader that you've made a conscious choice to override some default in the role, or pass in some
|
||||
configuration that the role can't assume by itself. It also allows you to pass something site-specific that isn't really part of the
|
||||
role you are sharing with others.
|
||||
|
||||
|
@ -883,7 +883,7 @@ can set variables in there and make use of them in other roles and elsewhere in
|
|||
|
||||
So, that's precedence, explained in a more direct way. Don't worry about precedence, just think about if your role is defining a
|
||||
variable that is a default, or a "live" variable you definitely want to use. Inventory lies in precedence right in the middle, and
|
||||
if you want to forceably override something, use -e.
|
||||
if you want to forcibly override something, use -e.
|
||||
|
||||
If you found that a little hard to understand, take a look at the "ansible-examples" repo on our github for a bit more about
|
||||
how all of these things can work together.
|
||||
|
|
Loading…
Reference in a new issue