Начало работы
Базовая структура
YAML использует отступы (пробелы, не табы) для вложенности. Отображения используют key: value, последовательности — - item. Inline-синтаксис использует [] для списков и {} для отображений. Комментарии начинаются с #.
# YAML uses indentation for structure
# Comments start with #
# Key-value pairs (mappings)
name: Alice
age: 30
# Nested mappings (use consistent indentation)
person:
name: Bob
age: 25
address:
city: NYC
zip: 10001
# Sequences (lists)
hobbies:
- reading
- coding
- music
# Inline syntax
numbers: [1, 2, 3]
coords: {x: 10, y: 20}Комментарии
Комментарии начинаются с # и должны иметь перед собой пробел или начало строки. Вн утри блочных скаляров (| и >) # — литеральный контент, а не комментарий. Многострочного синтаксиса комментариев нет: каждой строке нужен свой #.
# Full-line comment
key: value # Inline comment (whitespace before # required)
# Comments can appear anywhere
# - before documents
# - inside sequences
list:
- a # first item
- b # second item
# Block scalar headers DO accept comments
text: | # literal block
line one
# But the content of block scalars is literal,
# so # inside is NOT a comment:
literal: |
# this is part of the string, not a commentПравила отступов
YAML строго запрещает табы для отступов — допускаются только пробелы. Отступы должны быть согласованы в пределах уровня, но не обязаны иметь фиксированное число. Символ - в последовательностях является частью отступа. Смешивание табов и пробелов вызывает ошибку парсера.
# Use SPACES only — tabs are forbidden for indentation
# 2 spaces is the most common convention
mapping:
nested:
deeply_nested: value
# Sequences can be indented at the same level as the key
items:
- one
- two
# Or indented further (both are valid)
items2:
- one
- two
# WRONG: tab characters cause parser errors
# bad: value (tab before value)
# Hyphen counts as indentation start
- item1
- item2Начало и конец документа
--- отмечает начало YAML-документа; ... отмечает конец. Файл может содержать несколько документов, разделённых --- (поток документов). Для конфигов с одним документом ведущий --- необязателен, но рекомендуется как подсказка парсерам.
# --- separates documents in a stream
# ... ends a document (optional)
---
name: first document
value: 1
...
---
name: second document
value: 2
...
# A single document needs no markers
key: value
# But --- is recommended at the start of files
# to disambiguate from plain text
---
apiVersion: v1
kind: ConfigMapЧастые ловушки
Двоеточию нужен следующий пробел, чтобы быть разделителем отображения. YAML 1.1 и 1.2 различаются в yes/no/on/off (boolean в 1.1, строки в 1.2) и в восьмеричных литералах. Пустые значения — null, отличные от пустых строк. Многие парсеры (PyYAML) до сих пор следуют правилам 1.1.
# Colon needs a space after it
key:value # WRONG: parsed as a single string "key:value"
key: value # correct
# Yes/No/On/Off are NOT booleans in YAML 1.2
# (they WERE in YAML 1.1 — common gotcha)
answer: yes # YAML 1.1: true; YAML 1.2: "yes" string
# Numbers with leading zeros
version: 010 # YAML 1.1: octal 8; YAML 1.2: string "010"
# Unquoted strings with special chars
url: example.com/path # OK
url: example.com:8080 # WRONG: parsed as mapping with key example.com
# Empty values
empty: # null
empty2: ~ # explicit null
empty3: "" # empty string (different from null)YAML и JSON
YAML 1.2 спроектирован так, что JSON — строгое подмножество: любой JSON-файл является валидным YAML. YAML добавляет комментарии, блочную структуру, якоря, многострочные строки и теги. JSON требует кавычек для всех ключей и строковых значений, YAML это ослабляет для простых скаляров.
# JSON is a strict subset of YAML 1.2
# Every valid JSON document is valid YAML
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# Equivalent YAML:
name: Alice
age: 30
hobbies:
- a
- b
# YAML adds: comments, multi-line strings, anchors,
# relaxed quoting, tags, multiple documents
# YAML removes: mandatory quotes around strings,
# commas, braces (in block style)
# YAML is a superset of JSON — not the other way.
# Comments and anchors are not valid JSON.Скаляры (строки, числа, boolean, null)
Простые и закавыченные строки
Простые строки не нуждаются в кавычках, если не выглядят как числа, boolean, null или даты. Одинарные кавычки экранируют ' только удвоением (''); других escape-последовательностей нет. Двойные кавычки поддерживают полные escape-последовательности (\n, \t, \uXXXX). Кавычки принудительно задают строковый тип.
# Plain strings (no quotes) — most common
name: Alice
path: /usr/local/bin
url: https://example.com
# Single-quoted — escape ' by doubling
msg: 'it''s fine'
# Double-quoted — supports escapes
greeting: "Hello\nWorld"
unicode: "\u03B1" # Greek alpha
tab: "col1\tcol2"
# Multi-word plain strings are fine
description: This is a plain string with spaces
# Strings that look like other types must be quoted
version: "1.0" # string, not float
notBool: "true" # string, not boolean
notNull: "null" # string, not null
date: "2024-01-01" # string, not dateЧисла
YAML 1.2 использует 0o для восьмеричных (YAML 1.1 использовал просто ведущий 0). Подчёркивания в числах допускаются для читаемости. .inf и .nan — специальные литералы float. Закавычивайте любое значение, которое должно быть строкой, но выглядит числом (версии, телефоны, ID).
# Integers
int: 42
negative: -17
positive: +100
underscored: 1_000_000 # readable grouping (YAML 1.2)
# Octal & hex (YAML 1.2 prefixes)
octal: 0o17 # = 15 decimal
hex: 0xFF # = 255 decimal
binary: 0b1010 # = 10 decimal
# Floats
pi: 3.14159
exp: 1.0e+3 # 1000.0
neg_exp: -2.5e-4
# Special float values (IEEE 754)
infinity: .inf
neg_infinity: -.inf
not_a_number: .nan
# To force a string that looks numeric:
version: "1.0"
phone: "555-1234"Boolean
YAML 1.2 сузил boolean до true/false (и True/False, TRUE/FALSE). YAML 1.1 (используется PyYAML) трактует yes/no/on/off/y/n как boolean — знаменитый источник багов (например, норвежское 'no' превращается в false). Всегда зака вычивайте эти строки, если имеете их в виду буквально.
# YAML 1.2 — only these are booleans:
enabled: true
disabled: false
# YAML 1.1 ALSO accepts (common gotcha):
# yes, no, on, off, y, n, Y, N
# These are strings in 1.2 but booleans in 1.1
# To force a string:
answer: "yes" # always a string
option: "on"
flag: "y"
# PyYAML (1.1 rules) parses these as booleans:
# yes -> True, no -> False, on -> True, off -> False
# This breaks "no" as an answer or country code!
# Safe practice: quote if you mean the literal string
country: "no" # Norway country code, not FalseNull-значения
YAML принимает null, Null, NULL, ~ и пустое значение как null. Пустое значение (ключ без ничего после двоеточия) — null, отличное от пустой строки "". Парсеры отображают YAML null в null-значение языка хоста (None, null, nil).
# All of these represent null/None/null
key1: null
key2: Null
key3: NULL
key4: ~
key5: # empty value
# Distinguish null from empty string
empty_string: ""
null_value: null
# In sequences
list:
- value
- null # explicit null item
- another
# In nested structures
config:
timeout: null # explicitly unset
retries: 3
# Parsers convert to language-specific null:
# Python -> None, JavaScript -> null, Go -> nilДаты и отметки времени
Даты и отметки времени ISO 8601 распознаются большинством парсеров как нативные типы. Голый YYYY-MM-DD становится датой; со временем — datetime. Закавычьте значение, чтобы оставить его строкой. Обозначения часового пояса (Z, +08:00) поддерживаются.
# Date (ISO 8601)
date: 2024-01-15
# Datetime (ISO 8601)
datetime: 2024-01-15T14:30:00
datetime_tz: 2024-01-15T14:30:00Z
datetime_offset: 2024-01-15T14:30:00+08:00
datetime_space: 2024-01-15 14:30:00
# To force string (not a date):
not_a_date: "2024-01-15"
not_a_date2: '2024-01-15'
# Parsers typically return datetime objects
# Python: datetime.date / datetime.datetime
# JavaScript: Date (depending on library)Вывод типов
Система типов YAML разрешает незакавыченные скаляры через схему. Схема Failsafe трактует всё как строки; схемы JSON и Core выводят int, float, bool, null, date. Используйте кавычки или явные теги (!!str, !!int), чтобы переопределить разрешение, когда нужно.
# YAML infers types from unquoted scalars
str: hello # string
int: 42 # integer
float: 3.14 # float
bool: true # boolean
null_val: null # null
date: 2024-01-01 # date
list: [1, 2, 3] # sequence
# Force string type with quotes
str_version: "42"
str_date: "2024-01-01"
str_bool: "true"
# Or with the !!str tag
forced: !!str 42 # string "42"
forced_int: !!int "42" # integer 42
# Resolution depends on the schema
# Failsafe: everything is a string
# JSON/Core: numbers, bools, null inferredОтображения
Простое отображение
Отображение — пары key: value, где ключи обычно строки. Ключи могут быть любым скаляром (число, bool, даже null). Дубликаты ключей не рекомендуются, и поведение зависит от парсера (часто побеждает последний). Используйте линтер, чтобы ловить случайные дубликаты.
# A mapping is a set of key: value pairs
name: Alice
age: 30
email: [email protected]
# Keys can be any scalar type (string, number, bool)
"string key": value
123: numeric key
true: boolean key
# Duplicate keys are technically discouraged
# but some parsers allow them (last wins)
key: first
key: second # overrides "first" in many parsers
# Values can be any type
mixed:
string: text
number: 42
list: [1, 2, 3]
nested:
deep: valueВложенные отображения
Вложенные отображения создаются отступом дочерних ключей. Отступы должны быть согласованы в пределах уровня. Фиксированного размера отступа нет, но 2 пробела — де-факто стандарт. Более глубокая вложенность снижает читаемость — рассмотрите выпрямление очень глубоких структур.
# Nest mappings with consistent indentation
server:
host: localhost
port: 8080
ssl:
enabled: true
cert: /etc/ssl/cert.pem
key: /etc/ssl/key.pem
database:
primary:
host: db1.example.com
port: 5432
replica:
host: db2.example.com
port: 5432
# Indentation level is up to you — just be consistent
# 2 spaces is the most common conventionОтображение последовательностей
Отображения и последовательности свободно компонуются. Частый паттерн — последовательность отображений (список записей), где каждый - начинает элемент, а выровненные ключи принадлежат этому элементу. Отступ последующих ключей должен совпадать с первым ключом после -.
# Values in a mapping can be sequences
servers:
- web1.example.com
- web2.example.com
- web3.example.com
# Sequence of mappings (very common)
users:
- name: Alice
age: 30
- name: Bob
age: 25
# Each - starts a new item; aligned keys form one mapping
services:
- name: api
port: 8080
env:
- dev
- prod
- name: web
port: 3000
# Mixed: mapping containing sequence containing mapping
config:
endpoints:
- path: /health
method: GET
- path: /users
method: POSTСложные ключи
YAML допускает любой скаляр или коллекцию как ключ через индикатор ? key. Это редкость в конфигах, но полезно для таблиц поиска (например, цены по региону и типу инстанса). Сложные ключи неудобно читать — большинство конфигов ограничивается простыми строковыми ключами.
# Keys can be complex objects using ? notation
? key1
: value1
# A mapping as a key
? host: localhost
port: 8080
: connection1
# A sequence as a key
? [a, b, c]
: indexed_value
# Practical (rare) use: matrix lookup
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023
# In flow style:
{[a, b]: value, {x: 1}: other}
# Most config files just use plain string keys
simple: valueInline (flow) отображения
Flow-стиль использует {} для отображений и [] для последовательностей, похоже на JSON. Полезен для коротких компактных данных в одну строку. В отличие от JSON, YAML не допускает висячих запятых. Смешивайте flow и block свободно, но в конфигах предпочитайте block ради читаемости.
# Flow style mapping (like JSON)
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}
# Nested flow mappings
nested: {a: {b: {c: value}}}
# Mixed flow and block
block_key:
flow_value: {x: 1, y: 2}
another: value
# Flow with sequences
mixed: {nums: [1, 2, 3], name: test}
# Quoting still works in flow style
quoted: {"key with space": "value", count: 3}
# Trailing comma is NOT allowed in YAML flow
bad: {a: 1, b: 2,} # parse errorПорядок ключей и стиль
Сам YAML по спецификации сохраняет порядок отображения, но объекты языков хоста могут не сохранять (хотя большинство современных словарей сохраняют). Для читаемости конфига группируйте связанные ключи, используйте единый стиль имён (snake_case или camelCase) и добавляйте комментарии для разделения секций.
# YAML mappings are ORDERED (unlike JSON spec, though
# most JSON parsers preserve insertion order too)
# But language objects may not preserve order:
# Python dict (3.7+): preserves order
# Ruby Hash: preserves order
# JSON object: technically unordered
# Consistent key style improves readability
config:
server:
host: localhost # snake_case
port: 8080
max_connections: 100
database:
host: db.example.com
port: 5432
connection_pool: 10
# Group related keys together
# Use comments to delineate sections
app:
# networking
host: 0.0.0.0
port: 3000
# limits
timeout: 30
retries: 3Последовательности
Блочные последовательности
Блочные последовательности используют - (дефис и пробел) перед каждым элементом. Элементы могут быть любого типа: скаляры, отображения, вложенные последовательности. - считается частью отступа, поэтому последующие ключи в элементе-отображении выравниваются с первым ключом после дефиса.
# A sequence (list) uses - followed by space
fruits:
- apple
- banana
- cherry
# Sequence as top-level document
- item1
- item2
- item3
# Empty sequence
empty: []
or_with_marker: []
# Sequence with mixed types
mixed:
- string
- 42
- true
- null
- key: value # a mapping as an itemВложенные последовательности
Вложенные последовательности образуются дальнейшим отступом уровней -. Их становится трудно читать после 2 уровней — переходите на flow-стиль для внутренних последовательностей. Древовидные структуры (последовательность отображений с children) читаются лучше, чем чисто вложенные последовательности.
# Sequence of sequences
matrix:
- - 1
- 2
- 3
- - 4
- 5
- 6
# More readable with flow style for inner
matrix2:
- [1, 2, 3]
- [4, 5, 6]
# Deeply nested
tree:
- name: root
children:
- name: child1
children:
- name: grandchild1
- name: child2
# 3D: sequence of sequence of sequence
cube:
- - [1, 2]
- [3, 4]
- - [5, 6]
- [7, 8]]Последовательность отображений
Последовательность отображений — самый частый паттерн YAML (списки записей). Каждый - начинает новый элемент; последующие ключи на том же отступе принадлежат этому элементу. Выравнивайте ключи после - для читаемости. Пу стой элемент-отображение записывается как {}.
# Most common pattern: list of records
users:
- name: Alice
email: [email protected]
roles:
- admin
- user
- name: Bob
email: [email protected]
roles:
- user
# Each - starts a new mapping; aligned keys belong
# to that item. Indent the first key after - by 2 spaces.
servers:
- host: web1.example.com
port: 8080
healthy: true
- host: web2.example.com
port: 8080
healthy: false
# Empty mapping item
list:
- {}
- name: realInline (flow) последовательности
Flow-последовательности используют [] и эквивалентны блочным. Полезны для коротких списков в одну строку. Flow-последовательности могут занимать несколько строк ради читаемости. В отличие от JSON, YAML запрещает висячие запятые. Смешивайте flow-последовательности с блочными отображениями свободно.
# Flow sequence (JSON-like)
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]
# Nested flow sequences
matrix: [[1, 2], [3, 4]]
# Flow sequence of flow mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]
# Mixed: block mapping with flow sequence value
config:
ports: [80, 443, 8080]
hosts: [web1, web2, web3]
# Spread across multiple lines (still flow style)
long_list: [
item1,
item2,
item3
]
# NO trailing comma allowed
bad: [1, 2, 3,] # errorСмешанный и разнородный контент
YAML допускает совершенно разнородный контент в последовательностях и отображениях: любой элемент может быть любого типа. Эта гибкость мощна, но означает, что приложение должно валидировать структуру. Используйте схему (JSON Schema, Cue и т. д.) для строгой валидации.
# Sequences can mix types freely
mixed:
- string
- 42
- true
- null
- [1, 2, 3] # nested sequence
- key: value # mapping
another: value2
- - nested
- sequence
# Heterogeneous mapping values
config:
string_val: text
int_val: 42
list_val: [a, b, c]
map_val: {x: 1, y: 2}
null_val: null
bool_val: true
# YAML has no schema enforcing uniformity —
# the application must validate structureПаттерны отступов последовательностей
Последовательности под ключом могут быть с отступом (паттерн 1) или на том же уровне (паттерн 2, так как - считается отступом). Оба варианта валидны; выберите один и будьте последовательны. В последовательностях отображений все ключи элемента должны выравниваться с первым ключом после -.
# Pattern 1: sequence indented under key
items:
- a
- b
# Pattern 2: sequence at same level as key
# (the - is treated as indentation)
items:
- a
- b
# Both are valid and produce the same result.
# Pick one and be consistent (most style guides prefer #1).
# Mapping item alignment — both keys align with first
users:
- name: Alice
age: 30
- name: Bob
age: 25
# WRONG: misaligned keys cause parse errors
# users:
# - name: Alice
# age: 30 # one space off — errorМногострочные строки (folded и literal)
Литеральный блочный скаляр (|)
Литеральный блочный скаляр | сохраняет каждый перевод строки точно как написан. Отступ (величина после |) снимается с каждой строки. Chomping по умолчанию (clip) сохраняет один хвостовой перевод строки. Используется для скриптов, кода, поэзии, ASCII-арта — везде, где важны литеральные переводы строк.
# | preserves newlines as-is
script: |
#!/bin/bash
echo "Hello"
echo "World"
# Output string:
# #!/bin/bash\necho "Hello"\necho "World"\n
poem: |
Roses are red,
Violets are blue,
YAML is clean,
And JSON is too.
# Trailing newline is kept by default (clip mode)
# Use |- to strip, |+ to keep all trailing newlinesСвёрнутый блочный скаляр (>)
Свёрнутый блочный скаляр > превращает одиночные переводы строк в пробелы, соединяя строки в абзацы. Пустые строки становятся литеральными переводами строк. Строки с большим отступом, чем контент блока, сохраняются буквально (полезно для примеров кода внутри прозы).
# > folds newlines into spaces (paragraphs)
description: >
This is a long paragraph that
spans multiple lines in the YAML
but will be joined into one line
when parsed.
# Output: "This is a long paragraph that spans multiple
# lines in the YAML but will be joined into one line when
# parsed.\n"
# Blank lines preserve a newline
paragraphs: >
First paragraph here.
Second paragraph here.
Third paragraph here.
# More indented lines are preserved literally
example: >
This is folded.
This line is more indented — kept literal.Индикаторы chomping (+/-)
Chomping управляет хвостовыми переводами строк: clip (по умолчанию, без индикатора) сохраняет один; strip (-) удаляет все; keep (+) сохраняет все. Индикатор ставится сразу после | или > (например, |-, |+, >-, >+). Strip полезен для строк, используемых inline; keep редок, но точно повторяет исходник.
# Default (clip): single trailing newline
text: |
line1
line2
# Result: "line1\nline2\n"
# Strip (-): remove ALL trailing newlines
text_strip: |-
line1
line2
# Result: "line1\nline2"
# Keep (+): keep ALL trailing newlines
text_keep: |+
line1
line2
# Result: "line1\nline2\n\n\n"
# Same applies to folded scalars
folded_keep: >+
folded
text
Индикатор отступа
Когда контент блочного скаляра начинается с пробелов, нужно явно указать отступ контента цифрой (например, |2). Цифра показывает, сколько пробелов отступа относится к структуре, а сколько — к контенту. Комбинируйте с chomping: |2-, >4+ и т. д. Нужно редко, но когда нужно — обязательно.
# When the first line starts with spaces, you must
# tell YAML the content indentation explicitly
# Without indicator (ambiguous):
# content:
# indented_line # is the leading space content or not?
# With explicit indentation indicator (digit after | or >)
literal: |2
hello
world
# The "2" means: content is indented 2 spaces past the indicator
# So 4 spaces of indentation = 2 content + 2 extra
# Combined with chomping (order: indent then chomp)
text: |2-
no trailing newline
# Folded with explicit indent
folded: >4
paragraph with
explicit indent
# Most of the time you don't need this — only when
# content legitimately starts with spacesПростые многострочные строки
Простые и закавыченные скаляры могут занимать несколько строк, а переводы строк складываются в пробелы (похоже на >, но неявно). Это хрупко, потому что разрывы строк зависят от контекста и спецсимволов. Для любого нетривиального многострочного текста предпочитайте явные блочные скаляры | (literal) или > (folded).
# Plain (unquoted) scalars can span lines
# Newlines are folded to spaces (like > but no indicator)
message: this is
a long message
on multiple lines
# Result: "this is a long message on multiple lines"
# Quotes are required if the string contains special chars
quoted: "this is also
a long message
on multiple lines"
# Result: "this is also a long message on multiple lines"
# Plain multi-line breaks at certain chars
# (colons, etc.) — usually fold cleanly
# but be careful with leading colons
# Plain is fragile for multi-line — prefer | or >
safe_literal: |
Use literal block for
predictable multi-line textВыбор fold или literal
Правило: используйте |, когда переводы строк значимы (скрипты, конфиги, код), и >, когда нужен читаемый многострочный исходник, но соединённый абзац (описания, документация). Используйте |-, чтобы срезать хвостовой перевод строки, когда строка используется inline.
# Use | (literal) when newlines matter:
script: |
#!/bin/bash
set -e
echo "Step 1"
echo "Step 2"
config_file: |
[default]
region=us-east-1
output=json
# Use > (folded) when you want readable source
# but a single paragraph string:
description: >
This service handles user authentication
and session management. It talks to the
PostgreSQL database and Redis cache.
# Use |- or >- to strip trailing newline
# (useful for inline string usage):
inline_script: |-
echo hello
# Use plain single-line for short strings
short: hello worldЯкоря и алиасы
Определение якорей (&)
&name определяет якорь на узле (отображении, последовательности или скаляре). Якорь не меняет значение в этом месте — он просто помечает узел для переиспользования. Алиасы (*name) ссылаются на узел по имени. Якоря должны быть определены до использования в документе.
# &name defines an anchor on a node
defaults: &defaults
adapter: postgres
host: localhost
port: 5432
# The anchor marks the node so it can be reused
# The value is still assigned normally
production:
database: *defaults
# *defaults is an alias — references the anchored node
# Anchors on scalars
version: &ver "1.0.0"
current: *ver
# Anchors on sequences
colors: &colors
- red
- green
- blue
primary: *colorsИспользование алиасов (*)
*name — алиас, ссылающийся на ранее помеченный якорем узел. Алиасы делят идентичность с оригиналом (тот же объект в большинстве парсеров). Якоря и алиасы ограничены документом — они не могут ссылаться через границы документов ---. Комбинируйте с << (merge key), чтобы наслаивать переопределения.
# Define once, reuse by alias
base: &base
image: nginx:1.25
restart: always
web:
<<: *base
ports:
- "80:80"
api:
<<: *base
ports:
- "8080:8080"
environment:
- DEBUG=true
# Aliases reference the SAME object (by identity)
# In most parsers, mutating one mutates the other
# (though YAML itself is read-only)
# Aliases can't span documents
# Each document has its own anchor namespaceОбласть видимости якорей
Якоря ограничены своим документом и должны быть определены до любых ссылок-алиасов (никаких прямых ссылок вперёд). Несколько алиасов могут ссылаться на один якорь. Алиас на алиас работает: разрешается транзитивно. Ссылки между документами — ошибка.
# Anchors are scoped to a single document
---
# Document 1
shared: &shared
key: value
use: *shared # works
...
---
# Document 2 — &shared is NOT visible here
other: *shared # ERROR: unknown anchor
# Anchors must be defined before the alias
# (forward references are not allowed)
bad: *later # ERROR
later: &later value
# Multiple aliases to the same anchor are fine
template: &tpl
timeout: 30
use1: *tpl
use2: *tpl
use3: *tpl
# Aliasing an alias is allowed
a: &a value
b: &b *a
c: *b # resolves to "value"Переопределение значений с якорем
Алиас (*name) заменяет узел целиком — частично переопределить его нельзя. Чтобы переопределить отдельные ключи помеченного отображения, используйте merge key <<, чтобы слить отображение с якорем, затем добавить или переопределить ключи. Это канонический паттерн композиции конфигурации.
# Aliases themselves can't be partially overridden —
# an alias replaces the whole node. Use << (merge)
# to combine an anchored mapping with overrides.
defaults: &defaults
timeout: 30
retries: 3
log_level: info
production:
<<: *defaults
log_level: warn # override
host: prod.example.com # add
# Result:
# production:
# timeout: 30
# retries: 3
# log_level: warn
# host: prod.example.com
# Without <<, an alias replaces the whole node:
wrong:
thing: *defaults
# thing is the FULL defaults mapping — can't overrideЯкоря в последовательностях
Якоря могут помечать целые последовательности, отдельные элементы последовательности или отображения внутри последовательности. Паттерн слияния << особенно полезен в последовательностях похожих записей (например, определения сервисов), чтобы делить общие поля. Помечайте отдельные элементы через - &name value.
# Anchors work on sequence items too
common: &common
enabled: true
log: stdout
services:
- name: web
<<: *common
port: 80
- name: api
<<: *common
port: 8080
- name: worker
<<: *common
queue: jobs
# Anchoring a whole sequence
endpoints: &endpoints
- /health
- /metrics
- /ready
monitoring:
checks: *endpoints
# Anchoring individual sequence items
list:
- &first one
- two
- *first # "one" againОговорки по якорям
У якорей есть оговорки: алиасы делят идентичность (мутация одного влияет на все ссылки в мутабельных парсерах), они добавляют когнитивную нагрузку, а большинство сериализаторов (включая вывод JSON) разворачивают их в обычные копии. Используйте якоря для настоящего переиспользования (шаблоны, значения по умолчанию), а не для микрооптимизации.
# Caveat 1: shared identity can surprise you
defaults: &defaults
list: [1, 2, 3]
a: *defaults
b: *defaults
# In mutable parsers, a.list and b.list are the SAME list.
# Editing a.list also changes b.list.
# Caveat 2: anchors add cognitive overhead
# Overuse makes YAML hard to read and trace.
# Caveat 3: not all tools preserve anchors on output
# Many serializers expand aliases to plain copies.
# Caveat 4: JSON output loses anchors entirely
# (JSON has no anchor concept).
# Caveat 5: anchors don't work across documents
---
doc1: &x value
use1: *x
---
doc2: *x # ERROR
# Prefer anchors for genuine reuse, not micro-optimization.Merge keys (<<)
Базовое слияние (<<)
Merge key << берёт отображение (обычно алиас) и сливает его пары ключ-значение в текущее отображение. Ключи, явно заданные в текущем отображении, переопределяют слитые. Это канонический паттерн наследования конфигурации в YAML.
# << merges a referenced mapping into the current one
defaults: &defaults
adapter: postgres
pool: 5
timeout: 5000
development:
<<: *defaults
database: myapp_dev
host: localhost
production:
<<: *defaults
database: myapp_prod
host: db.example.com
pool: 20 # override
# Result for development:
# adapter: postgres
# pool: 5
# timeout: 5000
# database: myapp_dev
# host: localhostНесколько слияний
<< может сливать несколько отображений, если передать flow-последовательность алиасов ([*a, *b, *c]). Слияния применяются слева направо; более поздние переопределяют ранние для дублирующихся ключей. Явные ключи в отображении всегда побеждают любой слитый ключ. Несколько записей << тоже разрешены.
# << can merge multiple mappings (sequence value)
base: &base
logging: info
retries: 3
security: &security
auth: required
tls: true
service: &service
port: 8080
host: 0.0.0.0
# Merge multiple in one go
production:
<<: [*base, *security, *service]
environment: prod
port: 80 # override service.port
# Later merges override earlier ones for the same key.
# Explicit keys always win over merges.
# You can also have multiple << entries:
combined:
<<: *base
<<: *security
custom: valueПереопределение и приоритет
Приоритет слияния: явные ключи в отображении всегда побеждают. Среди слитых отображений более поздние в последовательности переопределяют ранние для одного ключа. Используйте это, чтобы чисто наслаивать переопределения: значения по умолчанию, затем ролевые, затем специфичные для инстанса.
# Explicit keys override merged keys
template: &template
port: 8080
log: info
timeout: 30
instance:
<<: *template
port: 9090 # overrides template.port
log: debug # overrides template.log
host: example.com # added
# Final: {port: 9090, log: debug, timeout: 30, host: example.com}
# Precedence: explicit > later merge > earlier merge
a: &a
k: from_a
x: 1
b: &b
k: from_b
y: 2
result:
<<: [*a, *b]
k: explicit # wins over both a and b
# Final: {k: explicit, x: 1, y: 2}Паттерн слияния с якорями
Паттерн merge и anchor — хлеб Docker Compose и похожих конфигов: определите якорь defaults, затем каждый сервис сливает его и переопределяет отдельные поля. Это держит конфиги DRY, не жертвуя настройкой каждого сервиса.
# Common pattern: anchor templates, merge + override
defaults: &defaults
image: nginx:1.25
restart: always
logging:
driver: json-file
services:
web:
<<: *defaults
ports: ["80:80"]
api:
<<: *defaults
image: node:20 # override
ports: ["8080:8080"]
environment:
NODE_ENV: production
worker:
<<: *defaults
image: worker:latest
command: ["./run.sh"]
# This is the bread-and-butter of Docker Compose files
# — share base config, override per service.Ограничения merge
Merge key << работает только для отображений — последовательности и скаляры сливать нельзя. Слияние поверхностное: вложенное отображение в текущем узле ЗАМЕНЯЕТ слитое целиком (без глубокого слияния). Для глубокого слияния перестройте данные или делайте это в коде приложения.
# << only works for MAPPINGS, not sequences or scalars
list_template: &list [1, 2, 3]
# This does NOT merge list items:
combined:
<<: *list # WRONG: *list is a sequence, not a mapping
extra: value # parse error or unexpected behavior
# Deep merge is NOT supported
parent: &parent
nested:
a: 1
b: 2
child:
<<: *parent
nested:
c: 3 # REPLACES parent.nested entirely
# Result: {nested: {c: 3}} — NOT {nested: {a:1, b:2, c:3}}
# To deep-merge, you must do it in application code
# or restructure the data.Статус и устаревание merge key
Merge key << был расширением YAML 1.1, удалённым из ядра спецификации YAML 1.2. На практике большинство парсеров его поддерживает (PyYAML, js-yaml, ruamel, SnakeYAML), но строгие парсеры 1.2 его отвергают. Используйте сегодня, но помните, что это нестандартно; для новых форматов рассмотрите конфигурационные языки с настоящим наследованием (Cue, Jsonnet, Dhall).
# IMPORTANT: the << merge key was REMOVED in YAML 1.2
# It was a YAML 1.1 feature.
# In practice, many parsers still support it:
# - PyYAML: supports (1.1 mode)
# - js-yaml: supports (opt-in)
# - ruamel.yaml: supports
# - SnakeYAML: supports
# - LibYAML: supports
# But strict YAML 1.2 parsers reject it:
# new_yaml_1_2_strict:
# <<: *template # ERROR in strict 1.2
# Recommendation:
# - Use << for now (widely supported)
# - Document that your files rely on it
# - For new formats, consider composition in code
# or a config language with proper inheritance
# (e.g. Dhall, Cue, Jsonnet)
# Alternative without <<:
# just duplicate or use application-level templatingМаркеры документов и директивы
Один документ
Один YAML-документ прекрасно работает без маркеров. Ведущий --- — соглашение, сигнализирующее «это YAML», и отграничение от простого текста. Маркер конца ... необязателен и редко используется в файлах с одним документом.
# A single YAML document needs no markers
key: value
list:
- a
- b
# But a leading --- is a common convention
# to mark "this is YAML, not plain text"
---
key: value
# The trailing ... (end marker) is optional
# for a single document
key: value
...Несколько документов (поток)
YAML-поток — последовательность документов, разделённых ---. Каждый документ разбирается независимо. Потоки часты в Kubernetes (несколько объектов в одном файле), генераторах статических сайтов и логах. Используйте load_all() или эквивалент в вашем парсере для перебора документов.
# A YAML stream is multiple documents separated by ---
---
name: first
value: 1
---
name: second
value: 2
---
name: third
value: 3
# Each document is independent — anchors don't cross
# Use a parser's load_all() / load_multi() to read them
# Python (PyYAML):
# for doc in yaml.safe_load_all(stream):
# print(doc)
# Common use cases:
# - Kubernetes: multiple objects in one file
# - Blog generators: front matter + content
# - Log files: one record per document
# - CI/CD: multi-step pipelinesМаркер конца документа (...)
Маркер ... явно завершает документ. Он необязателен в большинстве случаев, но полезен, когда контент может быть неоднозначным (например, литеральный блок, содержащий ---). Он также сигнализирует конец документа потоковым парсерам. Редок в рукописном YAML, но част в программном выводе.
# ... explicitly ends a document
---
key: value
...
# Anything after ... is a new document or stream end
# Useful when a document's content might be ambiguous
# without an explicit end:
---
message: |
Some content
---
that looks like a separator
...
---
next: document
# Without ... the parser might think the ---
# inside the literal block is a document separator
# (though block scalars usually prevent this)
# ... is also useful in programmatic output to flushДирективы
Директивы идут перед контентом документа и настраивают парсер. %YAML задаёт версию; %TAG объявляет сокращения префиксов тегов. Директивы ограничены документом: они применяются только к следующему документу. Большинство конфигов опускает директивы и полагается на значения парсера по умолчанию (обычно 1.1 или двурежимный 1.2).
# Directives appear at the very top, before content
# %YAML — declare YAML version
%YAML 1.2
---
key: value
# %TAG — declare a tag prefix
%TAG !e! tag:example.com,2024:
---
data: !e!custom value
# Multiple directives are allowed
%YAML 1.2
%TAG !e! tag:example.com,2024:
%TAG !yaml! tag:yaml.org,2002:
---
value: !yaml!str hello
# Directives are document-scoped — they apply to the
# next document only and must be repeated for each.
# Most config files omit directives and use defaults.Примеры потоков документов
Потоки документов широко используются. Kubernetes применяет их, чтобы упаковать несколько объектов (Namespace, Deployment, Service) в один файл. Шаблоны Helm, лог и CI и генераторы статических сайтов (front matter и контент) тоже используют потоки. Каждый документ независим и может иметь свои директивы.
# Kubernetes multi-object file
---
apiVersion: v1
kind: Namespace
metadata:
name: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
namespace: production
spec:
replicas: 3
---
apiVersion: v1
kind: Service
metadata:
name: api
namespace: production
spec:
ports:
- port: 80
# Helm chart templates: stream of objects
# CI logs: one event per document
# Static site generator: front matter + bodyЛовушки границ
Строка, начинающаяся с --- в колонке 0, всегда разделитель документов (вне блочных скаляров). Внутри блочных скаляров (|, >) --- это литеральный контент. Чтобы включить --- в колонке 0 в значение, сделайте отступ блока или сначала завершите документ через ... . --- с контентом в той же строке — маркер начала документа, а не разделитель.
# A line starting with --- is ALWAYS a document separator
# (when at column 0). This can surprise you:
---
script: |
echo hello
--- # this is INSIDE the block scalar — safe
next: value
# But this is NOT safe:
---
content: |
line1
---
mistaken: this is a NEW document, not part of content!
# Inside block scalars, --- is literal (good).
# Outside, --- at column 0 always separates documents.
# Workaround for content that must contain --- at col 0:
# indent the block, or use ... to end the doc first.
# Also: a bare --- line with content on the same line
# is the document start marker, NOT a separator
--- key: value # this is one documentFlow-стиль
Flow-последовательности
Flow-последовательности используют [ ] и ведут себя как массивы JSON. Пробелы и переводы строк внутри гибкие. В отличие от JSON, висячие запятые НЕ допускаются. Полезны для коротких плотных списков. Закавычивайте элементы, содержащие спецсимволы (запятые, скобки, двоеточия).
# Flow sequences use [item1, item2, ...]
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]
# Empty
empty: []
# Nested flow sequences
matrix: [[1, 2], [3, 4]]
# Flow sequence of mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]
# Multi-line flow sequence (whitespace is flexible)
long: [
alpha,
beta,
gamma
]
# Quoting inside flow
mixed: ["hello", 'world', 42, true]
# NO trailing comma
bad: [1, 2, 3,] # parse errorFlow-отображения
Flow-отображения используют { } и ведут себя как объекты JSON. Ключи можно закавычивать, когда они содержат спецсимволы. Пробелы гибкие. Висячие запятые запрещены (в отличие от JSON). Используйте flow-отображения для коротких плотных данных; блочный стиль читаемее для крупных структур.
# Flow mappings use {key: value, ...}
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}
# Empty mapping
empty: {}
# Nested flow mappings
nested: {a: {b: {c: value}}}
# Quoted keys (needed for special chars)
quoted: {"key with space": value, "weird:key": 1}
# Multi-line flow mapping
config: {
host: localhost,
port: 8080,
debug: true
}
# Flow mapping with flow sequence value
mixed: {nums: [1, 2, 3], name: test}
# NO trailing comma
bad: {a: 1, b: 2,} # parse errorСмешение flow и block
Flow- и block-стили можно свободно смешивать в документе. Прагматичное правило: используйте block для структурных элементов (лучше читаемость с отступами) и flow для коротких inline-значений (списки скаляров, небольшие словари). Избегайте глубоко вложенного flow — он быстро становится нечитаемым.
# Mix flow and block styles freely
config:
name: myapp
ports: [80, 443] # flow sequence in block mapping
endpoints: {api: /v1, web: /} # flow mapping in block
# Block inside flow (less common but valid)
flow_with_block: [{name: Alice, roles: [admin, user]}, {name: Bob}]
# Flow at top level
[top, level, flow]
# Block at top level
- block
- sequence
# Pragmatic rule:
# - Block for structure (readability)
# - Flow for short inline values
# - Avoid deeply nested flow — it becomes unreadableВложенный flow
Flow-стиль может вкладываться сколь угодно глубоко, но каждый уровень добавляет скобки, которые становятся нечитаемыми. После 1–2 уровней вложенности переходите на block ради читаемости. Блочный эквивалент глубоко вложенного flow почти всегда яснее для людей-сопровождающих.
# Flow can nest arbitrarily
data: {users: [{name: Alice, tags: [a, b]}, {name: Bob}]}
# Equivalent block:
# data:
# users:
# - name: Alice
# tags:
# - a
# - b
# - name: Bob
# Multi-line nested flow (rare but valid)
matrix: {
rows: [
[1, 2, 3],
[4, 5, 6]
],
cols: 3
}
# Recommendation: switch to block style after 1-2 levels
# of nesting — flow becomes a "wall of brackets".Когда использовать flow
Используйте flow для коротких списков скаляров, небольших словарей поиска, однострочных записей и вывода, совместимого с JSON. Избегайте flow для длинных списков (трудно сканировать), глубоко вложенных структур (стена скобок) и всего, что требует inline-комментариев. Если сомневаетесь, предпочитайте block ради читаемости.
# Good uses of flow style:
# 1. Short lists of scalars
ports: [80, 443, 8080]
colors: [red, green, blue]
# 2. Small lookup maps
codes: {200: OK, 404: NotFound, 500: Error}
# 3. Single-line records in a sequence
coordinates:
- {x: 1, y: 2}
- {x: 3, y: 4}
- {x: 5, y: 6}
# 4. JSON-compatible output (flow is JSON-compatible)
# Bad uses of flow style:
# 1. Long lists (use block)
# ports: [80, 443, 8080, 8443, 9000, 9090, 9091, ...] # hard to read
# 2. Deeply nested (use block)
# {a: {b: {c: {d: {e: value}}}}} # unreadable
# 3. Anything with comments (flow doesn't allow inline comments well)Оговорки flow-стиля
У flow-стиля есть оговорки: спецсимволы (запятые, двоеточия, скобки) нужно закавычивать; висячие запятые нельзя; комментарии неудобны; нет блочных скаляров | или > (используйте \n в двойных кавычках); однострочные изменения труднее диффать. Block дружелюбнее для конфигов под контролем версий.
# Caveat 1: special characters need quotes in flow
flow: [a, b, "c,d", "d:e"] # commas and colons need quoting
block:
- a
- b
- c,d # no quotes needed in block style
- d:e # no quotes needed in block style
# Caveat 2: no trailing commas
bad: [1, 2, 3,] # error
# Caveat 3: comments are awkward in flow
config: {
host: localhost, # comment allowed but clunky
port: 8080
}
# Caveat 4: flow style has no multi-line strings
# (no | or > inside flow)
# You can use \n escapes in double quotes:
text: "line1\nline2"
# Caveat 5: flow is harder to diff in version control
# (one-line changes vs whole-block changes)Конвертация YAML и JSON
JSON — валидный YAML
YAML 1.2 спроектирован так, что JSON — строгое подмножество: любой JSON-документ является валидным YAML. Большинство YAML-парсеров спокойно читают JSON. Обратное неверно: такие возможности YAML, как комментарии, якоря, потоки документов и блочные скаляры, не являются валидным JSON.
# JSON is a strict subset of YAML 1.2
# Any JSON file is valid YAML
# This is valid YAML (it's JSON):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# So is this multi-line JSON:
{
"name": "Alice",
"age": 30,
"hobbies": ["a", "b"]
}
# Parsers usually accept JSON files as YAML
# Python: yaml.safe_load(json_string) # works
# JS: YAML.load(json_string) # works
# Go: yaml.Unmarshal(json_bytes, &v) # works (yaml.v3)
# But the reverse is NOT always true:
# YAML with comments, anchors, multi-docs is NOT valid JSONЭквивалентные представления
JSON, блочный YAML и flow-YAML могут представлять одни и те же данные. JSON самый переносимый (в каждом языке есть JSON-парсер). Блочный YAML самый читаемый для людей. Flow-YAML — компактная золотая середина. Выбирайте по аудитории: инструменты (JSON) или люди (блочный YAML).
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# YAML block:
name: Alice
age: 30
hobbies:
- a
- b
# YAML flow (closest to JSON):
{name: Alice, age: 30, hobbies: [a, b]}
# YAML with quotes (JSON-compatible):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# All four parse to the same data structure.
# Pick the style that fits your use case:
# - JSON for interop and strict tools
# - YAML block for human-edited config
# - YAML flow for compact inline dataКонвертация JSON в YAML
Конвертируйте JSON в YAML, разобрав JSON и выгрузив как YAML с default_flow_style=False (блочный стиль). Обязательные кавычки JSON отбрасываются там, где YAML их не требует. Следите за ключами, похожими на числа или boolean: в YAML их может понадобиться закавычить, чтобы сохранить строковый тип.
# Convert JSON to YAML using a parser
# Python:
# import json, yaml
# data = json.loads(json_string)
# yaml_str = yaml.safe_dump(data, default_flow_style=False, sort_keys=False)
#
# JS:
# const data = JSON.parse(jsonString)
# const yamlStr = yaml.dump(data)
# Example input JSON:
# {"server": {"host": "localhost", "port": 8080}, "debug": true}
# Output YAML:
# server:
# host: localhost
# port: 8080
# debug: true
# Conversion considerations:
# - JSON keys are always quoted -> YAML usually unquotes them
# - JSON arrays -> YAML block sequences (with default_flow_style=False)
# - JSON strings with special chars may need quoting
# - JSON null -> YAML null (or ~)
# - JSON booleans/numbers preservedКонвертация YAML в JSON
Конвертируйте YAML в JSON, разобрав, затем сериализовав в JSON. Оговорки: комментарии и теги теряются; якоря разворачиваются в обычные копии; потоки документов должны стать JSON-массивом; YAML-даты могут стать строками. Инструменты вроде yq упрощают это в командной строке.
# Convert YAML to JSON
# Python:
# import json, yaml
# data = yaml.safe_load(yaml_string)
# json_str = json.dumps(data, indent=2)
# JS:
# const data = yaml.load(yamlString)
# const jsonStr = JSON.stringify(data, null, 2)
# Command-line tools:
# yq -o=json '.config' file.yaml # mikefarah/yq
# ruby -ryaml -rjson -e 'puts JSON.generate(YAML.load(STDIN.read))' < file.yaml
# python -c 'import json,sys,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))'
# Caveats when converting YAML to JSON:
# - YAML comments are LOST (JSON has no comments)
# - YAML anchors are EXPANDED to plain copies
# - YAML multi-doc streams become a JSON array (or fail)
# - YAML tags (!!) are lost or cause errors
# - YAML dates may become strings (JSON has no date type)JSON-совместимое подмножество
JSON-совместимое подмножество YAML избегает комментариев, якорей, нескольких документов, тегов, блочных скаляров и простых строк, похожих на другие типы. Пребывание в этом подмножестве гарантирует чистые круговые преобразования в JSON. Полезно, когда одни и те же данные читают и YAML-, и JSON-потребители, или когда важно строгое сохранение типов.
# To produce YAML that round-trips to JSON cleanly,
# stay within the JSON-compatible subset:
# 1. No comments
# 2. No anchors/aliases
# 3. No multi-doc streams
# 4. No tags
# 5. No block scalars (|, >) — use \n in double-quoted strings
# 6. Quote all string keys (JSON requires this)
# 7. No plain strings that look like other types
# JSON-compatible YAML:
{"name": "Alice", "age": 30, "active": true}
{"items": ["a", "b", "c"]}
{"nested": {"key": "value"}}
# Useful when you need both YAML and JSON consumers
# for the same data, or want strict type preservation.
# Many YAML dumpers have a "json-compatible" mode.Соображения кругового преобразования
Круговое преобразование YAML (разбор, затем выгрузка) часто теряет комментарии, имена якорей, порядок ключей, стиль кавычек и форматирование. ruamel.yaml (Python) имеет режим round-trip, сохраняющий комментарии и порядок. Для конфигов, редактируемых людьми, никогда не перезаписывайте слепо выводом дампера — сначала внимательно сравните diff.
# Round-trip: YAML -> parse -> dump -> YAML
# Information that may be LOST:
# - Comments (most dumpers drop them)
# - Anchor names (dumpers may re-create or expand)
# - Key order (some dumpers sort keys)
# - Quoting style (dumpers choose their own)
# - Flow vs block style (dumpers usually pick one)
# - Whitespace and indentation amount
# - Multi-document structure (sometimes)
# - Tag prefixes and %TAG directives
# Tools that preserve style:
# - ruamel.yaml (Python): round-trip mode preserves comments/order
# - yaml.v3 (Go): preserves key order
# - prettier with yaml plugin: normalizes formatting
# For config files where humans edit:
# - Use ruamel.yaml round-trip mode
# - Or accept that dumps are "normalized"
# - Never overwrite human-edited files with dumper output
# without diffing carefullyСхемы YAML
Схема Failsafe
Схема Failsafe самая консервативная: она распознаёт только str, map и seq. Все скаляры — строки, если явно не помечены тегом. Полезна для недоверенного ввода (никаких сюрпризов неявного приведения) или как база для своих схем. Большинство продакшен-загрузчиков используют чуть более богатую схему.
# Failsafe schema — the most conservative
# Recognizes ONLY three types: str, map, seq
# Everything else is a string
# Under Failsafe:
value: 42 # str "42" (NOT int)
flag: true # str "true" (NOT bool)
empty: null # str "null" (NOT null)
date: 2024-01-01 # str "2024-01-01" (NOT date)
# Use explicit tags to get other types
int_value: !!int 42
bool_value: !!bool true
null_value: !!null null
# When to use Failsafe:
# - Untrusted input (no implicit type coercion)
# - When you want strings only
# - As a base for custom schemas
# PyYAML: SafeLoader uses a schema close to Failsafe
# but with int/float/bool/null inference.Схема JSON
Схема JSON точно соответствует системе типов JSON: str, int, float, bool, null, map, seq. Она строже схемы Core: нет восьмеричных и двоичных литералов, нет разделителей-подчёркиваний, boolean только true/false, без вывода дат. Используйте для интеропа с JSON или строгого поведения типов.
# JSON schema — same type system as JSON
# Recognizes: str, int, float, bool, null, map, seq
# Under JSON schema:
int: 42 # int
float: 3.14 # float
str: hello # str
bool: true # bool
null_val: null # null
list: [1, 2, 3] # seq
map: {a: 1} # map
# Differences from Core schema:
# - Stricter number parsing (no 0o octal, no _ separators)
# - Booleans are only true/false (no yes/no)
# - No date/timestamp inference
# When to use JSON schema:
# - Interop with JSON tools
# - Strict type behavior
# - When you want JSON's type semanticsСхема Core
Схема Core — значение по умолчанию в YAML 1.2. Она расширяет JSON мягким разбором: hex (0x), octal (0o), binary (0b), подчёркивания в числах, float .inf/.nan. Boolean только true/false (не yes/no). Даты — строки (без вывода). Большинство современных парсеров по умолчанию использует Core или вариант, совместимый с 1.1.
# Core schema — the DEFAULT for YAML 1.2
# Extends JSON schema with more lenient scalar resolution
# Under Core schema:
int: 42 # int
neg: -17 # int
hex: 0xFF # int (255)
oct: 0o17 # int (15) [YAML 1.2 syntax]
bin: 0b1010 # int (10)
float: 3.14 # float
exp: 1.0e+3 # float
inf: .inf # float
nan: .nan # float
bool: true # bool (only true/false, not yes/no)
null: null # null (also ~, empty)
str: hello # str
date: 2024-01-01 # str (Core does NOT infer dates)
# Differences from YAML 1.1:
# - yes/no/on/off are STRINGS (not booleans)
# - 017 is a string (octal is 0o17 in 1.2)
# - Dates are strings (no implicit inference)
# Most modern parsers default to Core or close to it.YAML 1.1 против 1.2
YAML 1.1 (по умолчанию в PyYAML) трактует yes/no/on/off как boolean, а числа с ведущим 0 — как восьмеричные: знаменитые источники багов (норвежское 'no' превращается в false). YAML 1.2 (текущая спецификация) ограничивает boolean true/false и использует 0o для восьмеричных. Всегда проверяйте значение парсера по умолчанию и закавычивайте неоднозначные строки.
# YAML 1.1 (older, used by PyYAML by default)
bool_1_1: yes # true (yes/no/on/off are booleans)
octal_1_1: 017 # 15 (leading 0 = octal)
sexagesimal: 1:30 # 90 (base-60!) - obscure feature
# YAML 1.2 (current spec)
bool_1_2: yes # str "yes" (only true/false are bool)
octal_1_2: 0o17 # 15 (explicit 0o prefix)
no_sexagesimal: 1:30 # str "1:30"
# Practical impact:
# - "no" (Norway) becomes False in PyYAML (1.1)
# - "010" becomes 8 in PyYAML, "010" in 1.2
# - "on"/"off" become True/False in 1.1, strings in 1.2
# PyYAML: defaults to 1.1 behavior
# ruamel.yaml: defaults to 1.2 (with 1.1 compatibility options)
# js-yaml: defaults to 1.1 with 1.2 options
# Go yaml.v3: defaults to 1.2-ish
# Always check your parser's default schema!Различия разрешения типов
Разрешение типов различается между парсерами YAML 1.1 и 1.2: yes/no/on/off, числа с ведущим нулём и шестидесятеричные литералы разбираются по-разному. Смягчайте закавычиванием неоднозначных строк, фиксацией версии через %YAML, явными тегами и тестированием на всех целевых парсерах.
# Same YAML, different parsers, different types:
value: yes
# PyYAML (1.1): True (bool)
# js-yaml (1.1): true (bool)
# ruamel (1.2): "yes" (str)
# Go yaml.v3 (1.2): "yes" (str)
# Strict 1.2: "yes" (str)
value: 010
# PyYAML (1.1): 8 (int, octal)
# ruamel (1.2): "010" (str)
# Go yaml.v3 (1.2): "010" (str)
value: 1.0
# All: 1.0 (float) - consistent
value: true
# All: true (bool) - consistent
# Mitigation strategies:
# 1. Quote strings that look like other types
# 2. Pin the YAML version with %YAML 1.2
# 3. Use explicit tags (!!) for critical values
# 4. Test against all target parsersВыбор схемы
Выбирайте схему по сценарию: 1.2 Core для новых проектов (предсказуемо), 1.1 для интеропа с PyYAML (или закавычивайте неоднозначные строки), Failsafe или JSON для недоверенного ввода, JSON-схему для интеропа с JSON. Для конфигов 1.2 Core плюс закавычивание неоднозначных строк («no», «010» и т. п.) — самая безопасная комбинация.
# Recommendations for choosing a schema:
# 1. For NEW projects: use YAML 1.2 Core schema
# - More predictable (no yes/no surprises)
# - Modern parsers support it
# - ruamel.yaml, Go yaml.v3 default to it
# 2. For INTEROP with existing PyYAML code:
# - Either accept 1.1 semantics
# - Or use ruamel.yaml with 1.2 + preserve 1.1 features
# - Quote all ambiguous strings explicitly
# 3. For UNTRUSTED input: use Failsafe or JSON schema
# - No implicit type coercion
# - Smaller attack surface
# - Predictable behavior
# 4. For CONFIG FILES: use 1.2 Core + quote ambiguous strings
# - "no", "yes", "on", "off", "010", "1.0" should be quoted
# - Document your schema choice
# - Lint with yamllint
# 5. For JSON INTEROP: use JSON schema
# - Same types as JSON
# - Round-trips cleanlyЛинт и валидация YAML
yamllint
yamllint — стандартный линтер YAML (Python). Он ловит синтаксические ошибки, проблемы отступов, хвостовые пробелы, отсутствующие маркеры документов и другое. Используйте его в CI и pre-commit хуках, чтобы ловить проблемы YAML рано. Строгий режим (-s) трактует предупреждения как ошибки.
# yamllint is the standard YAML linter
# Install: pip install yamllint
# Lint a file
# yamllint config.yaml
# Lint with strict mode (warnings = errors)
# yamllint -s config.yaml
# Output example:
# config.yaml
# 3:4 error mapping values are not allowed here
# 5:1 error syntax error: found character ' ' that cannot start any token
# 8:3 warning missing document start "---"
# 12:5 warning comment is not indented like content
# Lint multiple files
# yamllint file1.yaml file2.yaml file3.yaml
# Lint a directory (recursive)
# yamllint -d path/to/dir
# Read from stdin
# cat config.yaml | yamllint -Конфигурация линта
Настраивайте yamllint через .yamllint.yml. Расширьте профиль (default или strict), затем переопределите отдельные правила: отступы, длину строки, стиль кавычек, комментарии, хвостовые пробелы, маркеры документов. Подстройте под стиль коман ды. Запускайте в CI для единообразия.
# .yamllint.yml — configuration file for yamllint
# Place in project root or ~/.config/yamllint/config
# Use a built-in profile
extends: default
# Or use a stricter profile
# extends: strict
# Override specific rules
rules:
# Require document start marker
document-start: disable
# Enforce 2-space indentation
indentation:
spaces: 2
indent-sequences: true
# Max line length
line-length:
max: 120
allow-non-breakable-words: true
# Disallow trailing spaces
trailing-spaces: enable
# Require consistent quoting
quoted-strings:
quote-type: double
required: only-when-needed
# Disallow comments without space before #
comments:
require-starting-space: true
min-spaces-from-content: 1Частые синтаксические ошибки
Частые ошибки YAML: табы для отступов (допустимы только пробелы), двоеточие без следующего пробела, незакавыченные строки с двоеточиями (разбираются как отображения), висячие запятые в flow-стиле, несогласованные отступы и дубликаты ключей. Линтер ловит всё это автоматически.
# Error: tab characters for indentation
# bad:
# key: value <- tab not allowed
# Fix: use spaces only
# Error: colon without space
# bad: key:value
# good: key: value
# Error: unquoted special characters
# bad: url: http://example.com:8080 <- parsed as mapping
# good: url: "http://example.com:8080"
# Error: trailing comma in flow
# bad: list: [1, 2, 3,]
# good: list: [1, 2, 3]
# Error: inconsistent indentation
# bad:
# key1: value
# key2: value <- one extra space
# good:
# key1: value
# key2: value
# Error: duplicate keys (some parsers warn)
# bad:
# key: first
# key: second
# good: rename oneОшибки табов и пробелов
Табы строго запрещены для структурных отступов YAML — причина ошибок разбора номер один. Табы внутри строковых значений (блочные скаляры, строки в кавычках) допустимы. Настройте редактор на пробелы (expandtab) для YAML-файлов. Находите проблемные строки через grep -P '\t'.
# YAML FORBIDS tabs for indentation.
# This is the #1 cause of YAML parse errors.
# Symptom: parser error like
# "found character '\t' that cannot start any token"
# or "while scanning for the next token, found tab"
# Tabs are allowed INSIDE string values:
script: |
#!/bin/bash
if [ -f file ]; then # this is fine (literal content)
\techo found # \t inside block scalar is OK
# But tabs for STRUCTURAL indentation are forbidden:
# bad:
# services:
# \tweb:
# \t\timage: nginx
# Fix: convert tabs to spaces
# Configure your editor to use spaces for YAML files
# VS Code: "editor.insertSpaces": true, "editor.tabSize": 2
# Vim: set expandtab shiftwidth=2
# Detect tabs:
# grep -P '\t' file.yaml (finds offending lines)Поиск дубликатов ключей
Дубликаты ключей в отображении не рекомендуются и являются частым источником багов (тихое переопределение, где побеждает последний). yamllint находит их правилом key-duplicates (включено по умолчанию). Частые причины: ошибки копирования и плохое разрешение merge-конфликтов. Всегда линтуйте в CI, чтобы ловить их рано.
# Duplicate keys are technically discouraged
# but YAML 1.2 doesn't strictly forbid them.
# Behavior varies by parser (usually last-wins).
config:
host: localhost
port: 8080
host: prod.example.com # silent override!
# yamllint catches these:
# 4:3 error duplication of key "host" in mapping
# Enable in .yamllint.yml:
# rules:
# key-duplicates: enable
# Other tools that detect duplicates:
# - kubeval (for Kubernetes YAML)
# - yq (programmatic checks)
# - Custom schema validation (JSON Schema)
# Common cause: copy-paste errors, merge conflicts
# resolved incorrectly. Always lint in CI to catch.Валидация схемы
Валидируйте структуру YAML через JSON Schema (работает, потому что YAML — надмножество JSON). Для Kubernetes используйте kubeval или kubectl --dry-run. Для общего конфига используйте yamllint (синтаксис и стиль) плюс jsonschema (структура) или Cue (язык схем). Встройте валидацию в pre-commit хуки и CI.
# Validate YAML against a JSON Schema
# (JSON Schema works on YAML since YAML is a JSON superset)
# Python example with jsonschema + PyYAML:
# import json, yaml, jsonschema
# with open('schema.json') as f: schema = json.load(f)
# with open('config.yaml') as f: doc = yaml.safe_load(f)
# jsonschema.validate(doc, schema)
# Tools for Kubernetes YAML:
# kubeval - validate against K8s schemas
# kubectl apply --dry-run=client -f file.yaml
# conftest - policy-based validation (OPA)
# Tools for general YAML:
# yamllint - syntax + style
# jsonschema-cli - JSON Schema validation
# cue - schema + validation language
# dataladen - config validation
# Pre-commit hook example (.pre-commit-config.yaml):
# repos:
# - repo: https://github.com/adrienverge/yamllint
# rev: v1.32.0
# hooks:
# - id: yamllint
# args: [-s]YAML Docker Compose
Определение сервиса
Файлы Docker Compose определяют многоконтейнерные приложения. Ключи верхнего уровня: version, services, volumes, networks, configs, secrets. Каждый сервис задаёт image/build, ports, volumes, environment, depends_on, политику restart. Тома, объявленные на верхнем уровне, именованные и персистентные.
# docker-compose.yml — multi-container apps
version: "3.9" # compose file format version
services:
web:
image: nginx:1.25
ports:
- "80:80"
- "443:443"
volumes:
- ./html:/usr/share/nginx/html:ro
restart: unless-stopped
depends_on:
- api
api:
build:
context: ./api
dockerfile: Dockerfile
environment:
- NODE_ENV=production
- DB_URL=postgres://db:5432/app
ports:
- "8080:8080"
restart: always
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secret
volumes:
- db_data:/var/lib/postgresql/data
restart: always
volumes:
db_data:Тома и сети
Тома Compose бывают bind mount (host:container), именованные (объявлены в верхнеуровневых volumes) или анонимные. Суффикс :ro делает монтирование read-only. Сети изолируют сервисы; internal: true блокирует внешний доступ. Именованные тома сохраняют данные между пересозданиями контейнеров.
services:
web:
image: nginx
volumes:
# Bind mount: host:container
- ./html:/usr/share/nginx/html:ro
# Named volume: name:container
- shared_data:/data
# Anonymous volume
- /tmp/cache
networks:
- frontend
- backend
db:
image: postgres
volumes:
- db_data:/var/lib/postgresql/data
networks:
- backend
volumes:
db_data:
driver: local
shared_data:
driver: nfs
driver_opts:
type: nfs
device: ":/path/to/share"
networks:
frontend:
driver: bridge
backend:
driver: bridge
internal: true # no external accessПеременные окружения
Compose поддерживает три стиля env-переменных: список (KEY=value), словарь (KEY: value) и env_file. ${VAR} интерполируется из shell хоста или файла .env при разборе; ${VAR:-default} даёт значение по умолчанию. Используйте $$, чтобы экранировать литеральный $. Файл .env в корне проекта загружается автоматически.
services:
api:
image: myapi
# Method 1: list of KEY=value
environment:
- NODE_ENV=production
- LOG_LEVEL=info
# Method 2: map (cleaner)
environment:
NODE_ENV: production
LOG_LEVEL: info
# Method 3: file
env_file:
- .env
- .env.production
# Interpolation from host environment
environment:
- API_KEY=${API_KEY} # from shell
- PORT=${PORT:-8080} # default 8080
# .env file (auto-loaded by docker compose):
# API_KEY=abc123
# PORT=8080
# DB_URL=postgres://...
# Compose substitutes ${VAR} from host shell or .env
# Use $$ to escape (literal $):
# - TOKEN=price_$$5 # produces price_$5Depends, healthchecks и restart
depends_on с condition: service_healthy ждёт прохождения healthcheck зависимости перед запуском. Healthchecks используют test (CMD или CMD-SHELL), interval, timeout, retries, start_period. Политики restart: no, always, unless-stopped (переживает перезагрузки, но уважает ручную остановку), on-failure.
services:
api:
image: myapi
depends_on:
db:
condition: service_healthy # wait for db healthy
redis:
condition: service_started
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
db:
image: postgres
restart: always
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
# restart policies:
# no - never restart (default)
# always - always restart on stop
# unless-stopped - restart unless manually stopped
# on-failure - restart only on non-zero exitOverride-файлы
Compose сливает override-файлы поверх базового. docker-compose.override.yml применяется автоматически. Отображения сливаются глубоко (переопределения побеждают); последовательности обычно заменяются (не дописываются) — следите за ports и volumes. Используйте флаги -f, чтобы задать явный порядок файлов для конфигов конкретных окружений.
# docker-compose.yml — base
services:
web:
image: nginx
ports:
- "80:80"
environment:
- ENV=base
# docker-compose.override.yml — auto-applied on top
# (loaded automatically by 'docker compose up')
services:
web:
ports:
- "8080:80" # overrides "80:80"
environment:
- DEBUG=true # added
- ENV=override # overrides ENV=base
volumes:
- ./dev.conf:/etc/nginx/conf.d/default.conf
# Multiple override files (-f flag):
# docker compose -f compose.yml -f compose.prod.yml -f compose.secrets.yml up
# Merge rules:
# - mappings: deep-merged (overrides win, others kept)
# - sequences: usually REPLACED (not appended) —
# ports/depends_on/volumes are exceptions in some versions
# Use -f to specify explicit file orderПрофили и возможности Compose
Профили позволяют включать сервисы по выбору (например, debug, test, ci) флагом --profile. Другие возможности v3: init (корректная обработка сигналов как PID 1), extends (наследование от другого сервиса), configs и secrets (монтируются как файлы), deploy (размещение, реплики и ресурсы Swarm). Профили хороши, чтобы держать один compose-файл для нескольких окружений.
# Profiles — opt-in services
services:
web:
image: nginx
# no profile: always started
debug:
image: busybox
profiles: ["debug"] # only with --profile debug
loadtest:
image: locust
profiles: ["test", "ci"]
# Enable a profile:
# docker compose --profile debug up
# docker compose --profile test --profile ci up
# Compose file format features (v3.9+):
# - deploy: placement, replicas, resources (Swarm-only in v3)
# - configs: external config files
# - secrets: mounted secret files
# - extends: inherit from another service
# - init: run tini as PID 1
services:
worker:
image: worker
init: true # proper signal handling
extends:
service: base # inherit fields
configs:
- config1
secrets:
- api_key
configs:
config1:
file: ./config.toml
secrets:
api_key:
file: ./api_key.txtYAML Kubernetes
Структура объекта
У каждого объекта Kubernetes есть apiVersion, kind, metadata и spec. apiVersion — группа и версия (например, apps/v1, v1 для core). metadata включает name, namespace, labels, annotations. spec — желаемое состояние: Kubernetes стремится привести реальность к spec. status задаёт система.
# Every Kubernetes object has the same 4 top-level fields
apiVersion: apps/v1 # API group + version
kind: Deployment # object type
metadata: # identity
name: my-app
namespace: production
labels:
app: my-app
tier: backend
annotations:
deployment.kubernetes.io/revision: "1"
spec: # desired state
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: app
image: my-app:1.0.0
ports:
- containerPort: 8080
# apiVersion + kind + metadata + spec is the universal shape
# (some objects use status too, but you don't set it)Labels и селекторы
Labels идентифицируют и группируют объекты; селекторы запрашивают по labels. Поддерживаются селекторы на равенстве (key=value) и на множествах (In, NotIn, Exists, DoesNotExist). Annotations хранят неидентифицирующие метаданные (описания, контакты, конфигурацию инструментов). Labels — для выбора; annotations — для дополнительной информации.
# Labels — identify and group objects
metadata:
labels:
app: my-app
tier: backend
env: production
version: "1.0"
# Selectors — query objects by labels
# Equality-based
selector:
matchLabels:
app: my-app
env: production
# Set-based
selector:
matchExpressions:
- {key: tier, operator: In, values: [backend, api]}
- {key: env, operator: NotIn, values: [dev]}
- {key: version, operator: Exists}
# kubectl commands:
# kubectl get pods -l app=my-app
# kubectl get pods -l 'tier in (backend,api),env!=dev'
# kubectl get pods -l app=my-app -l env=production
# Annotations — non-identifying metadata
metadata:
annotations:
description: "My app deployment"
contact: "[email protected]"Pod spec
Spec Pod определяет контейнеры, их образы, порты, env-переменные (литеральные или из secrets и configmaps), ресурсы (requests/limits), пробы (readiness/liveness), тома и volumeMounts. Pods — минимальная развёртываемая единица, но обычно их создают через Deployments, а не напрямую.
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- name: app
image: my-app:1.0
ports:
- containerPort: 8080
name: http
env:
- name: LOG_LEVEL
value: info
- name: SECRET_KEY
valueFrom:
secretKeyRef:
name: app-secrets
key: secret-key
resources:
requests: {cpu: 100m, memory: 128Mi}
limits: {cpu: 500m, memory: 512Mi}
readinessProbe:
httpGet: {path: /health, port: 8080}
initialDelaySeconds: 5
periodSeconds: 10
volumeMounts:
- name: config
mountPath: /etc/config
volumes:
- name: config
configMap:
name: app-config
restartPolicy: AlwaysDeployment
Deployment управляет ReplicaSets и Pods. spec.replicas задаёт желаемое количество. strategy.type может быть RollingUpdate (по умолчанию, управляется maxSurge/maxUnavailable) или Recreate. Шаблон pod (spec.template) определяет, как создаются pod'ы. Управляйте rollout'ами через kubectl rollout status/undo/history.
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 3
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: app
image: my-app:1.0.0
ports:
- containerPort: 8080
resources:
requests: {cpu: 100m, memory: 128Mi}
limits: {cpu: 500m, memory: 512Mi}
readinessProbe:
httpGet: {path: /ready, port: 8080}
# Rollback / history
# kubectl rollout status deployment/my-app
# kubectl rollout undo deployment/my-app
# kubectl rollout history deployment/my-appService
Service открывает Pods как сетевой сервис. type ClusterIP (по умолчанию) только внутренний; NodePort открывает на каждом узле; LoadBalancer создаёт облачный LB; ExternalName — DNS CNAME. selector направляет трафик к подходящим pod'ам. ports сопоставляют порт сервиса с targetPort контейнера (число или имя).
apiVersion: v1
kind: Service
metadata:
name: my-app
spec:
type: ClusterIP # ClusterIP (default), NodePort, LoadBalancer, ExternalName
selector:
app: my-app # routes to pods with these labels
ports:
- name: http
port: 80 # service port
targetPort: 8080 # container port (or named port)
protocol: TCP
- name: https
port: 443
targetPort: 8443
# NodePort: exposes on each node's IP at a static port (30000-32767)
# LoadBalancer: provisions a cloud LB
# ExternalName: CNAME to an external service
# Service types:
# ClusterIP - internal cluster IP (default)
# NodePort - exposes on node port + ClusterIP
# LoadBalancer - cloud LB + NodePort + ClusterIP
# ExternalName - DNS CNAME (no proxying)ConfigMap и Secret
ConfigMaps хранят нечувствительную конфигурацию (строки или файлы); Secrets — чувствительные данные (base64 в data или открытый текст в stringData). Оба потребляются через env-переменные (valueFrom) или монтируются как тома. Secrets по умолчанию НЕ шифруются — включите шифрование в покое и ограничьте доступ через RBAC.
# ConfigMap — non-sensitive configuration
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
log_level: info
max_connections: "100"
config.yaml: |
server:
host: 0.0.0.0
port: 8080
---
# Secret — sensitive data (base64-encoded)
apiVersion: v1
kind: Secret
metadata:
name: app-secrets
type: Opaque
data:
# base64-encoded values
api_key: c2VjcmV0LWtleS0xMjM= # echo -n 'secret-key-123' | base64
db_password: cGFzc3dvcmQ=
# Or use stringData for plain text (auto-encoded):
# stringData:
# api_key: secret-key-123
# Consumed by pods:
# env:
# - name: API_KEY
# valueFrom:
# secretKeyRef:
# name: app-secrets
# key: api_key
# volumes:
# - name: config
# configMap:
# name: app-configКонфигурация CI/CD (GitHub Actions и GitLab CI)
Workflow GitHub Actions
Workflow GitHub Actions живут в .github/workflows/. on: триггеры (push, PR, schedule, workflow_dispatch). jobs содержат runs-on и steps. uses: ссылается на actions, run: выполняет shell. Выражения используют синтаксис ${{ }} — внутри YAML-шаблонных литералов их нужно экранировать как \${{ }}.