From 111b3578d652f7ea0e89fd799f2d33833a9f710b Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Fri, 4 Oct 2013 13:27:19 -0400 Subject: [PATCH] add more indexes, AWX blurb. --- docsite/latest/rst/developing_plugins.rst | 18 ++++++++- docsite/latest/rst/faq.rst | 48 ++++++++++++++++++++--- docsite/latest/rst/guide_aws.rst | 22 +++++++++++ docsite/latest/rst/index.rst | 31 ++++++++++++++- 4 files changed, 110 insertions(+), 9 deletions(-) diff --git a/docsite/latest/rst/developing_plugins.rst b/docsite/latest/rst/developing_plugins.rst index cf6a1a6275..7247f41f7f 100644 --- a/docsite/latest/rst/developing_plugins.rst +++ b/docsite/latest/rst/developing_plugins.rst @@ -7,6 +7,8 @@ in ansible and were most convient 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. +.. _developing_connection_type_plugins: + Connection Type Plugins ----------------------- @@ -20,6 +22,8 @@ directory. The value of 'smart' for a connection allows selection of paramiko More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/connection_plugins and figure things out pretty easily. +.. _developing_lookup_plugins: + Lookup Plugins -------------- @@ -28,6 +32,8 @@ Language constructs like "with_fileglob" and "with_items" are implemented via lo More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/lookup_plugins and figure things out pretty easily. +.. _developing_vars_plugins: + Vars Plugins ------------ @@ -40,6 +46,8 @@ things out pretty easily. If you find yourself wanting to write a vars_plugin, it's more likely you should write an inventory script instead. +.. _developing_filter_plugins: + Filter Plugins -------------- @@ -47,12 +55,15 @@ If you want more Jinja2 filters available in a Jinja2 template (filters like to_ Jump into lib/ansible/runner/filter_plugins/ for details. +.. _developing_callbacks: Callbacks --------- Callbacks are one of the more interesting plugin types. Adding additional callback plugins to Ansible allows for adding new behaviors when responding to events. +.. _callback_examples: + Examples ++++++++ @@ -64,23 +75,26 @@ when playbooks complete. The 'osx_say' callback provided is particularly entertaining -- it will respond with computer synthesized speech on OS X in relation to playbook events, and is guaranteed to entertain and/or annoy coworkers. +.. _configuring_callbacks: + Configuring +++++++++++ To active a callback drop it in a callback directory as configured in ansible.cfg. +.. _callback_development: + Development +++++++++++ More information will come later, though see the source of any of the existing callbacks and you should be able to get started quickly. They should be reasonably self explanatory. +.. _distributing_plugins: Distributing Plugins -------------------- -.. versionadded:: 0.8 - Plugins are loaded from both Python's site_packages (those that ship with ansible) and a configured plugins directory, which defaults to /usr/share/ansible/plugins, in a subfolder for each plugin type:: diff --git a/docsite/latest/rst/faq.rst b/docsite/latest/rst/faq.rst index d736252f8c..f4c82d2d3e 100644 --- a/docsite/latest/rst/faq.rst +++ b/docsite/latest/rst/faq.rst @@ -6,6 +6,8 @@ Here are some commonly-asked questions and their answers. .. contents:: :depth: 2 +.. _users_and_ports: + How do I handle different machines needing different user accounts or ports to log in with? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -28,6 +30,7 @@ You can also dictate the connection type to be used, if you want:: You may also wish to keep these in group variables instead, or file in them in a group_vars/ file. See the rest of the documentation for more information about how to organize variables. +.. _use_ssh: How do I get ansible to reuse connections, enable Kerberized SSH, or have Ansible pay attention to my local SSH config file? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -44,12 +47,16 @@ consider managing from a Fedora or openSUSE client even though you are managing We keep paramiko as the default as if you are first installing Ansible on an EL box, it offers a better experience for new users. +.. _ec2_cloud_performance: + How do I speed up management inside EC2? ++++++++++++++++++++++++++++++++++++++++ Don't try to manage a fleet of EC2 machines from your laptop. Connect to a management node inside EC2 first and run Ansible from there. +.. _python_interpreters: + How do I handle python pathing not having a Python 2.X in /usr/bin/python on a remote machine? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -71,6 +78,8 @@ Python 3.0 support will likely be addressed at a later point in time when usage Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time. +.. _use_roles: + What is the best way to make content reusable/redistributable? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -79,16 +88,15 @@ self contained, and works will with things like git submodules for sharing conte If some of these plugin types look strange to you, see the API documentation for more details about ways Ansible can be extended. +.. _configuration_file: + Where does the configuration file live and what can I configure in it? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Technically ansible doesn't need a configuration file, but OS packages are likely to include a default one in /etc/ansible/ansible.cfg -that you may customize. You can also install your own copy in ~/.ansible.cfg or keep a copy in a directory relative to your playbook named "ansible.cfg". -For what values you can use in this file, see `the configuration file on github `_. +See `intro_configuration`. -Generally you would configure the default module path or connection type here, among other things, though the defaults are usually -good enough for starting out. +.. _who_would_ever_want_to_disable_cowsay_but_ok_here_is_how: How do I disable cowsay? ++++++++++++++++++++++++ @@ -98,6 +106,8 @@ that you would like to work in a professional cow-free environment, you can eith export ANSIBLE_NOCOWS=1 +.. _browse_facts: + How do I see a list of all of the ansible\_ variables? ++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -107,6 +117,8 @@ Ansible by default gathers "facts" about the machines under management, and thes This will print out a dictionary of all of the facts that are available for that particular host. +.. _host_loops: + How do I loop over a list of hosts in a group, inside of a template? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -129,6 +141,8 @@ Then you can use the facts inside your template, like this:: {{ hostvars[host]['ansible_eth0']['ipv4']['address'] }} {% endfor %} +.. _file_recursion: + How do I copy files recursively onto a target host? +++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -144,6 +158,8 @@ Here is an example:: Note that you'll need passphrase-less SSH or ssh-agent set up to let rsync copy without prompting for a passphase or password. +.. _shell_env: + How do I access shell environment variables? ++++++++++++++++++++++++++++++++++++++++++++ @@ -157,20 +173,40 @@ environment variable on management machine:: If you need to set environment variables, see the Advanced Playbooks section about environments. +Ansible 1.4 will also make remote environment variables available via facts in the 'ansible_env' variable:: + + {{ ansible_env.SOME_VARIABLE }} + +.. _commercial_support: + Can I get training on Ansible or find commercial support? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Yes! See `AnsibleWorks.com `_ or email `info@ansibleworks.com `_. +.. _web_interface: + +Is there a web interface / REST API / etc? +++++++++++++++++++++++++++++++++++++++++++ + +Yes! AnsibleWorks makes a great product that makes Ansible even more powerful +and easy to use: `AnsibleWorks AWX ` + +.. _docs_contributions: + How do I submit a change to the documentation? ++++++++++++++++++++++++++++++++++++++++++++++ Great question! Documentation for Ansible is kept in the main project git repository, and complete instructions for contributing can be found in the docs README `viewable on GitHub `_. Thanks! +.. _i_dont_see_my_question: + I don't see my question here ++++++++++++++++++++++++++++ -See the "Resources" section of the documentation for a link to the IRC and Google Group. +We're happy to help. + +See the "Resources" section of the documentation home page for a link to the IRC and Google Group. diff --git a/docsite/latest/rst/guide_aws.rst b/docsite/latest/rst/guide_aws.rst index 7e04188bff..732b9ffec3 100644 --- a/docsite/latest/rst/guide_aws.rst +++ b/docsite/latest/rst/guide_aws.rst @@ -4,6 +4,8 @@ Amazon Web Services Guide .. contents:: :depth: 2 +.. _aws_intro: + Introduction ```````````` @@ -22,6 +24,8 @@ Requirements for the AWS modules are minimal. All of the modules require and ar You can also install it via pip if you want. +.. _aws_provisioning: + Provisioning ```````````` @@ -81,9 +85,13 @@ Rather than include configuration inline, you may also choose to just do it as a The method above ties the configuration of a host with the provisioning step. This isn't always ideal and leads us onto the next section. +:: _aws_advanced: + Advanced Usage `````````````` +:: _aws_host_inventory: + Host Inventory ++++++++++++++ @@ -99,6 +107,8 @@ You may wish to schedule a regular refresh of the inventory cache to accommodate Put this into a crontab as appropriate to make calls from your Ansible master server to the EC2 API endpoints and gather host information. The aim is to keep the view of hosts as up-to-date as possible, so schedule accordingly. Playbook calls could then also be scheduled to act on the refreshed hosts inventory after each refresh. This approach means that machine images can remain "raw", containing no payload and OS-only. Configuration of the workload is handled entirely by Ansible. +:: _aws_pull: + Pull Configuration ++++++++++++++++++ @@ -108,6 +118,8 @@ More information on pull-mode playbooks can be found `here `_ while reading along with the playbook documentation. These illustrate best practices as well as how to put many of the various concepts together. +.. ansibleworks_awx: + +Upgrading the Ansible Experience: AnsibleWorks AWX +`````````````````````````````````````````````````` + +`AnsibleWorks `_, who also sponsors the AnsibleWorks community, also produces 'AWX', which is a web-based tool 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. + +Find out more about AWX features and how to download it on the `AWX webpage `_. AWX +is free for usage for up to 10 nodes, and comes bundled with amazing support from AnsibleWorks. As you would expect, AWX is +installed using Ansible playbooks! + +.. _advanced_topics_in_playbooks: + Advanced Topics In Playbooks ```````````````````````````` @@ -87,7 +108,9 @@ these only if they seem relevant or useful to your environment. playbooks_lookups playbooks_prompts playbooks_tags - + +.. _detailed_guides: + Detailed Guides ``````````````` @@ -104,6 +127,8 @@ A chance to dive into some more topics in depth: Pending topics may include: Vagrant, Docker, Jenkins, Rackspace Cloud, Google Compute Engine, Linode/Digital Ocean, Continous Deployment, and more. +.. _community_information: + Community Information ````````````````````` @@ -113,6 +138,8 @@ other users, introducing new people to Ansible, or helping with the software or How to interact +.. _developer_information: + Developer Information ````````````````````` @@ -128,6 +155,8 @@ with other solutions in your environment. developing_plugins REST API +.. _misc: + Miscellaneous `````````````