Синтаксис YAML

Эта страница предоставляет краткий обзор правильного синтаксиса YAML, который используется для выражения playbooks Ansible (нашего языка управления конфигурацией).

Мы используем YAML, потому что его легче читать и писать, чем другие распространённые форматы данных, такие как XML или JSON. Кроме того, существуют библиотеки для работы с YAML на большинстве языков программирования.

Вы также можете прочитать Работа с playbook одновременно, чтобы увидеть, как это используется на практике.

Основы YAML

Практически каждый файл YAML для Ansible начинается со списка. Каждый элемент списка представляет собой список пар ключ-значение, обычно называемый «хэш» или «словарём». Поэтому нам нужно знать, как писать списки и словари в YAML.

Существует ещё одна небольшая особенность YAML. Все файлы YAML (независимо от их связи с Ansible или нет) могут необязательно начинаться с --- и заканчиваться .... Это часть формата YAML и указывает начало и конец документа.

Все члены списка находятся на одной и той же отступе, начиная со строки с "- " (дефис и пробел):

---
# A list of tasty fruits
fruits:
    - Apple
    - Orange
    - Strawberry
    - Mango
...

Словарь представлен в простом key: value формате (двоеточие должно следовать за пробелом):

# An employee record
martin:
    name: Martin D'vloper
    job: Developer
    skill: Elite

Возможны более сложные структуры данных, такие как списки словарей, словари, значениями которых являются списки, или их сочетание:

# Employee records
-  martin:
    name: Martin D'vloper
    job: Developer
    skills:
      - python
      - perl
      - pascal
-  tabitha:
    name: Tabitha Bitumen
    job: Developer
    skills:
      - lisp
      - fortran
      - erlang

Словари и списки также могут быть представлены в сокращённой форме, если это необходимо:

---
martin: {name: Martin D'vloper, job: Developer, skill: Elite}
fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']

Они называются «Коллекциями потоков».

Ansible не очень часто использует их, но вы также можете указать значение булева типа (true/false) в нескольких формах:

create_key: yes
needs_agent: no
knows_oop: True
likes_emacs: TRUE
uses_cvs: false

Значения могут занимать несколько строк, используя | или >. Использование «Литерального блочного скаляра» | сохранит все новые строки и все последующие пробелы. Использование «Свёрнутого блочного скаляра» > свёрнёт все новые строки в пробелы; используется для того, чтобы сделать очень длинную строку легче для чтения и редактирования. В любом случае отступ будет проигнорирован. Вот примеры:

include_newlines: |
            exactly as you see
            will appear these three
            lines of poetry

fold_newlines: >
            this is really a
            single line of text
            despite appearances

В приведённом выше > примере все новые строки сворачиваются в пробелы, но есть два способа сохранить новую строку:

fold_some_newlines: >
    a
    b

    c
    d
      e
    f
same_as: "a b\nc d\n  e\nf\n"

Давайте объединим то, что мы узнали до сих пор, в произвольном примере YAML. Это не имеет отношения к Ansible, но позволит вам почувствовать формат:

---
# An employee record
name: Martin D'vloper
job: Developer
skill: Elite
employed: True
foods:
    - Apple
    - Orange
    - Strawberry
    - Mango
languages:
    perl: Elite
    python: Elite
    pascal: Lame
education: |
    4 GCSEs
    3 A-Levels
    BSc in the Internet of Things

Это всё, что вам нужно знать о YAML, чтобы начать писать Ansible playbook.

Особенности

Хотя вы можете поместить практически что угодно в необработанный скаляр, есть некоторые исключения. Двоеточие, за которым следует пробел (или новая строка) : `` is an indicator for a mapping. A space followed by the pound sign `` # начинает комментарий.

Из-за этого следующее приведёт к ошибке синтаксиса YAML:

foo: somebody said I should put a colon here: so I did

windows_drive: c:

...но это будет работать:

windows_path: c:\windows

Вы захотите использовать кавычки для значений хэша, используя двоеточие, за которым следует пробел или конец строки:

foo: 'somebody said I should put a colon here: so I did'

windows_drive: 'c:'

...а затем двоеточие будет сохранено.

В качестве альтернативы можно использовать двойные кавычки:

foo: "somebody said I should put a colon here: so I did"

windows_drive: "c:"

Разница между одинарными и двойными кавычками в том, что в двойных кавычках вы можете использовать управляющие символы:

foo: "a \t TAB and a \n NEWLINE"

Список разрешённых управляющих символов можно найти в спецификации YAML в разделе «Escape Sequences» (YAML 1.1) или «Escape Characters» (YAML 1.2).

Следующее является недопустимым YAML:

foo: "an escaped \' single quote"

Кроме того, Ansible использует «{{ var }}» для переменных. Если значение после двоеточия начинается с «{», YAML посчитает это словарем, поэтому вы должны использовать кавычки, как в этом примере:

foo: "{{ variable }}"

Если ваше значение начинается с кавычки, всё значение должно быть заключено в кавычки, а не только его часть. Вот ещё несколько примеров правильного использования кавычек:

foo: "{{ variable }}/additional/string/literal"
foo2: "{{ variable }}\\backslashes\\are\\also\\special\\characters"
foo3: "even if it's just a string literal it must all be quoted"

Неверно:

foo: "E:\\path\\"rest\\of\\path

Помимо ' и " существует ряд специальных (или зарезервированных) символов, которые нельзя использовать в качестве первого символа необработанного скаляра: [] {} > | * & ! % # ` @ ,.

Вы также должны учитывать ? : -. В YAML они разрешены в начале строки, если за ними следует символ, отличный от пробела, но реализации процессоров YAML различаются, поэтому лучше использовать кавычки.

В коллекциях потоков правила немного жёстче:

a scalar in block mapping: this } is [ all , valid

flow mapping: { key: "you { should [ use , quotes here" }

Преобразование в булевы значения полезно, но это может быть проблемой, когда вам нужно получить строковое представление литерального yes или других булевых значений. В этих случаях используйте кавычки:

non_boolean: "yes"
other_string: "False"

YAML преобразует некоторые строки в числа с плавающей точкой, такие как строка 1.0. Если вам нужно указать номер версии (например, в файле requirements.yml), вам нужно заключить значение в кавычки, если оно похоже на число с плавающей точкой:

version: "1.0"