PageRenderTime 30ms CodeModel.GetById 16ms app.highlight 7ms RepoModel.GetById 2ms app.codeStats 0ms

/docsite/rst/YAMLSyntax.rst

https://github.com/ajanthanm/ansible
ReStructuredText | 116 lines | 85 code | 31 blank | 0 comment | 0 complexity | 3e22036bb862e60848db2e9fd9776f37 MD5 | raw file
  1YAML Syntax
  2===========
  3
  4This page provides a basic overview of correct YAML syntax, which is how Ansible
  5playbooks (our configuration management language) are expressed.  
  6
  7We use YAML because it is easier for humans to read and write than other common
  8data formats like XML or JSON.  Further, there are libraries available in most
  9programming languages for working with YAML.
 10
 11You may also wish to read :doc:`playbooks` at the same time to see how this
 12is used in practice.
 13
 14
 15YAML Basics
 16-----------
 17
 18For Ansible, nearly every YAML file starts with a list.   
 19Each item in the list is a list of key/value pairs, commonly
 20called a "hash" or a "dictionary".  So, we need to know how
 21to write lists and dictionaries in YAML.
 22
 23There's another small quirk to YAML.  All YAML files (regardless of their association with
 24Ansible or not) should begin with ``---``.  This is part of the YAML
 25format and indicates the start of a document.
 26
 27All members of a list are lines beginning at the same indentation level starting
 28with a ``-`` (dash) character::
 29
 30    ---
 31    # A list of tasty fruits
 32    - Apple
 33    - Orange
 34    - Strawberry
 35    - Mango
 36
 37A dictionary is represented in a simple ``key:`` and ``value`` form::
 38
 39    ---
 40    # An employee record
 41    name: Example Developer
 42    job: Developer
 43    skill: Elite
 44
 45Dictionaries can also be represented in an abbreviated form if you really want to::
 46
 47    ---
 48    # An employee record
 49    {name: Example Developer, job: Developer, skill: Elite}
 50
 51.. _truthiness:
 52
 53Ansible doesn't really use these too much, but you can also specify a 
 54boolean value (true/false) in several forms::
 55
 56    ---
 57    create_key: yes
 58    needs_agent: no
 59    knows_oop: True
 60    likes_emacs: TRUE
 61    uses_cvs: false
 62
 63Let's combine what we learned so far in an arbitrary YAML example.  This really
 64has nothing to do with Ansible, but will give you a feel for the format::
 65
 66    ---
 67    # An employee record
 68    name: Example Developer
 69    job: Developer
 70    skill: Elite
 71    employed: True
 72    foods:
 73        - Apple
 74        - Orange
 75        - Strawberry
 76        - Mango
 77    languages:
 78        ruby: Elite
 79        python: Elite
 80        dotnet: Lame
 81
 82That's all you really need to know about YAML to start writing
 83`Ansible` playbooks.
 84
 85Gotchas
 86-------
 87
 88While YAML is generally friendly, the following is going to result in a YAML syntax error:
 89
 90    foo: somebody said I should put a colon here: so I did
 91
 92You will want to quote any hash values using colons, like so:
 93
 94    foo: "somebody said I should put a colon here: so I did"
 95
 96And then the colon will be preserved.
 97
 98Further, Ansible uses "{{ var }}" for variables.  If a value after a colon starts
 99with a "{", YAML will think it is a dictionary, so you must quote it, like so::
100
101    foo: "{{ variable }}"
102
103
104.. seealso::
105
106   :doc:`playbooks`
107       Learn what playbooks can do and how to write/run them.
108   `YAMLLint <http://yamllint.com/>`_
109       YAML Lint (online) helps you debug YAML syntax if you are having problems
110   `Github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_
111       Complete playbook files from the github project source
112   `Mailing List <http://groups.google.com/group/ansible-project>`_
113       Questions? Help? Ideas?  Stop by the list on Google Groups
114   `irc.freenode.net <http://irc.freenode.net>`_
115       #ansible IRC chat channel
116