YAMLSyntax.html


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>YAML Syntax &mdash; Ansible - SSH-Based Configuration Management &amp; Deployment</title>
    
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.01',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/bootstrap-dropdown.js"></script>
    <script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="top" title="Ansible - SSH-Based Configuration Management &amp; Deployment" href="index.html" />
    <link rel="next" title="Playbooks" href="playbooks.html" />
    <link rel="prev" title="Ansible Modules" href="modules.html" />
<script type="text/javascript">
(function () {
  /**
   * Patch TOC list.
   *
   * Will mutate the underlying span to have a correct ul for nav.
   *
   * @param $span: Span containing nested UL's to mutate.
   * @param minLevel: Starting level for nested lists. (1: global, 2: local).
   */
  var patchToc = function ($span, minLevel) {
    var $tocList = $("<ul/>").attr('class', "dropdown-menu"),
      findA;

    // Find all a "internal" tags, traversing recursively.
    findA = function ($elem, level) {
      var level = level || 0,
        $items = $elem.find("> li > a.internal, > ul, > li > ul");

      // Iterate everything in order.
      $items.each(function (index, item) {
        var $item = $(item),
          tag = item.tagName.toLowerCase(),
          pad = 10 + ((level - minLevel) * 10);

        if (tag === 'a' && level >= minLevel) {
          // Add to existing padding.
          $item.css('padding-left', pad + "px");
          // Add list element.
          $tocList.append($("<li/>").append($item));
        } else if (tag === 'ul') {
          // Recurse.
          findA($item, level + 1);
        }
      });
    };

    // Start construction and return.
    findA($span);

    // Wipe out old list and patch in new one.
    return $span.empty("ul").append($tocList);
  };

  $(document).ready(function () {
    // Patch the global and local TOC's to be bootstrap-compliant.
    patchToc($("span.globaltoc"), 1);
    patchToc($("span.localtoc"), 2);

    // Activate.
    $('#topbar').dropdown();
  });
}());
</script>

<script type="text/javascript">

 var _gaq = _gaq || [];
 _gaq.push(['_setAccount', 'UA-29861888-1']);
 _gaq.push(['_trackPageview']);

 (function() {
   var ga = document.createElement('script'); ga.type =
'text/javascript'; ga.async = true;
   ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
   var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
 })();

</script>

<script type="text/javascript">
  (function() {
    var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
    po.src = 'https://apis.google.com/js/plusone.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
  })();
</script>

