mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
misc doc updates for 0.5
This commit is contained in:
parent
c963278c58
commit
6eb53ad540
7 changed files with 130 additions and 17 deletions
|
@ -72,6 +72,12 @@ Until then, to manage your entire site, simply execute all of your playbooks tog
|
||||||
You don't have to do this though. It's fine to select sections of your infrastructure to manage at a single time.
|
You don't have to do this though. It's fine to select sections of your infrastructure to manage at a single time.
|
||||||
You may wish to construct simple shell scripts to wrap calls to ansible-playbook.
|
You may wish to construct simple shell scripts to wrap calls to ansible-playbook.
|
||||||
|
|
||||||
|
Bundling Ansible Modules With Playbooks
|
||||||
|
+++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
In version 0.5 and later, if a playbook has a "./library" directory relative to it's YAML file, this directory can be used to add ansible modules that will automatically be in the ansible module path. This is a great way to keep modules that
|
||||||
|
go with a playbook together.
|
||||||
|
|
||||||
Miscellaneous Tips
|
Miscellaneous Tips
|
||||||
++++++++++++++++++
|
++++++++++++++++++
|
||||||
|
|
||||||
|
|
18
rst/faq.rst
18
rst/faq.rst
|
@ -50,8 +50,7 @@ vs Func?
|
||||||
Ansible uses SSH by default instead of SSL and custom daemons, and requires
|
Ansible uses SSH by default instead of SSL and custom daemons, and requires
|
||||||
no extra software to run on managed machines. You can also write modules
|
no extra software to run on managed machines. You can also write modules
|
||||||
in any language as long as they return JSON. Ansible's API, of course, is
|
in any language as long as they return JSON. Ansible's API, of course, is
|
||||||
heavily inspired by Func. Some features, like delegation hierarchies, are
|
heavily inspired by Func. Ansible also adds
|
||||||
not supported, but Ansible does have an async mode. Ansible also adds
|
|
||||||
a configuration management and multinode orchestration layer (:doc:`playbooks`)
|
a configuration management and multinode orchestration layer (:doc:`playbooks`)
|
||||||
that Func didn't have.
|
that Func didn't have.
|
||||||
|
|
||||||
|
@ -70,7 +69,7 @@ There is no central server subject to thundering herd problems, and Ansible is
|
||||||
also designed with multi-node deployment in mind from day-one -- something that is difficult
|
also designed with multi-node deployment in mind from day-one -- something that is difficult
|
||||||
for Puppet because of the pull architecture. Ansible is push based,
|
for Puppet because of the pull architecture. Ansible is push based,
|
||||||
so you can do things in an ordered fashion, addressing batches of servers
|
so you can do things in an ordered fashion, addressing batches of servers
|
||||||
at one time, and you do not have to contend with the DAG. It's also extensible in any language
|
at one time, and you do not have to contend with the dependency graph. It's also extensible in any language
|
||||||
and the source is designed so that you don't have to be an expert programmer to submit a patch.
|
and the source is designed so that you don't have to be an expert programmer to submit a patch.
|
||||||
|
|
||||||
Ansible's resources are heavily inspired by Puppet, with the "state" keyword being a more or less
|
Ansible's resources are heavily inspired by Puppet, with the "state" keyword being a more or less
|
||||||
|
@ -167,10 +166,13 @@ Ansible, it is not consuming any resources, and you don't have to contend
|
||||||
with a herd of machines all knocking at the door of your management server
|
with a herd of machines all knocking at the door of your management server
|
||||||
all at once.
|
all at once.
|
||||||
|
|
||||||
If you have 10,000 systems, running a single ansible playbook against all of
|
The SSH connection type (paramiko is the default, binary openssh is an option)
|
||||||
them probably isn't appropriate, which is why ansible-pull exists.
|
can also make use of "ControlMaster" features in SSH, which reuses network
|
||||||
|
connections.
|
||||||
|
|
||||||
This tool is designed for running out of git and cron, and can scale to any
|
If you have 10,000 systems, running a single ansible playbook against all of
|
||||||
|
them probably isn't appropriate, which is why ansible-pull exists. This tool
|
||||||
|
is designed for running out of git and cron, and can scale to any
|
||||||
number of hosts. Ansible-pull uses local connections versus SSH, but can be
|
number of hosts. Ansible-pull uses local connections versus SSH, but can be
|
||||||
easily bootstrapped or reconfigured just using SSH. There is more information
|
easily bootstrapped or reconfigured just using SSH. There is more information
|
||||||
available about this in the :doc:`playbooks2` section. The self-bootstrapping
|
available about this in the :doc:`playbooks2` section. The self-bootstrapping
|
||||||
|
@ -182,8 +184,8 @@ If you'd like to discuss scaling strategies further, please hop on the mailing l
|
||||||
Are transports other than SSH supported?
|
Are transports other than SSH supported?
|
||||||
++++++++++++++++++++++++++++++++++++++++
|
++++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
Currently SSH and local connections are supported. In 0.5, we'll also be including
|
Currently SSH (you can choose between paramiko or the openssh binaries)
|
||||||
a faster SSH transport. The interface is actually pluggable so a
|
and local connections are supported. The interface is actually pluggable so a
|
||||||
small patch could bring transport over message bus or XMPP as an option.
|
small patch could bring transport over message bus or XMPP as an option.
|
||||||
|
|
||||||
Stop by the mailing list if you have ideas. The connection-specific parts of Ansible
|
Stop by the mailing list if you have ideas. The connection-specific parts of Ansible
|
||||||
|
|
|
@ -21,7 +21,7 @@ also need:
|
||||||
|
|
||||||
* ``python-simplejson``
|
* ``python-simplejson``
|
||||||
|
|
||||||
NOTE: Ansible 0.4 will have ways to remote bootstrap this, using Ansible itself. Stay tuned.
|
(Note that even that's not quite true. Ansible's "raw" module (for executing commands in a quick and dirty way) and the copy module -- some of the most basic features in ansible don't even need that. So technically, you can use Ansible to install python-simplejson using the raw module, which then allows you to use everything else. That's jumping ahead though.)
|
||||||
|
|
||||||
Python 2.6 EPEL instructions for RHEL and CentOS 5
|
Python 2.6 EPEL instructions for RHEL and CentOS 5
|
||||||
``````````````````````````````````````````````````
|
``````````````````````````````````````````````````
|
||||||
|
@ -128,6 +128,24 @@ project page:
|
||||||
|
|
||||||
* `Ansible/downloads <https://github.com/ansible/ansible/downloads>`_
|
* `Ansible/downloads <https://github.com/ansible/ansible/downloads>`_
|
||||||
|
|
||||||
|
Choosing Between Paramiko and Native SSH
|
||||||
|
````````````````````````````````````````
|
||||||
|
|
||||||
|
By default, ansible uses paramiko to talk to managed nodes over SSH. Paramiko is fast, works
|
||||||
|
very transparently, requires no configuration, and is a good choice for most users.
|
||||||
|
However, it does not support some advanced SSH features that folks will want to use.
|
||||||
|
|
||||||
|
Starting in version 0.5, if you want to leverage more advanced SSH features (such as Kerberized SSH or jump hosts),
|
||||||
|
pass the flag "--connection=ssh" to any ansible command, or set the
|
||||||
|
ANSIBLE_TRANSPORT environment variable to 'ssh'. This will cause Ansible to use openssh
|
||||||
|
tools instead.
|
||||||
|
|
||||||
|
If ANSIBLE_SSH_ARGS are not set, ansible will try to use some sensible ControlMaster options
|
||||||
|
by default. You are free to override this environment variable, but should still pass ControlMaster
|
||||||
|
options to ensure performance of this transport. With ControlMaster in use, both transports
|
||||||
|
are roughly the same speed. Without CM, the binary ssh transport is signficantly slower.
|
||||||
|
|
||||||
|
If none of this makes sense to you, the default paramiko option is probably fine.
|
||||||
|
|
||||||
Your first commands
|
Your first commands
|
||||||
```````````````````
|
```````````````````
|
||||||
|
@ -146,10 +164,24 @@ Set up SSH agent to avoid retyping passwords::
|
||||||
ssh-agent bash
|
ssh-agent bash
|
||||||
ssh-add ~/.ssh/id_rsa
|
ssh-add ~/.ssh/id_rsa
|
||||||
|
|
||||||
|
(Depending on your setup, you may wish to ansible's --private-key-file option to specify a pem file instead)
|
||||||
|
|
||||||
Now ping all your nodes::
|
Now ping all your nodes::
|
||||||
|
|
||||||
ansible all -m ping
|
ansible all -m ping
|
||||||
|
|
||||||
|
If you want to access machines remotely as a different user than root, you will want to
|
||||||
|
specify the '-u' option to ansible. If you would like to access sudo mode, there are also flags to do that::
|
||||||
|
|
||||||
|
# as bruce
|
||||||
|
ansible all -m ping -u bruce
|
||||||
|
|
||||||
|
# as bruce, sudoing to root
|
||||||
|
ansible all -m ping -u bruce --sudo
|
||||||
|
|
||||||
|
# as bruce, sudoing to batman
|
||||||
|
ansible all -m ping -u bruce --sudo --sudo-user batman
|
||||||
|
|
||||||
Now run a live command on all of your nodes::
|
Now run a live command on all of your nodes::
|
||||||
|
|
||||||
ansible all -a "/bin/echo hello"
|
ansible all -a "/bin/echo hello"
|
||||||
|
|
|
@ -6,8 +6,8 @@ Ansible is a radically simple model-driven configuration management, deployment,
|
||||||
and command execution framework. Other tools in this space have been too
|
and command execution framework. Other tools in this space have been too
|
||||||
complicated for too long, require too much bootstrapping, and have too
|
complicated for too long, require too much bootstrapping, and have too
|
||||||
much learning curve. Ansible is dead simple and painless to extend.
|
much learning curve. Ansible is dead simple and painless to extend.
|
||||||
For comparison, Puppet and Chef have about 60k lines of code.
|
For comparison, Puppet and Chef have about 60k lines of code.
|
||||||
Ansible's core is a little over 1000 lines.
|
Ansible's core is a little over 2000 lines..
|
||||||
|
|
||||||
Ansible isn't just for idempotent configuration -- it's also great for ad-hoc
|
Ansible isn't just for idempotent configuration -- it's also great for ad-hoc
|
||||||
tasks, quickly firing off commands against nodes. See :doc:`examples`.
|
tasks, quickly firing off commands against nodes. See :doc:`examples`.
|
||||||
|
@ -68,6 +68,7 @@ Features
|
||||||
* Dead simple setup
|
* Dead simple setup
|
||||||
* Super fast & parallel by default
|
* Super fast & parallel by default
|
||||||
* No server or client daemons; use existing SSHd out of the box
|
* No server or client daemons; use existing SSHd out of the box
|
||||||
|
* Supports Kerberized SSH, jump hosts, forwarding, etc
|
||||||
* No additional software required on client boxes
|
* No additional software required on client boxes
|
||||||
* Can be easily run from a checkout, no installation required
|
* Can be easily run from a checkout, no installation required
|
||||||
* Modules are idempotent, but you can also easily use shell commands
|
* Modules are idempotent, but you can also easily use shell commands
|
||||||
|
|
|
@ -73,8 +73,56 @@ Example action from Ansible :doc:`playbooks`::
|
||||||
apt pkg=foo=1.00 state=installed
|
apt pkg=foo=1.00 state=installed
|
||||||
apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes
|
apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes
|
||||||
|
|
||||||
|
. _assemble:
|
||||||
|
|
||||||
|
assemble
|
||||||
|
````````
|
||||||
|
|
||||||
|
(new in 0.5) Assembles a configuration file from fragments. Often a particular program will take a single configuration file
|
||||||
|
and does not support a conf.d style structure where it is easy to build up the configuration from multiple sources.
|
||||||
|
Assmeble will take a directory of files that have already been transferred to the system, and concatenate them
|
||||||
|
together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea
|
||||||
|
"fragments".
|
||||||
|
|
||||||
|
*src*:
|
||||||
|
|
||||||
|
* An already existing directory full of source files.
|
||||||
|
|
||||||
|
*dest*:
|
||||||
|
|
||||||
|
* A file to create using the concatenation of all of the source files.
|
||||||
|
|
||||||
|
Example action from Ansible :doc:`playbooks`::
|
||||||
|
|
||||||
|
assemble src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
|
||||||
|
|
||||||
|
|
||||||
|
_authorized_key:
|
||||||
|
|
||||||
|
authorized_key
|
||||||
|
``````````````
|
||||||
|
|
||||||
|
(new in 0.5). Adds or removes an authorized key for a user from a remote host.
|
||||||
|
|
||||||
|
*user*:
|
||||||
|
|
||||||
|
* Name of the user who access is being granted or remoted to.
|
||||||
|
|
||||||
|
*state*:
|
||||||
|
|
||||||
|
* Either 'absent' or 'present', this is whether the given key should be in the authorized keys file or not.
|
||||||
|
|
||||||
|
*key*:
|
||||||
|
|
||||||
|
* The actual key, as a string.
|
||||||
|
|
||||||
|
Example action from Ansible :doc:`playbooks`::
|
||||||
|
|
||||||
|
authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"
|
||||||
|
|
||||||
.. _command:
|
.. _command:
|
||||||
|
|
||||||
|
|
||||||
command
|
command
|
||||||
```````
|
```````
|
||||||
|
|
||||||
|
@ -565,7 +613,11 @@ Creates user accounts, manipulates existing user accounts, and removes user acco
|
||||||
*createhome*:
|
*createhome*:
|
||||||
|
|
||||||
* Whether to create the user's home directory. Takes 'yes', or 'no'. The default is 'yes'.
|
* Whether to create the user's home directory. Takes 'yes', or 'no'. The default is 'yes'.
|
||||||
|
|
||||||
|
*home=*:
|
||||||
|
|
||||||
|
* Specifies where the user's home directory should be, if not in /home/$username.
|
||||||
|
|
||||||
*password*:
|
*password*:
|
||||||
|
|
||||||
* Sets the user's password to this crypted value. Pass in a result from crypt. See the users example in the github examples directory for what this looks like in a playbook.
|
* Sets the user's password to this crypted value. Pass in a result from crypt. See the users example in the github examples directory for what this looks like in a playbook.
|
||||||
|
|
|
@ -67,6 +67,10 @@ with the aforementioned bracket headers in the inventory file::
|
||||||
webservers
|
webservers
|
||||||
webservers:dbservers
|
webservers:dbservers
|
||||||
|
|
||||||
|
In 0.5 and later, you can exclude groups as well, for instance, all webservers not in Phoenix::
|
||||||
|
|
||||||
|
webservers:!phoenix
|
||||||
|
|
||||||
Individual host names (or IPs), but not groups, can also be referenced using
|
Individual host names (or IPs), but not groups, can also be referenced using
|
||||||
wildcards::
|
wildcards::
|
||||||
|
|
||||||
|
@ -77,13 +81,13 @@ It's also ok to mix wildcard patterns and groups at the same time::
|
||||||
|
|
||||||
one*.com:dbservers
|
one*.com:dbservers
|
||||||
|
|
||||||
|
|
||||||
Easy enough. See :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
|
Easy enough. See :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
|
||||||
|
|
||||||
Host Variables
|
Host Variables
|
||||||
++++++++++++++
|
++++++++++++++
|
||||||
|
|
||||||
Using the 0.4 branch of Ansible, it is easy to assign variables to hosts that will be used
|
It is easy to assign variables to hosts that will be used later in playbooks::
|
||||||
later in playbooks::
|
|
||||||
|
|
||||||
[atlanta]
|
[atlanta]
|
||||||
host1 http_port=80 maxRequestsPerChild=808
|
host1 http_port=80 maxRequestsPerChild=808
|
||||||
|
@ -93,7 +97,7 @@ later in playbooks::
|
||||||
Group Variables
|
Group Variables
|
||||||
+++++++++++++++
|
+++++++++++++++
|
||||||
|
|
||||||
Using the 0.4 branch of Ansible, variables can also be applied to an entire group at once::
|
Variables can also be applied to an entire group at once::
|
||||||
|
|
||||||
[atlanta]
|
[atlanta]
|
||||||
host1
|
host1
|
||||||
|
@ -137,7 +141,7 @@ variables to groups. These variables can be used by /usr/bin/ansible-playbook,
|
||||||
YAML Inventory Format
|
YAML Inventory Format
|
||||||
+++++++++++++++++++++
|
+++++++++++++++++++++
|
||||||
|
|
||||||
For people using 0.3, or those that prefer to use it, the inventory file can also be expressed in
|
For that prefer to use it, the inventory file can also be expressed in
|
||||||
YAML::
|
YAML::
|
||||||
|
|
||||||
---
|
---
|
||||||
|
@ -175,6 +179,9 @@ YAML::
|
||||||
vars:
|
vars:
|
||||||
- asdf: 1234
|
- asdf: 1234
|
||||||
|
|
||||||
|
Tip: If you ever have two python interpreters on a system, set a variable called 'ansible_python_interpreter' to
|
||||||
|
the Python interpreter path you would like to use. (This is available in version 0.5 and later)
|
||||||
|
|
||||||
Tip: Be sure to start your YAML file with the YAML record designator ``---``.
|
Tip: Be sure to start your YAML file with the YAML record designator ``---``.
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
|
@ -103,7 +103,7 @@ These variables can be used later in the playbook like this::
|
||||||
|
|
||||||
The later is useful in the event you need to do something like ${other}_concatenated_value.
|
The later is useful in the event you need to do something like ${other}_concatenated_value.
|
||||||
|
|
||||||
In templates, the full power of the Jinja2 templating language is also available, which looks like this::
|
The full power of the Jinja2 templating language is also available (note: in 0.4, this is only true inside of templates), which looks like this::
|
||||||
|
|
||||||
{{ varname }}
|
{{ varname }}
|
||||||
|
|
||||||
|
@ -298,6 +298,19 @@ Let's run a playbook using a parallelism level of 10::
|
||||||
|
|
||||||
ansible-playbook playbook.yml -f 10
|
ansible-playbook playbook.yml -f 10
|
||||||
|
|
||||||
|
Tips and Tricks
|
||||||
|
```````````````
|
||||||
|
|
||||||
|
Look at the bottom of the playbook execution for a summary of the nodes that were executed
|
||||||
|
and how they performed. General failures and fatal "unreachable" communication attempts are
|
||||||
|
kept seperate in the counts.
|
||||||
|
|
||||||
|
If you ever want to see detailed output from successful modules as well as unsuccessful ones,
|
||||||
|
use the '--verbose' flag. This is available in Ansible 0.5 and later.
|
||||||
|
|
||||||
|
Also, in version 0.5 and later, Ansible playbook output is vastly upgraded if the cowsay
|
||||||
|
package is installed. Try it!
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
||||||
:doc:`YAMLSyntax`
|
:doc:`YAMLSyntax`
|
||||||
|
|
Loading…
Reference in a new issue