YAML is a file format similar in intent to JSON, but generally easier for humans to read and write.
Start of File
All YAML files (regardless of their association with Ansible or not) can optionally begin with --- and end with .... This is part of the YAML format and indicates the start and end of a document.
However, if you forget to put those three dashes at the top of your playbook files, Ansible won’t complain.
Comments
Comments start with a number sign and apply to the end of the line, the same as in shell scripts, Python, and Ruby:
# This is a YAML comment
Strings
In general, YAML strings don’t have to be quoted even though they have spaces in them, and you can quote them if you prefer.
SPACES VS TABS
YAML uses spaces, period. Do not use tabs in your SLS files! If strange errors are coming up in rendering SLS files, make sure to check that no tabs have crept in!
In Vim, after enabling search highlighting with: :set hlsearch, you can check with the following key sequence in normal mode(you can hit ESC twice to be sure): /, Ctrl-v, Tab, then hit Enter. Also, you can convert tabs to 2 spaces by these commands in Vim::set tabstop=2 expandtab and then :retab.
INDENTATION
In YAML line indentation is used to indicate variable nesting to the parser, which also makes the file easier to read.
The suggested syntax for YAML files is to use 2 spaces for indentation, but YAML will follow whatever indentation system that the individual file uses. Indentation of two spaces works very well for SLS files given the fact that the data is uniform and not deeply nested.
/etc/http/conf/http.conf:
file:
- managed
- source: salt://apache/http.conf
- user: root
- group: root
- mode: 644
- template: jinja
- context:
custom_var: "override"
- defaults:
custom_var: "default value"
other_var: 123
Notice that while the indentation is two spaces per level, for the values under the context and defaults options there is a four-space indent. If only two spaces are used to indent, then those keys will be considered part of the same dictionary that contains the context key, and so the data will not be loaded correctly. If using a double indent is not desirable, then a deeply-nested dict can be declared with curly braces:
/etc/http/conf/http.conf:
file:
- managed
- source: salt://apache/http.conf
- user: root
- group: root
- mode: 644
- template: jinja
- context: {
custom_var: "override" }
- defaults: {
custom_var: "default value",
other_var: 123 }
An example to set the logging banner for an apache servers can be file /etc/ansible/playbooks/MOTD.ymal with below contents:
:
Booleans
There are multiple ways to express booleans:
YAML truthy
true, True, TRUE, yes, Yes, YES, on, On, ON, y, Y
YAML falsey
false, False, FALSE, no, No, NO, off, Off, OFF, n, N
Lists (sequences)
All members of a list are lines beginning at the same indentation level starting with a "- " (a dash and a space):
- My Fair Lady
- Oklahoma
- The Pirates of Penzance
Dictionaries
Similar to dictionaries in Python, a dictionary is represented in a simple key: value form (the colon must be followed by a space, All keys are case-sensitive):
address: 742 Evergreen Terrace
city: Springfield
state: North Takoma
Line Folding
Line folding break up one line across multiple lines, and Ansible treat the string as if it were a single line.
You can do this with YAML using line folding with the greater than (>) character.
address: > Department of Computer Science, A.V. Williams Building, University of Maryland city: College Park state: Maryland