diff --git a/docsite/latest/rst/index.rst b/docsite/latest/rst/index.rst index 1435e2ed45..0593eaba94 100644 --- a/docsite/latest/rst/index.rst +++ b/docsite/latest/rst/index.rst @@ -10,25 +10,22 @@ Welcome to the Ansible documentation! Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates. -Ansible's goals are foremost those of simplicity and ease of use. It also has a strong focus on security and reliability, featuring -a minimum of moving parts, usage of Open SSH for transport (with an accelerated socket mode as an alternative that uses SSH for key exchange), and a language that is designed around auditability by humans -- even those not familiar with the program. +Ansible's goals are foremost those of simplicity and maximum ease of use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of Open SSH for transport (with an accelerated socket mode as an alternative that uses SSH for key exchange), and a language that is designed around auditability by humans -- even those not familiar with the program. -Ansible manages machines in an agentless manner -- the intent here is to make things more reliable and -there are no additional open ports. This also means there is never a question of how to -upgrade the management software with the management software, or the problem of not being able to manage remote nodes because -management daemons are not yet installed or not currently running. As OpenSSH is one of the most peer reviewed open source components, the security exposure of using the tool is therefore also greatly reduced. Ansible is decentralized, and relies on your existing OS credentials to control access to remote machines, rather than just who can edit configuration recipes in source control. +Ansible manages machines in an agentless manner. There is never a question of how to +upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled. As OpenSSH is one of the most peer reviewed open source components, the security exposure of using the tool is greatly reduced. Ansible is decentralized -- it relies on your existing OS credentials to control access to remote machines; if needed it can easily connect with Kerberos, LDAP, and other centralized authentication management systems. You may be interested in reading about `some notable Ansible users `_. -This documentation covers the current released version of Ansible (1.3.X) and also some development version features (1.4). For recent features, in each section, the version of Ansible where the feature is added is indicated. Ansible produces a new major release approximately every 2 months. The core project moves somewhat conservatively, valuing simplicity in language design and setup, while the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release. - -Before we dive into playbooks, configuration management, deployment, and orchestration, we'll learn how to get Ansible installed and some basic concepts. We'll go over how to execute ad-hoc commands in parallel across your nodes using /usr/bin/ansible. We'll also see what sort of modules are available in Ansible's core (though you can also write your own, which we'll also show later). +This documentation covers the current released version of Ansible (1.3.X) and also some development version features (1.4). For recent features, in each section, the version of Ansible where the feature is added is indicated. AnsibleWorks releases a new major release of Ansible approximately every 2 months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup, while the community around new modules and plugins being developed and contributed moves very very quickly, typically adding 20 or so new modules in each release. .. _an_introduction: The Basics `````````` +Before we dive into the really fun parts -- playbooks, configuration management, deployment, and orchestration, we'll learn how to get Ansible installed and some basic concepts. We'll go over how to execute ad-hoc commands in parallel across your nodes using /usr/bin/ansible. We'll also see what sort of modules are available in Ansible's core (though you can also write your own, which we'll also show later). + .. toctree:: :maxdepth: 1 @@ -50,6 +47,7 @@ that will work on your platform. You may think of the module library as a toolb and playbooks as the instructions for buildilng something using those tools. .. toctree:: + :maxdepth: 1 modules .. _overview: @@ -69,6 +67,8 @@ Playbooks Playbooks are Ansible's configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process. +If Ansible modules are your the tools in your workshop, playbooks are your design plans. + At a basic level, playbooks can be used to manage configurations of and deployments to remote machines. At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way. While there's a lot of information here, there's no need to learn everything at once. You can start small and pick up more features diff --git a/docsite/latest/rst/modules.rst b/docsite/latest/rst/modules.rst index 823a7c7361..20a72a51d4 100644 --- a/docsite/latest/rst/modules.rst +++ b/docsite/latest/rst/modules.rst @@ -57,6 +57,25 @@ Let's see what's available in the Ansible module library, out of the box: .. include:: modules/_list.rst +.. _ansible_doc: + +Reading Module Documentation Locally +```````````````````````````````````` + +ansible-doc is a friendly command line tool that allows you to access module documentation locally. +It comes with Ansible. + +To list documentation for a particular module:: + + ansible-doc yum | less + +To list all modules available:: + + ansible-doc --list | less + +To access modules outside of the stock module path (such as custom modules that live in your playbook directory), +use the '--module-path' option to specify the directory where the module lives. + .. _writing_modules: Writing your own modules diff --git a/docsite/latest/rst/playbooks.rst b/docsite/latest/rst/playbooks.rst index 6b5cd02a87..dbe3504c21 100644 --- a/docsite/latest/rst/playbooks.rst +++ b/docsite/latest/rst/playbooks.rst @@ -325,6 +325,22 @@ Let's run a playbook using a parallelism level of 10:: .. _tips_and_tricks: + +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. + +Ansible-pull is a small script that will checkout a repo of configuration instructions from git, and then +run ansible-playbook against that content. + +Assuming you load balance your checkout location, ansible-pull scales essentially infinitely. + +Run 'ansible-pull --help' for details. + +There's also a ` https://github.com/ansible/ansible-examples/blob/master/language_features/ansible_pull.yml>`_ available to using ansible in push mode to configure ansible-pull via a crontab! + Tips and Tricks ```````````````