From d3fa1c36a5f93cf2cff123478a9a0ebe0b5abb71 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Wed, 4 Jul 2012 17:47:04 -0400 Subject: [PATCH] docs build + formatting fix on the modules page --- YAMLSyntax.html | 2 +- api.html | 2 +- bestpractices.html | 12 +++++-- examples.html | 2 +- faq.html | 18 ++++++----- genindex.html | 2 +- gettingstarted.html | 32 +++++++++++++++++-- index.html | 12 +++++-- moduledev.html | 2 +- modules.html | 78 +++++++++++++++++++++++++++++++++++---------- patterns.html | 14 +++++--- playbooks.html | 15 +++++++-- playbooks2.html | 15 ++++++--- rst/modules.rst | 4 +-- search.html | 2 +- searchindex.js | 2 +- 16 files changed, 162 insertions(+), 52 deletions(-) diff --git a/YAMLSyntax.html b/YAMLSyntax.html index 09c4a90e28d..0329c54c679 100644 --- a/YAMLSyntax.html +++ b/YAMLSyntax.html @@ -275,7 +275,7 @@ languages:

© Copyright 2012 Michael DeHaan.
- Last updated on Jun 19, 2012.
+ Last updated on Jul 04, 2012.

diff --git a/api.html b/api.html index 3b9bcf1c946..4cb1f467866 100644 --- a/api.html +++ b/api.html @@ -359,7 +359,7 @@ a conf.d file appropriately or something similar. Who knows?

© Copyright 2012 Michael DeHaan.
- Last updated on Jun 19, 2012.
+ Last updated on Jul 04, 2012.

diff --git a/bestpractices.html b/bestpractices.html index 7df3a1b3442..daf491712da 100644 --- a/bestpractices.html +++ b/bestpractices.html @@ -150,6 +150,7 @@ s.parentNode.insertBefore(ga, s);
  • Best Practices
    • @@ -193,6 +194,7 @@ using the group variable system.

    Playbooks should be organized like this:

    (root of source control repository)
 
+    global_vars.yml # variables for all playbooks
     acme/           # each playbook has a directory
 
         setup.yml   # playbook to manage the service
@@ -206,7 +208,7 @@ using the group variable system.
    
            etc_other_conf_other.conf
 
         vars/
-           main.yml
+           main.yml  # variables specific to this playbook
 
         handlers/
            main.yml
@@ -224,6 +226,7 @@ will require handlers, tasks, and templates
    +
    +

    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

    When you can do something simply, do something simply. Do not reach to use every feature of Ansible together, all @@ -289,7 +297,7 @@ This way you have an audit trail describing when and why you changed the rules a

    © Copyright 2012 Michael DeHaan.
    - Last updated on Jun 19, 2012.
    + Last updated on Jul 04, 2012.

    diff --git a/examples.html b/examples.html index cfd5badff69..5f740bd82ba 100644 --- a/examples.html +++ b/examples.html @@ -382,7 +382,7 @@ a simplified syntax for this.

    © Copyright 2012 Michael DeHaan.
    - Last updated on Jun 19, 2012.
    + Last updated on Jul 04, 2012.

    diff --git a/faq.html b/faq.html index 35f79ba8b99..ce80eb9280a 100644 --- a/faq.html +++ b/faq.html @@ -230,8 +230,7 @@ best’, and distills all of the ideas behind all of these other tools to th

    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 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 -not supported, but Ansible does have an async mode. Ansible also adds +heavily inspired by Func. Ansible also adds a configuration management and multinode orchestration layer (Playbooks) that Func didn’t have.

    @@ -247,7 +246,7 @@ notification events (like Puppet). This is kind of a ‘best of both worlds 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, 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.

    Ansible’s resources are heavily inspired by Puppet, with the “state” keyword being a more or less direct port of “ensure” from Puppet. Unlike Puppet, Ansible can be extended in any language, @@ -324,9 +323,12 @@ to go.

    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 all at once.

    +

    The SSH connection type (paramiko is the default, binary openssh is an option) +can also make use of “ControlMaster” features in SSH, which reuses network +connections.

    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 +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 easily bootstrapped or reconfigured just using SSH. There is more information available about this in the Advanced Playbooks section. The self-bootstrapping @@ -336,8 +338,8 @@ model.

    Are transports other than SSH supported?

    -

    Currently SSH and local connections are supported. In 0.5, we’ll also be including -a faster SSH transport. The interface is actually pluggable so a +

    Currently SSH (you can choose between paramiko or the openssh binaries) +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.

    Stop by the mailing list if you have ideas. The connection-specific parts of Ansible are all abstracted away from the core implementation so it is very easy to extend.

    @@ -386,7 +388,7 @@ tasks – whether for a QA sytem, build system, or anything you can think of

    © Copyright 2012 Michael DeHaan.
    - Last updated on Jun 19, 2012.
    + Last updated on Jul 04, 2012.

    diff --git a/genindex.html b/genindex.html index 7f02ca20cdc..cd74c798e2b 100644 --- a/genindex.html +++ b/genindex.html @@ -190,7 +190,7 @@ s.parentNode.insertBefore(ga, s);

    © Copyright 2012 Michael DeHaan.
    - Last updated on Jun 19, 2012.
    + Last updated on Jul 04, 2012.

    diff --git a/gettingstarted.html b/gettingstarted.html index 1989a557d7d..f440d463710 100644 --- a/gettingstarted.html +++ b/gettingstarted.html @@ -158,6 +158,7 @@ s.parentNode.insertBefore(ga, s);
  • Tagged Releases
    • +
  • Choosing Between Paramiko and Native SSH
  • Your first commands
    • @@ -205,7 +206,7 @@ also need:

    -

    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

    @@ -293,6 +294,21 @@ project page:

    +
    +

    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

    Now that you’ve installed Ansible, it’s time to test it.

    @@ -306,9 +322,21 @@ bserver.example.org 
    ssh-agent bash
 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:

    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:

    ansible all -a "/bin/echo hello"
    @@ -349,7 +377,7 @@ explore, but you already have a fully working infrastructure!

    © Copyright 2012 Michael DeHaan.
    - Last updated on Jun 19, 2012.
    + Last updated on Jul 04, 2012.

    diff --git a/index.html b/index.html index 60065527892..cfc165430ca 100644 --- a/index.html +++ b/index.html @@ -190,7 +190,7 @@ and command execution framework. Other tools in this space have been too complicated for too long, require too much bootstrapping, and have too much learning curve. Ansible is dead simple and painless to extend. 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 tasks, quickly firing off commands against nodes. See Command Line.

    @@ -237,6 +237,7 @@ hosts.

  • Dead simple setup
  • Super fast & parallel by default
  • 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
  • Can be easily run from a checkout, no installation required
  • Modules are idempotent, but you can also easily use shell commands
    • @@ -290,6 +291,7 @@ Email:   Tagged Releases +
  • Choosing Between Paramiko and Native SSH
  • Your first commands
    • @@ -314,6 +316,8 @@ Email:   
  • Ansible Modules
  • Advanced Playbooks