mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 00:55:19 +00:00
119 lines
2.9 KiB
ReStructuredText
119 lines
2.9 KiB
ReStructuredText
.. _yaml:
|
|
|
|
==================
|
|
Understanding YAML
|
|
==================
|
|
|
|
The default renderer for SLS files is the YAML renderer. YAML is a
|
|
markup language with many powerful features. However, Salt uses
|
|
a small subset of YAML that maps over very commonly used data structures,
|
|
like lists and dictionaries. It is the job of the YAML renderer to take
|
|
the YAML data structure and compile it into a Python data structure for
|
|
use by Salt.
|
|
|
|
Though YAML syntax may seem daunting and terse at first, there are only
|
|
three very simple rules to remember when writing YAML for SLS files.
|
|
|
|
Rule One: Indentation
|
|
---------------------
|
|
|
|
YAML uses a fixed indentation scheme to represent relationships between
|
|
data layers. Salt requires that the indentation for each level consists
|
|
of exactly two spaces. Do not use tabs.
|
|
|
|
|
|
Rule Two: Colons
|
|
----------------
|
|
|
|
Python dictionaries are, of course, simply key-value pairs. Users from other
|
|
languages may recognize this data type as hashes or associative arrays.
|
|
|
|
Dictionary keys are represented in YAML as strings terminated by a trailing
|
|
colon. Values are represented by either a string following the colon,
|
|
separated by a space:
|
|
|
|
.. code-block:: yaml
|
|
|
|
my_key: my_value
|
|
|
|
In Python, the above maps to:
|
|
|
|
.. code-block:: python
|
|
|
|
{'my_key': 'my_value'}
|
|
|
|
Alternatively, a value can be associated with a key through indentation.
|
|
|
|
.. code-block:: yaml
|
|
|
|
my_key:
|
|
my_value
|
|
|
|
.. note::
|
|
|
|
The above syntax is valid YAML but is uncommon in SLS files because most often,
|
|
the value for a key is not singular but instead is a *list* of values.
|
|
|
|
In Python, the above maps to:
|
|
|
|
.. code-block:: python
|
|
|
|
{'my_key': 'my_value'}
|
|
|
|
Dictionaries can be nested:
|
|
|
|
.. code-block:: yaml
|
|
|
|
first_level_dict_key:
|
|
second_level_dict_key: value_in_second_level_dict
|
|
|
|
And in Python:
|
|
|
|
.. code-block:: python
|
|
|
|
{
|
|
'first_level_dict_key': {
|
|
'second_level_dict_key': 'value_in_second_level_dict'
|
|
}
|
|
}
|
|
|
|
Rule Three: Dashes
|
|
------------------
|
|
|
|
To represent lists of items, a single dash followed by a space is used. Multiple
|
|
items are a part of the same list as a function of their having the same level of indentation.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- list_value_one
|
|
- list_value_two
|
|
- list_value_three
|
|
|
|
Lists can be the value of a key-value pair. This is quite common in Salt:
|
|
|
|
.. code-block:: yaml
|
|
|
|
my_dictionary:
|
|
- list_value_one
|
|
- list_value_two
|
|
- list_value_three
|
|
|
|
In Python, the above maps to:
|
|
|
|
.. code-block:: python
|
|
|
|
{'my_dictionary': ['list_value_one', 'list_value_two', 'list_value_three']}
|
|
|
|
Learning More
|
|
-------------
|
|
|
|
One easy way to learn more about how YAML gets rendered into Python data structures is
|
|
to use an online YAML parser to see the Python output.
|
|
|
|
One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/
|
|
|
|
Templating
|
|
----------
|
|
Jinja statements and expressions are allowed by default in SLS files. See
|
|
:ref:`Understanding Jinja <understanding-jinja>`.
|