cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
ansible/docs/docsite/rst/reference_appendices/glossary.rst
Toshio Kuratomi 46b1a999c6
Collections docs generation backport (#70515) 
* Build documentation for Ansible-2.10 (formerly known as ACD).

Builds plugin docs from collections whose source is on galaxy

The new command downloads collections from galaxy, then finds the
plugins inside of them to get the documentation for those plugins.

* Update the python syntax checks
  * docs builds can now require python 3.6+.

* Move plugin formatter code out to an external tool, antsibull-docs.
  Collection owners want to be able to extract docs for their own
  websites as well.
* The jinja2 filters, tests, and other support code have moved to antsibull
* Remove document_plugins as that has now been integrated into antsibull-docs

* Cleanup and bugfix to other build script code:
  * The Commands class needed to have its metaclass set for abstractmethod
    to work correctly
  * Fix lint issues in some command plugins

* Add the docs/docsite/rst/collections to .gitignore as
  everything in that directory will be generated so we don't want any of
  it saved in the git repository
* gitignore the build dir and remove edit docs link on module pages

* Add docs/rst/collections as a directory to remove on make clean
* Split the collections docs from the main docs

* remove version and edit on github
* remove version banner for just collections
* clarify examples need collection keyword defined

* Remove references to plugin documentation locations that no longer exist.
  * Perhaps the pages in plugins/*.rst should be deprecated
    altogether and their content moved?
  * If not, perhaps we want to rephrase and link into the collection
    documentation?
  * Or perhaps we want to link to the plugins which are present in
    collections/ansible/builtin?

* Remove PYTHONPATH from the build-ansible calls
  One of the design goals of the build-ansible.py script was for it to
  automatically set its library path to include the checkout of ansible
  and the library of code to implement itself.  Because it automatically
  includes the checkout of ansible, we don't need to set PYTHONPATH in
  the Makefile any longer.

* Create a command to only build ansible-base plugin docs
  * When building docs for devel, only build the ansible-base docs for
    now.  This is because antsibull needs support for building a "devel
    tree" of docs.  This can be changed once that is implemented
  * When building docs for the sanity tests, only build the ansible-base
    plugin docs for now.  Those are the docs which are in this repo so
    that seems appropriate for now.

* Docs: User guide overhaul, part 5 (#70307)

(cherry picked from commit db354c0300)

* Need to return any error code from running antsibull-docs (#70763)

This way we fail early if there's a problem

(cherry picked from commit 1e3989c9f7)

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
2020-07-20 14:28:35 -07:00

501 lines
27 KiB
ReStructuredText
Raw Blame History

Glossary
========
The following is a list (and re-explanation) of term definitions used elsewhere in the Ansible documentation.
Consult the documentation home page for the full documentation and to see the terms in context, but this should be a good resource
to check your knowledge of Ansible's components and understand how they fit together. It's something you might wish to read for review or
when a term comes up on the mailing list.
.. glossary::
Action
An action is a part of a task that specifies which of the modules to
run and which arguments to pass to that module. Each task can have
only one action, but it may also have other parameters.
Ad Hoc
Refers to running Ansible to perform some quick command, using
:command:`/usr/bin/ansible`, rather than the :term:`orchestration`
language, which is :command:`/usr/bin/ansible-playbook`. An example
of an ad hoc command might be rebooting 50 machines in your
infrastructure. Anything you can do ad hoc can be accomplished by
writing a :term:`playbook <playbooks>` and playbooks can also glue
lots of other operations together.
Async
Refers to a task that is configured to run in the background rather
than waiting for completion. If you have a long process that would
run longer than the SSH timeout, it would make sense to launch that
task in async mode. Async modes can poll for completion every so many
seconds or can be configured to "fire and forget", in which case
Ansible will not even check on the task again; it will just kick it
off and proceed to future steps. Async modes work with both
:command:`/usr/bin/ansible` and :command:`/usr/bin/ansible-playbook`.
Callback Plugin
Refers to some user-written code that can intercept results from
Ansible and do something with them. Some supplied examples in the
GitHub project perform custom logging, send email, or even play sound
effects.
Check Mode
Refers to running Ansible with the ``--check`` option, which does not
make any changes on the remote systems, but only outputs the changes
that might occur if the command ran without this flag. This is
analogous to so-called "dry run" modes in other systems, though the
user should be warned that this does not take into account unexpected
command failures or cascade effects (which is true of similar modes in
other systems). Use this to get an idea of what might happen, but do
not substitute it for a good staging environment.
Connection Plugin
By default, Ansible talks to remote machines through pluggable
libraries. Ansible uses native OpenSSH (:term:`SSH (Native)`) or
a Python implementation called :term:`paramiko`. OpenSSH is preferred
if you are using a recent version, and also enables some features like
Kerberos and jump hosts. This is covered in the :ref:`getting
started section <remote_connection_information>`. There are also
other connection types like ``accelerate`` mode, which must be
bootstrapped over one of the SSH-based connection types but is very
fast, and local mode, which acts on the local system. Users can also
write their own connection plugins.
Conditionals
A conditional is an expression that evaluates to true or false that
decides whether a given task is executed on a given machine or not.
Ansible's conditionals are powered by the 'when' statement, which are
discussed in the :ref:`working_with_playbooks`.
Declarative
An approach to achieving a task that uses a description of the
final state rather than a description of the sequence of steps
necessary to achieve that state. For a real world example, a
declarative specification of a task would be: "put me in California".
Depending on your current location, the sequence of steps to get you to
California may vary, and if you are already in California, nothing
at all needs to be done. Ansible's Resources are declarative; it
figures out the steps needed to achieve the final state. It also lets
you know whether or not any steps needed to be taken to get to the
final state.
Diff Mode
A ``--diff`` flag can be passed to Ansible to show what changed on
modules that support it. You can combine it with ``--check`` to get a
good 'dry run'. File diffs are normally in unified diff format.
Executor
A core software component of Ansible that is the power behind
:command:`/usr/bin/ansible` directly -- and corresponds to the
invocation of each task in a :term:`playbook <playbooks>`. The
Executor is something Ansible developers may talk about, but it's not
really user land vocabulary.
Facts
Facts are simply things that are discovered about remote nodes. While
they can be used in :term:`playbooks` and templates just like
variables, facts are things that are inferred, rather than set. Facts
are automatically discovered by Ansible when running plays by
executing the internal :ref:`setup module <setup_module>` on the remote nodes. You
never have to call the setup module explicitly, it just runs, but it
can be disabled to save time if it is not needed or you can tell
ansible to collect only a subset of the full facts via the
``gather_subset:`` option. For the convenience of users who are
switching from other configuration management systems, the fact module
will also pull in facts from the :program:`ohai` and :program:`facter`
tools if they are installed. These are fact libraries from Chef and
Puppet, respectively. (These may also be disabled via
``gather_subset:``)
Filter Plugin
A filter plugin is something that most users will never need to
understand. These allow for the creation of new :term:`Jinja2`
filters, which are more or less only of use to people who know what
Jinja2 filters are. If you need them, you can learn how to write them
in the :ref:`API docs section <developing_filter_plugins>`.
Forks
Ansible talks to remote nodes in parallel and the level of parallelism
can be set either by passing ``--forks`` or editing the default in
a configuration file. The default is a very conservative five (5)
forks, though if you have a lot of RAM, you can easily set this to
a value like 50 for increased parallelism.
Gather Facts (Boolean)
:term:`Facts` are mentioned above. Sometimes when running a multi-play
:term:`playbook <playbooks>`, it is desirable to have some plays that
don't bother with fact computation if they aren't going to need to
utilize any of these values. Setting ``gather_facts: False`` on
a playbook allows this implicit fact gathering to be skipped.
Globbing
Globbing is a way to select lots of hosts based on wildcards, rather
than the name of the host specifically, or the name of the group they
are in. For instance, it is possible to select ``ww*`` to match all
hosts starting with ``www``. This concept is pulled directly from
:program:`Func`, one of Michael DeHaan's (an Ansible Founder) earlier
projects. In addition to basic globbing, various set operations are
also possible, such as 'hosts in this group and not in another group',
and so on.
Group
A group consists of several hosts assigned to a pool that can be
conveniently targeted together, as well as given variables that they
share in common.
Group Vars
The :file:`group_vars/` files are files that live in a directory
alongside an inventory file, with an optional filename named after
each group. This is a convenient place to put variables that are
provided to a given group, especially complex data structures, so that
these variables do not have to be embedded in the :term:`inventory`
file or :term:`playbook <playbooks>`.
Handlers
Handlers are just like regular tasks in an Ansible
:term:`playbook <playbooks>` (see :term:`Tasks`) but are only run if
the Task contains a ``notify`` directive and also indicates that it
changed something. For example, if a config file is changed, then the
task referencing the config file templating operation may notify
a service restart handler. This means services can be bounced only if
they need to be restarted. Handlers can be used for things other than
service restarts, but service restarts are the most common usage.
Host
A host is simply a remote machine that Ansible manages. They can have
individual variables assigned to them, and can also be organized in
groups. All hosts have a name they can be reached at (which is either
an IP address or a domain name) and, optionally, a port number, if they
are not to be accessed on the default SSH port.
Host Specifier
Each :term:`Play <plays>` in Ansible maps a series of :term:`tasks` (which define the role,
purpose, or orders of a system) to a set of systems.
This ``hosts:`` directive in each play is often called the hosts specifier.
It may select one system, many systems, one or more groups, or even
some hosts that are in one group and explicitly not in another.
Host Vars
Just like :term:`Group Vars`, a directory alongside the inventory file named
:file:`host_vars/` can contain a file named after each hostname in the
inventory file, in :term:`YAML` format. This provides a convenient place to
assign variables to the host without having to embed them in the
:term:`inventory` file. The Host Vars file can also be used to define complex
data structures that can't be represented in the inventory file.
Idempotency
An operation is idempotent if the result of performing it once is
exactly the same as the result of performing it repeatedly without
any intervening actions.
Includes
The idea that :term:`playbook <playbooks>` files (which are nothing
more than lists of :term:`plays`) can include other lists of plays,
and task lists can externalize lists of :term:`tasks` in other files,
and similarly with :term:`handlers`. Includes can be parameterized,
which means that the loaded file can pass variables. For instance, an
included play for setting up a WordPress blog may take a parameter
called ``user`` and that play could be included more than once to
create a blog for both ``alice`` and ``bob``.
Inventory
A file (by default, Ansible uses a simple INI format) that describes
:term:`Hosts <Host>` and :term:`Groups <Group>` in Ansible. Inventory
can also be provided via an :term:`Inventory Script` (sometimes called
an "External Inventory Script").
Inventory Script
A very simple program (or a complicated one) that looks up
:term:`hosts <Host>`, :term:`group` membership for hosts, and variable
information from an external resource -- whether that be a SQL
database, a CMDB solution, or something like LDAP. This concept was
adapted from Puppet (where it is called an "External Nodes
Classifier") and works more or less exactly the same way.
Jinja2
Jinja2 is the preferred templating language of Ansible's template
module. It is a very simple Python template language that is
generally readable and easy to write.
JSON
Ansible uses JSON for return data from remote modules. This allows
modules to be written in any language, not just Python.
Lazy Evaluation
In general, Ansible evaluates any variables in
:term:`playbook <playbooks>` content at the last possible second,
which means that if you define a data structure that data structure
itself can define variable values within it, and everything "just
works" as you would expect. This also means variable strings can
include other variables inside of those strings.
Library
A collection of modules made available to :command:`/usr/bin/ansible`
or an Ansible :term:`playbook <playbooks>`.
Limit Groups
By passing ``--limit somegroup`` to :command:`ansible` or
:command:`ansible-playbook`, the commands can be limited to a subset
of :term:`hosts <Host>`. For instance, this can be used to run
a :term:`playbook <playbooks>` that normally targets an entire set of
servers to one particular server.
Local Action
A local_action directive in a :term:`playbook <playbooks>` targeting
remote machines means that the given step will actually occur on the
local machine, but that the variable ``{{ ansible_hostname }}`` can be
passed in to reference the remote hostname being referred to in that
step. This can be used to trigger, for example, an rsync operation.
Local Connection
By using ``connection: local`` in a :term:`playbook <playbooks>`, or
passing ``-c local`` to :command:`/usr/bin/ansible`, this indicates
that we are managing the local host and not a remote machine.
Lookup Plugin
A lookup plugin is a way to get data into Ansible from the outside world.
Lookup plugins are an extension of Jinja2 and can be accessed in templates, e.g.,
``{{ lookup('file','/path/to/file') }}``.
These are how such things as ``with_items``, are implemented.
There are also lookup plugins like ``file`` which loads data from
a file and ones for querying environment variables, DNS text records,
or key value stores.
Loops
Generally, Ansible is not a programming language. It prefers to be
more declarative, though various constructs like ``loop`` allow
a particular task to be repeated for multiple items in a list.
Certain modules, like :ref:`yum <yum_module>` and :ref:`apt <apt_module>`, actually take
lists directly, and can install all packages given in those lists
within a single transaction, dramatically speeding up total time to
configuration, so they can be used without loops.
Modules
Modules are the units of work that Ansible ships out to remote
machines. Modules are kicked off by either
:command:`/usr/bin/ansible` or :command:`/usr/bin/ansible-playbook`
(where multiple tasks use lots of different modules in conjunction).
Modules can be implemented in any language, including Perl, Bash, or
Ruby -- but can leverage some useful communal library code if written
in Python. Modules just have to return :term:`JSON`. Once modules are
executed on remote machines, they are removed, so no long running
daemons are used. Ansible refers to the collection of available
modules as a :term:`library`.
Multi-Tier
The concept that IT systems are not managed one system at a time, but
by interactions between multiple systems and groups of systems in
well defined orders. For instance, a web server may need to be
updated before a database server and pieces on the web server may
need to be updated after *THAT* database server and various load
balancers and monitoring servers may need to be contacted. Ansible
models entire IT topologies and workflows rather than looking at
configuration from a "one system at a time" perspective.
Notify
The act of a :term:`task <tasks>` registering a change event and
informing a :term:`handler <handlers>` task that another
:term:`action` needs to be run at the end of the :term:`play <plays>`. If
a handler is notified by multiple tasks, it will still be run only
once. Handlers are run in the order they are listed, not in the order
that they are notified.
Orchestration
Many software automation systems use this word to mean different
things. Ansible uses it as a conductor would conduct an orchestra.
A datacenter or cloud architecture is full of many systems, playing
many parts -- web servers, database servers, maybe load balancers,
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 modeling that kind of process.
paramiko
By default, Ansible manages machines over SSH. The library that
Ansible uses by default to do this is a Python-powered library called
paramiko. The paramiko library is generally fast and easy to manage,
though users who want to use Kerberos or Jump Hosts may wish to switch
to a native SSH binary such as OpenSSH by specifying the connection
type in their :term:`playbooks`, or using the ``-c ssh`` flag.
Playbooks
Playbooks are the language by which Ansible orchestrates, configures,
administers, or deploys systems. They are called playbooks partially
because it's a sports analogy, and it's supposed to be fun using them.
They aren't workbooks :)
Plays
A :term:`playbook <playbooks>` is a list of plays. A play is
minimally a mapping between a set of :term:`hosts <Host>` selected by a host
specifier (usually chosen by :term:`groups <Group>` but sometimes by
hostname :term:`globs <Globbing>`) and the :term:`tasks` which run on those
hosts to define the role that those systems will perform. There can be
one or many plays in a playbook.
Pull Mode
By default, Ansible runs in :term:`push mode`, which allows it very
fine-grained control over when it talks to each system. Pull mode is
provided for when you would rather have nodes check in every N minutes
on a particular schedule. It uses a program called
:command:`ansible-pull` and can also be set up (or reconfigured) using
a push-mode :term:`playbook <playbooks>`. Most Ansible users use push
mode, but pull mode is included for variety and the sake of having
choices.
:command:`ansible-pull` works by checking configuration orders out of
git on a crontab and then managing the machine locally, using the
:term:`local connection` plugin.
Push Mode
Push mode is the default mode of Ansible. In fact, it's not really
a mode at all -- it's just how Ansible works when you aren't thinking
about it. Push mode allows Ansible to be fine-grained and conduct
nodes through complex orchestration processes without waiting for them
to check in.
Register Variable
The result of running any :term:`task <tasks>` in Ansible can be
stored in a variable for use in a template or a conditional statement.
The keyword used to define the variable is called ``register``, taking
its name from the idea of registers in assembly programming (though
Ansible will never feel like assembly programming). There are an
infinite number of variable names you can use for registration.
Resource Model
Ansible modules work in terms of resources. For instance, the
:ref:`file module <file_module>` will select a particular file and ensure
that the attributes of that resource match a particular model. As an
example, we might wish to change the owner of :file:`/etc/motd` to
``root`` if it is not already set to ``root``, or set its mode to
``0644`` if it is not already set to ``0644``. The resource models
are :term:`idempotent <idempotency>` meaning change commands are not
run unless needed, and Ansible will bring the system back to a desired
state regardless of the actual state -- rather than you having to tell
it how to get to the state.
Roles
Roles are units of organization in Ansible. Assigning a role to
a group of :term:`hosts <Host>` (or a set of :term:`groups <group>`,
or :term:`host patterns <Globbing>`, etc.) implies that they should
implement a specific behavior. A role may include applying certain
variable values, certain :term:`tasks`, and certain :term:`handlers`
-- or just one or more of these things. Because of the file structure
associated with a role, roles become redistributable units that allow
you to share behavior among :term:`playbooks` -- or even with other users.
Rolling Update
The act of addressing a number of nodes in a group N at a time to
avoid updating them all at once and bringing the system offline. For
instance, in a web topology of 500 nodes handling very large volume,
it may be reasonable to update 10 or 20 machines at a time, moving on
to the next 10 or 20 when done. The ``serial:`` keyword in an Ansible
:term:`playbooks` control the size of the rolling update pool. The
default is to address the batch size all at once, so this is something
that you must opt-in to. OS configuration (such as making sure config
files are correct) does not typically have to use the rolling update
model, but can do so if desired.
Serial
.. seealso::
:term:`Rolling Update`
Sudo
Ansible does not require root logins, and since it's daemonless,
definitely does not require root level daemons (which can be
a security concern in sensitive environments). Ansible can log in and
perform many operations wrapped in a sudo command, and can work with
both password-less and password-based sudo. Some operations that
don't normally work with sudo (like scp file transfer) can be achieved
with Ansible's :ref:`copy <copy_module>`, :ref:`template <template_module>`, and
:ref:`fetch <fetch_module>` modules while running in sudo mode.
SSH (Native)
Native OpenSSH as an Ansible transport is specified with ``-c ssh``
(or a config file, or a directive in the :term:`playbook <playbooks>`)
and can be useful if wanting to login via Kerberized SSH or using SSH
jump hosts, etc. In 1.2.1, ``ssh`` will be used by default if the
OpenSSH binary on the control machine is sufficiently new.
Previously, Ansible selected ``paramiko`` as a default. Using
a client that supports ``ControlMaster`` and ``ControlPersist`` is
recommended for maximum performance -- if you don't have that and
don't need Kerberos, jump hosts, or other features, ``paramiko`` is
a good choice. Ansible will warn you if it doesn't detect
ControlMaster/ControlPersist capability.
Tags
Ansible allows tagging resources in a :term:`playbook <playbooks>`
with arbitrary keywords, and then running only the parts of the
playbook that correspond to those keywords. For instance, it is
possible to have an entire OS configuration, and have certain steps
labeled ``ntp``, and then run just the ``ntp`` steps to reconfigure
the time server information on a remote host.
Task
:term:`Playbooks` exist to run tasks. Tasks combine an :term:`action`
(a module and its arguments) with a name and optionally some other
keywords (like :term:`looping directives <loops>`). :term:`Handlers`
are also tasks, but they are a special kind of task that do not run
unless they are notified by name when a task reports an underlying
change on a remote system.
Tasks
A list of :term:`Task`.
Templates
Ansible can easily transfer files to remote systems but often it is
desirable to substitute variables in other files. Variables may come
from the :term:`inventory` file, :term:`Host Vars`, :term:`Group
Vars`, or :term:`Facts`. Templates use the :term:`Jinja2` template
engine and can also include logical constructs like loops and if
statements.
Transport
Ansible uses :term:``Connection Plugins`` to define types of available
transports. These are simply how Ansible will reach out to managed
systems. Transports included are :term:`paramiko`,
:term:`ssh <SSH (Native)>` (using OpenSSH), and
:term:`local <Local Connection>`.
When
An optional conditional statement attached to a :term:`task <tasks>` that is used to
determine if the task should run or not. If the expression following
the ``when:`` keyword evaluates to false, the task will be ignored.
Vars (Variables)
As opposed to :term:`Facts`, variables are names of values (they can
be simple scalar values -- integers, booleans, strings) or complex
ones (dictionaries/hashes, lists) that can be used in templates and
:term:`playbooks`. They are declared things, not things that are
inferred from the remote system's current state or nature (which is
what Facts are).
YAML
Ansible does not want to force people to write programming language
code to automate infrastructure, so Ansible uses YAML to define
:term:`playbook <playbooks>` configuration languages and also variable
files. YAML is nice because it has a minimum of syntax and is very
clean and easy for people to skim. It is a good data format for
configuration files and humans, but also machine readable. Ansible's
usage of YAML stemmed from Michael DeHaan's first use of it inside of
Cobbler around 2006. YAML is fairly popular in the dynamic language
community and the format has libraries available for serialization in
many languages (Python, Perl, Ruby, etc.).
.. seealso::
:ref:`ansible_faq`
Frequently asked questions
:ref:`working_with_playbooks`
An introduction to playbooks
:ref:`playbooks_best_practices`
Tips and tricks for playbooks
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel
Reference in a new issue View git blame Copy permalink