<script>(function(d, s, id) {
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) return;
  js = d.createElement(s); js.id = id;
  js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
  fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>

  </head>
  <body>
  <div class="topbar" data-scrollspy="scrollspy" >
    <div class="topbar-inner">
      <div class="container">
        <!-- <a class="brand" href="index.html">Ansible</a> -->
        <ul class="nav">
          
            <li class="dropdown" data-dropdown="dropdown">
  <a href="index.html"
     class="dropdown-toggle">Chapter</a>
  <span class="globaltoc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory &amp; Patterns</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</a></li>
<li class="toctree-l1"><a class="reference internal" href="modules.html">Ansible Modules</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">YAML Syntax</a></li>
<li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="playbooks2.html">Advanced Playbooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API &amp; Integrations</a></li>
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="who_uses_ansible.html">Who Uses Ansible</a></li>
</ul>
</span>
</li>
            <li class="dropdown" data-dropdown="dropdown">
  <a href="#"
     class="dropdown-toggle">Page</a>
  <span class="localtoc"><ul>
<li><a class="reference internal" href="#">YAML Syntax</a><ul>
<li><a class="reference internal" href="#yaml-basics">YAML Basics</a></li>
</ul>
</li>
</ul>
</span>
</li>
          
        </ul>
        <ul class="nav secondary-nav">
          
            
<form class="pull-left" action="search.html" method="get">
  <input type="text" name="q" placeholder="Search" />
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </ul>
      </div>
    </div>
  </div>
<a href="http://github.com/ansible/ansible"><img style="position: absolute; right: 0; border: 0;" src="http://ansible.github.com/github.png" alt="Fork me on GitHub"></a>


<div class="container">
   <a href="http://ansible.github.com"><img src="http://ansible.github.com/ansible-logo.png" alt="Ansible"/></a><br/>
<br/>
   
  <div class="section" id="yaml-syntax">
<h1>YAML Syntax<a class="headerlink" href="#yaml-syntax" title="Permalink to this headline">¶</a></h1>
<p>This page provides a basic overview of correct YAML syntax, which is how Ansible
playbooks (our configuration management language) are expressed.</p>
<p>We use YAML because it is easier to read and write for humans than other common
data formats like XML or JSON.  Further, there are libraries available for reading
and writing YAML in most programming languages.</p>
<p>You may also wish to read <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> at the same time to see how this
is used in practice.</p>
<div class="section" id="yaml-basics">
<h2>YAML Basics<a class="headerlink" href="#yaml-basics" title="Permalink to this headline">¶</a></h2>
<p>For <cite>ansible</cite>, nearly every YAML file starts with a list.
Each item in the list is a list of key/value pairs, commonly
called a &#8220;hash&#8221; or a &#8220;dictionary&#8221;.  So, we need to know how
to write lists and dictionaries in YAML.</p>
<p>There&#8217;s another small quirk to YAML.  All YAML files (regardless of their association with
<cite>ansible</cite> or not) should start with <tt class="docutils literal"><span class="pre">---</span></tt>.  This is just a YAML
format thing that means &#8220;this is the start of a document&#8221;.</p>
<p>All members of a list are lines beginning at the same indentation level starting
with a <tt class="docutils literal"><span class="pre">-</span></tt> (dash) character:</p>
<div class="highlight-python"><pre>---
# A list of tasty fruits
- Apple
- Orange
- Strawberry
- Mango</pre>
</div>
<p>A dictionary is represented in a simple <tt class="docutils literal"><span class="pre">key:</span></tt> and <tt class="docutils literal"><span class="pre">value</span></tt> form:</p>
<div class="highlight-python"><pre>---
# An employee record
name: John Eckersberg
job: Developer
skill: Elite</pre>
</div>
<p>Dictionaries can also be represented in an abbreviated form if you really want to:</p>
<div class="highlight-python"><pre>---
# An employee record
{name: John Eckersberg, job: Developer, skill: Elite}</pre>
</div>
<p id="truthiness">Ansible doesn&#8217;t really use these too much, but you can also specify a
boolean value (true/false) in several forms:</p>
<div class="highlight-python"><pre>---
knows_oop: True
likes_emacs: TRUE
uses_cvs: false</pre>
</div>
<p>Let&#8217;s combine what we learned so far in an arbitary YAML example.  This really
has nothing to do with Ansible, but will give you a feel for the format:</p>
<div class="highlight-python"><pre>---
# An employee record
name: John Eckersberg
job: Developer
skill: Elite
employed: True
foods:
    - Apple
    - Orange
    - Strawberry
    - Mango
languages:
    ruby: Elite
    python: Elite
    dotnet: Lame</pre>
</div>
<p>That&#8217;s all you really need to know about YAML to get started writing
<cite>Ansible</cite> playbooks.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
<dd>Learn what playbooks can do and how to write/run them.</dd>
<dt><a class="reference external" href="http://yamllint.com/">YAMLLint</a></dt>
<dd>YAML Lint (online) helps you debug YAML syntax if you are having problems</dd>
<dt><a class="reference external" href="https://github.com/ansible/ansible/tree/devel/examples/playbooks">Github examples directory</a></dt>
<dd>Complete playbook files from the github project source</dd>
<dt><a class="reference external" href="http://groups.google.com/group/ansible-project">Mailing List</a></dt>
<dd>Questions? Help? Ideas?  Stop by the list on Google Groups</dd>
<dt><a class="reference external" href="http://irc.freenode.net">irc.freenode.net</a></dt>
<dd>#ansible IRC chat channel</dd>
</dl>
</div>
</div>
</div>


<br/>
</div>
<footer class="footer">

  <div class="container">
  <div id="fb-root"></div>
<p>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_donations">
<input type="hidden" name="business" value="michael.dehaan@gmail.com">
<input type="hidden" name="lc" value="US">
<input type="hidden" name="item_name" value="Ansible">
<input type="hidden" name="no_note" value="0">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>
</p>
<p>
<a href="https://twitter.com/share" class="twitter-share-button" data-text="ansible.github.com">Share On Twitter</a>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
<g:plusone annotation="inline"></g:plusone>
<div class="fb-like" data-href="http://ansible.github.com" data-send="true" data-width="450" data-show-faces="false"></div>
</p>
<p>
        &copy; Copyright 2012 Michael DeHaan.<br/>
      Last updated on Aug 30, 2012.<br/>
    </p>
  </div>
</footer>
  </body>
</html>