diff --git a/docs/man/man1/ansible-doc.1 b/docs/man/man1/ansible-doc.1 index 6ba3e058ec..041cf48099 100644 --- a/docs/man/man1/ansible-doc.1 +++ b/docs/man/man1/ansible-doc.1 @@ -1,13 +1,22 @@ '\" t .\" Title: ansible-doc -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 11/27/2013 +.\" Author: :doctype:manpage +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 05/26/2014 .\" Manual: System administration commands -.\" Source: Ansible 1.4.1 +.\" Source: Ansible 1.7 .\" Language: English .\" -.TH "ANSIBLE\-DOC" "1" "11/27/2013" "Ansible 1\&.4\&.1" "System administration commands" +.TH "ANSIBLE\-DOC" "1" "05/26/2014" "Ansible 1\&.7" "System administration commands" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- @@ -54,4 +63,10 @@ Ansible is released under the terms of the GPLv3 License\&. .sp \fBansible\-playbook\fR(1), \fBansible\fR(1), \fBansible\-pull\fR(1) .sp -Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/ +Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible +.SH "AUTHOR" +.PP +\fB:doctype:manpage\fR +.RS 4 +Author. +.RE diff --git a/docs/man/man1/ansible-galaxy.1 b/docs/man/man1/ansible-galaxy.1 index af2285121a..5bac353505 100644 --- a/docs/man/man1/ansible-galaxy.1 +++ b/docs/man/man1/ansible-galaxy.1 @@ -1,13 +1,13 @@ '\" t .\" Title: ansible-galaxy .\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 03/16/2014 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 05/26/2014 .\" Manual: System administration commands -.\" Source: Ansible 1.6 +.\" Source: Ansible 1.7 .\" Language: English .\" -.TH "ANSIBLE\-GALAXY" "1" "03/16/2014" "Ansible 1\&.6" "System administration commands" +.TH "ANSIBLE\-GALAXY" "1" "05/26/2014" "Ansible 1\&.7" "System administration commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/docs/man/man1/ansible-playbook.1 b/docs/man/man1/ansible-playbook.1 index f435627f79..63f8904f0c 100644 --- a/docs/man/man1/ansible-playbook.1 +++ b/docs/man/man1/ansible-playbook.1 @@ -1,13 +1,13 @@ '\" t .\" Title: ansible-playbook .\" Author: :doctype:manpage -.\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 02/12/2014 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 05/26/2014 .\" Manual: System administration commands -.\" Source: Ansible 1.5 +.\" Source: Ansible 1.7 .\" Language: English .\" -.TH "ANSIBLE\-PLAYBOOK" "1" "02/12/2014" "Ansible 1\&.5" "System administration commands" +.TH "ANSIBLE\-PLAYBOOK" "1" "05/26/2014" "Ansible 1\&.7" "System administration commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -91,72 +91,12 @@ Prompt for the password to use for playbook plays that request sudo access, if a Desired sudo user (default=root)\&. .RE .PP -\fB\-S\fR, \fB\-\-su\fR -.RS 4 -run operations with su\&. -.RE -.PP -\fB\-\-ask\-su\-pass\fR -.RS 4 -Prompt for the password to use for playbook plays that request su access, if any\&. -.RE -.PP -\fB\-R\fR, \fISU_USER\fR, \fB\-\-sudo\-user=\fR\fISU_USER\fR -.RS 4 -Desired su user (default=root)\&. -.RE -.PP -\fB\-\-ask\-vault\-pass\fR -.RS 4 -Ask for vault password\&. -.RE -.PP -\fB\-\-vault\-password\-file=\fR\fIVAULT_PASSWORD_FILE\fR -.RS 4 -Vault password file\&. -.RE -.PP -\fB\-\-force\-handlers\fR -.RS 4 -Run play handlers even if a task fails\&. -.RE -.PP -\fB\-\-list\-hosts\fR -.RS 4 -Outputs a list of matching hosts without executing anything else\&. -.RE -.PP -\fB\-\-list\-tasks\fR -.RS 4 -List all tasks that would be executed\&. -.RE -.PP -\fB\-\-start\-at\-task=\fR\fISTART_AT\fR -.RS 4 -Start the playbook at the task matching this name\&. -.RE -.PP -\fB\-\-step\fR -.RS 4 -one-step-at-a-time: confirm each task before running\&. -.RE -.PP -\fB\-\-syntax\-check\fR -.RS 4 -Perform a syntax check on the playbook, but do not execute it\&. -.RE -.PP -\fB\-\-private\-key\fR -.RS 4 -Use this file to authenticate the connection\&. -.RE -.PP -\fB\-t\fR, \fITAGS\fR, \fB\fI\-\-tags=\fR\fR\fB\*(AqTAGS\fR +\fB\-t\fR, \fITAGS\fR, \fB\-\-tags=\fR\fITAGS\fR .RS 4 Only run plays and tasks tagged with these values\&. .RE .PP -\fB\fI\-\-skip\-tags=\fR\fR\fB\*(AqSKIP_TAGS\fR +\fB\-\-skip\-tags=\fR\fISKIP_TAGS\fR .RS 4 Only run plays and tasks whose tags do not match these values\&. .RE @@ -207,13 +147,6 @@ is mostly useful for crontab or kickstarts\&. .RS 4 Further limits the selected host/group patterns\&. .RE - -.PP -\fB\-\-version\fR -.RS 4 -Show program's version number and exit\&. -.RE - .SH "ENVIRONMENT" .sp The following environment variables may be specified\&. diff --git a/docs/man/man1/ansible-pull.1 b/docs/man/man1/ansible-pull.1 index fb727631eb..58029eabb8 100644 --- a/docs/man/man1/ansible-pull.1 +++ b/docs/man/man1/ansible-pull.1 @@ -2,12 +2,21 @@ .\" Title: ansible .\" Author: :doctype:manpage .\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 01/02/2014 +.\" Date: 05/26/2014 .\" Manual: System administration commands -.\" Source: Ansible 1.5 +.\" Source: Ansible 1.7 .\" Language: English .\" -.TH "ANSIBLE" "1" "01/03/2014" "Ansible 1\&.5" "System administration commands" +.TH "ANSIBLE" "1" "05/26/2014" "Ansible 1\&.7" "System administration commands" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- @@ -94,7 +103,7 @@ Ansible is released under the terms of the GPLv3 License\&. .sp \fBansible\fR(1), \fBansible\-playbook\fR(1), \fBansible\-doc\fR(1) .sp -Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/ +Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible .SH "AUTHOR" .PP \fB:doctype:manpage\fR diff --git a/docs/man/man1/ansible-vault.1 b/docs/man/man1/ansible-vault.1 index cced9f1bcf..f353e3269f 100644 --- a/docs/man/man1/ansible-vault.1 +++ b/docs/man/man1/ansible-vault.1 @@ -1,13 +1,13 @@ '\" t .\" Title: ansible-vault .\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 03/17/2014 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 05/26/2014 .\" Manual: System administration commands -.\" Source: Ansible 1.6 +.\" Source: Ansible 1.7 .\" Language: English .\" -.TH "ANSIBLE\-VAULT" "1" "03/17/2014" "Ansible 1\&.6" "System administration commands" +.TH "ANSIBLE\-VAULT" "1" "05/26/2014" "Ansible 1\&.7" "System administration commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1 index 99b0fd37ef..233428782e 100644 --- a/docs/man/man1/ansible.1 +++ b/docs/man/man1/ansible.1 @@ -1,13 +1,22 @@ '\" t .\" Title: ansible -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 11/27/2013 +.\" Author: :doctype:manpage +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 05/26/2014 .\" Manual: System administration commands -.\" Source: Ansible 1.4.1 +.\" Source: Ansible 1.7 .\" Language: English .\" -.TH "ANSIBLE" "1" "11/27/2013" "Ansible 1\&.4\&.1" "System administration commands" +.TH "ANSIBLE" "1" "05/26/2014" "Ansible 1\&.7" "System administration commands" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- @@ -25,7 +34,7 @@ ansible \- run a command somewhere else ansible [\-f forks] [\-m module_name] [\-a args] .SH "DESCRIPTION" .sp -\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&. +\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq over SSH\&. .SH "ARGUMENTS" .PP \fBhost\-pattern\fR @@ -73,7 +82,7 @@ search path to load modules from\&. The default is \fI/usr/share/ansible\fR\&. This can also be set with the ANSIBLE_LIBRARY environment variable\&. .RE .PP -\fB\-a\fR \'\fIARGUMENTS\fR\', \fB\-\-args=\fR\'\fIARGUMENTS\fR\' +\fB\-a\fR \*(Aq\fIARGUMENTS\fR\*(Aq, \fB\-\-args=\fR\*(Aq\fIARGUMENTS\fR\*(Aq .RS 4 The \fIARGUMENTS\fR @@ -165,7 +174,7 @@ Further limits hosts with a regex pattern\&. .sp Ansible stores the hosts it can potentially operate on in an inventory file\&. The syntax is one host per line\&. Groups headers are allowed and are included on their own line, enclosed in square brackets that start the line\&. .sp -Ranges of hosts are also supported\&. For more information and additional options, see the documentation on http://ansible\&.github\&.com/\&. +Ranges of hosts are also supported\&. For more information and additional options, see the documentation on http://docs\&.ansible\&.com/\&. .SH "FILES" .sp /etc/ansible/hosts \(em Default inventory file @@ -196,4 +205,10 @@ Ansible is released under the terms of the GPLv3 License\&. .sp \fBansible\-playbook\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1) .sp -Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/ +Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible +.SH "AUTHOR" +.PP +\fB:doctype:manpage\fR +.RS 4 +Author. +.RE diff --git a/docsite/rst/guide_aws.rst b/docsite/rst/guide_aws.rst index 39f2440f19..a404c6c1e5 100644 --- a/docsite/rst/guide_aws.rst +++ b/docsite/rst/guide_aws.rst @@ -309,7 +309,7 @@ In the future look here for more topics. An introduction to playbooks :doc:`playbooks_delegation` Delegation, useful for working with loud balancers, clouds, and locally executed steps. - `User Mailing List `_ + `User Mailing List `_ Have a question? Stop by the google group! `irc.freenode.net `_ #ansible IRC chat channel diff --git a/docsite/rst/index.rst b/docsite/rst/index.rst index 14f0e326f4..b4eb978967 100644 --- a/docsite/rst/index.rst +++ b/docsite/rst/index.rst @@ -34,6 +34,7 @@ This documentation covers the current released version of Ansible (1.5.3) and al tower community galaxy + test_strategies faq glossary YAMLSyntax diff --git a/docsite/rst/test_strategies.rst b/docsite/rst/test_strategies.rst new file mode 100644 index 0000000000..c713c6f756 --- /dev/null +++ b/docsite/rst/test_strategies.rst @@ -0,0 +1,262 @@ +Testing Strategies +================== + +.. _testing_intro: + +Integrating Testing With Ansible Playbooks +`````````````````````````````````````````` + +Many times, people ask, "how can I best integrate testing with Ansible playbooks?" There are many options. Ansible is actually designed +to be a "fail-fast" and ordered system, therefore it makes it easy to embed testing directly in Ansible playbooks. In this chapter, +we'll go into some patterns for integrating tests of infrastructure and discuss the right level of testing that may be appropriate. + +.. note:: This is a chapter about testing the application you are deploying, not the chapter on how to test ansible modules during development. For that content, please hop over to the Development section. + +By incorporating a degree of testing into your deployment workflow, there will be less surprises when code hits production, and in many cases, +tests can be leveraged in production to prevent failed updates from migrating across an entire installation. Since it's push-based and +also makes it very easy to run steps on the localhost or testing servers, Ansible lets you insert as many checks and balances into your upgrade workflow as you would like to insert. + +The Right Level of Testing +`````````````````````````` + +Ansible resources are models of desired-state. As such, it should not be neccessary to test that services are running, packages are +installed, or other such things. Ansible is the system that will ensure these things are declaratively true. Instead, assert these +things into your playbooks. + +.. code-block:: yaml + + tasks: + - service: name=foo state=running enabled=yes + +If you think the service may not be running, the best thing to do is request it to be running. If the service fails to start, Ansible +will yell appropriately. (This should not be confused with whether the service is doing something functional, which we'll show more about how to +do later). + +Check Mode As A Drift Test +`````````````````````````` + +In the above setup, `--check` mode in Ansible can be used as a layer of testing as well. If running a deployment playbook against an existing system, using the `--check` flag to the ansible command will report if Ansible thinks it would have had to have made any changes to bring the system into a desired state. + +This can let you know up front if there is any need to deploy onto the given system. Ordinarily scripts and commands don't run in check mode, so if you +want certain steps to always execute in check mode, such as calls to the script module, add the 'always_run' flag:: + + + roles: + - webserver + + tasks: + - script: verify.sh + always_run: True + +Modules That Are Useful for Testing +``````````````````````````````````` + +Certain playbook modules are particularly good for testing. Below is an example that ensures a port is open:: + + tasks: + + - wait_for: host={{ inventory_hostname }} port=22 + delegate_to: localhost + +Here's an example of using the URI module to make sure a web service returns:: + + tasks: + + - action: uri url=http://www.example.com return_content=yes + register: webpage + + - fail: msg='service is not happy' + when: "'AWESOME' not in webpage.content" + +It's easy to push an arbitrary script (in any language) on a remote host and the script will automatically fail if it has a non-zero return code:: + + tasks: + + - script: test_script1 + - script: test_script2 --parameter value --parameter2 value + +If using roles (you should be, roles are great!), scripts pushed by the script module can live in the 'files/' directory of a role. + +And the assert module makes it very easily to validate various kinds of truth:: + + tasks: + + - shell: /usr/bin/some-command --parameter value + register: cmd_result + + - assert: + that: + - "'not ready' not in cmd_result.stderr" + - "'gizmo enabled' in cmd_result.stdout" + +Should you feel the need to test for existance of files that are not declaratively set by your ansible configuration, the 'stat' module is a great choice:: + + tasks: + + - stat: path=/path/to/something + register: p + + - assert: + that: + - p.stat.exists and p.stat.isdir + + +As mentioned above, there's no need to check things like the return codes of commands. Ansible is checking them automatically. +Rather than checking for a user to exist, consider using the user module to make it exist. + +Ansible is a fail-fast system, so when there is an error creating that user, it will stop the playbook run. You do not have +to check up behind it. + +Testing Lifecycle +````````````````` + +If writing some degree of basic validation of your application into your playbooks, they will run every time you deploy. + +As such, deploying into a local development VM and a state environment will both validate that things are according to plan +ahead of your production deploy. + +Your workflow may be something like this:: + + - Use the same playbook all the time with embedded tests in development + - Use the playbook to deploy to a stage environment (with the same playbooks) that simulates production + - Run an integration test battery written by your QA team against stage + - Deploy to production, with the same integrated tests. + +Something like an integration test battery should be written by your QA team if you are a production webservice. This would include +things like Selenium tests or automated API tests and would usually not be something embedded into your ansible playbooks. + +However, it does make sense to include some basic health checks into your playbooks, and in some cases it may be possible to run +a subset of the QA battery against remote nodes. This is what the next section covers. + +Integrating Testing With Rolling Updates +```````````````````````````````````````` + +If you have read into :doc:`playbooks_delegation` it may quickly become apparent that the rolling update pattern can be extended, and you +can use the success or failure of the playbook run to decide whether to add a machine into a load balancer or not. + +This is the great culmination of embedded tests:: + + --- + + - hosts: webservers + serial: 5 + + pre_tasks: + + - name: take out of load balancer pool + command: /usr/bin/take_out_of_pool {{ inventory_hostname }} + delegate_to: 127.0.0.1 + + roles: + + - common + - webserver + - apply_testing_checks + + post_tasks: + + - name: add back to load balancer pool + command: /usr/bin/add_back_to_pool {{ inventory_hostname }} + delegate_to: 127.0.0.1 + +Of course in the above, the "take out of the pool" and "add back" steps would be replaced with a call to a Ansible load balancer +module or appropriate shell command. You might also have steps that use a monitoring module to start and end an outage window +for the machine. + +However, what you can see from the above is that tests are used as a gate -- if the "apply_testing_checks" step is not performed, +the machine will not go back into the pool. + +Read the delegation chapter about "max_fail_percentage" and you can also control how many failing tests will stop a rolling update +from proceeding. + +This above approach can also be modified to run a step from a testing machine remotely against a machine:: + + --- + + - hosts: webservers + serial: 5 + + pre_tasks: + + - name: take out of load balancer pool + command: /usr/bin/take_out_of_pool {{ inventory_hostname }} + delegate_to: 127.0.0.1 + + roles: + + - common + - webserver + + tasks: + - script: /srv/qa_team/app_testing_script.sh --server {{ inventory_hostname }} + delegate_to: testing_server + + post_tasks: + + - name: add back to load balancer pool + command: /usr/bin/add_back_to_pool {{ inventory_hostname }} + delegate_to: 127.0.0.1 + +In the above example, a script is run from the testing server against a remote node prior to bringing it back into +the pool. + +In the event of a problem, fix the few servers that fail using Ansible's automatically generated +retry file to repeat the deploy on just those servers. + +Achieving Continous Deployment +`````````````````````````````` + +If desired, the above techniques may be extended to enable continuous deployment practices. + +The workflow may look like this:: + + - Write and use automation to deploy local development VMs + - Have a CI system like Jenkins deploy to a stage environment on every code change + - The deploy job calls testing scripts to pass/fail a build on every deploy + - If the deploy job succeeds, it runs the same deploy playbook against production inventory + +Some Ansible users use the above approach to deploy a half-dozen or dozen times an hour without taking all of their infrastructure +offline. A culture of automated QA is vital if you wish to get to this level. + +If you are still doing a large amount of manual QA, you should still make the decision on whether to deploy manually as well, but +it can still help to work in the rolling update patterns of the previous section and encorporate some basic health checks using +modules like 'script', 'stat', 'uri', and 'assert'. + +Conclusion +`````````` + +Ansible believes you should not need another framework to validate basic things of your infrastructure is true. This is the case +because ansible is an order-based system that will fail immediately on unhandled errors for a host, and prevent further configuration +of that host. This forces errors to the top and shows them in a summary at the end of the Ansible run. + +However, as Ansible is designed as a multi-tier orchestration system, it makes it very easy to incorporate tests into the end of +a playbook run, either using loose tasks or roles. When used with rolling updates, testing steps can decide whether to put a machine +back into a load balanced pool or not. + +Finally, because Ansible errors propogate all the way up to the return code of the ansible program itself, and Ansible by default +runs in an easy push-based mode, ansible is a great step to put into a build environment if you wish to use it to roll out systems +as part of a Continous Integration/Continous Delivery pipeline, as is covered in sections above. + +The focus should not be on infrastructure testing, but on application testing, so we strongly encourage getting together with your +QA team and ask what sort of tests would make sense to run every time you deploy development VMs, and which sort of tests they would like +to run against the stage environment on every deploy. Obviously at the development stage, unit tests are great too. But don't unit +tests your playbook. Ansible describes states of resources declaratively, so you don't have to. If there are cases where you want +to be sure of something though, that's great, and things like stat/assert are great go-to modules for that purpose. + +In all, testing is a very organizational and site-specific thing. Everybody should be doing it, but what makes the most sense for your +environment will vary with what you are deploying and who is using it -- but everyone benefits from a more robust and reliable deployment +system. + +.. seealso:: + + :doc:`modules` + All the documentation for Ansible modules + :doc:`playbooks` + An introduction to playbooks + :doc:`playbooks_delegation` + Delegation, useful for working with loud balancers, clouds, and locally executed steps. + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel +