YAML Синтаксис

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

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

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

Основы YAML

Для Ansible почти каждый файл YAML начинается со списка. Каждый элемент в списке представляет собой список пар ключ/значение, обычно называемых «хешем» или «словарем». Поэтому нам нужно знать, как писать списки и словари в 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

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

Давайте объединим то, чему мы научились до сих пор, в произвольном примере 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 playbooks.

Особенности

Хотя YAML, в целом, дружественный, следующее приведёт к ошибке синтаксиса 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:"

…и тогда двоеточие будет сохранено.

Кроме того, 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 [] {} : > |.

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

non_boolean: "yes"
other_string: "False"

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

version: "1.0"