ITSumma 28 фев 2024 в 13:35

Сборник советов, как упростить работу с YAML-файлами

Простой

5 мин

18K

Блог компании ITSummaСистемное администрирование*DevOps*

Туториал

YAML (.yml) — популярный язык для конфигурационных файлов, широко используемый DevOps в подходе «Инфраструктура как Код» (IaC). Несмотря на то, что работать с ним бывает проще, чем с тем же JSON (особенно в контексте взаимодействия с большими объемами данных), иногда использовать его бывает трудно. В этой статье мы рассмотрим несколько советов, которые помогут упростить процесс создания и редактирования yml-файлов.

Используйте специализированные редакторы и плагины

Установка в текстовый редактор IDE плагина с поддержкой YAML может в корне изменить процесс работы с этим форматом. Ведь они предоставляют целый набор полезных функций:

Подсветка синтаксиса. Все элементы YAML-файла (строки, числа, массивы и т.д.) выделяются разными цветами, что повышает читабельность и облегчает поиск ошибок.
Автодополнение кода. Плагин будет автоматически предлагать варианты написания элементов и тегов по мере ввода, избавляя от необходимости постоянно держать правила синтаксиса YAML в голове.
Проверка отступов. Плагины контролирует правильность и непротиворечивость структуры отступов в документе, не давая ошибиться со вложенностью.
Сниппеты (шаблоны кода). Можно заранее определить и использовать шаблоны типовых фрагментов конфигурации (например, объявления службы в docker-compose.yml).

Популярные плагины для работы с YAML: YAML Support для VS Code, yaml-mode для Emacs, drawspaces для Gedit. Их использование сэкономит массу времени и избавит от головной боли при написании сложных конфигурационных файлов.

Придерживайтесь best practices

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

Всегда заключайте строковые значения в кавычки. Если этого не сделать, YAML может неявно привести строку к числу, булевому значению или null, что приведет к неочевидным багам.
Используйте последовательную структуру отступов. Например, только пробелы или только табы. Смешение табуляции и пробелов часто становится источником ошибок.
Для логических значений применяйте только true/false. В YAML есть масса синонимов вроде yes/no, on/off, но это только добавляет путаницы.
Комментируйте все нетривиальные решения и неочевидные моменты в YAML-файлах с помощью "# ". Это сэкономит вам время при последующем изучении конфигурации.

Генерируйте YAML из кода

Ручное написание сложных вложенных конфигураций на YAML задача не из приятных. Гораздо проще сначала определить нужную структуру данных в виде словарей и массивов в том же Python,а затем сгенерировать из нее YAML с помощью соответствующей библиотеки.

Например, нужно определить такую структуру данных:

python
data = {
  "server": {
    "port": 8000,
    "enabled": true
  },
  "clients": [
    {"name": "Client1", "address": "192.168.1.100"}, 
    {"name": "Client2", "address": "192.168.1.101"}
  ]
}

Мы ее описали в Python, структурировали как нужно. Теперь с помощью библиотеки pyyaml легко конвертируем в YAML-файл:

python
import yaml
with open('config.yaml','w') as f:
  f.write(yaml.dump(data))

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

yaml  
server:
  port: 8000
  enabled: true
clients:
- address: 192.168.1.100
  name: Client1  
- address: 192.168.1.101
  name: Client2

Используйте валидаторы и линтеры

Специальные инструменты для анализа YAML-файлов помогут выявить множество потенциальных ошибок еще до запуска приложения.

yamllint — линтер YAML, который может быть легко встроен в CI/CD pipelines. Выдает предупреждения о потенциально опасных конструкциях и нарушениях правил синтаксиса.
drona — валидатор с уклоном на безопасность. Может проверить файлы на наличие уязвимых креденшалов, секретов и прочей скрытой информации.
kubeval - специальный валидатор для файлов с описаниями Kubernetes-ресурсов (deployments, services). Проверяет их соответствие схеме Kubernetes API.

Многие из этих утилит можно легко встроить в CI/CD, например развернув как предварительный шаг перед запуском приложения из нового образа.

Разбивайте конфигурации на фрагменты

Если YAML-файлы приложения разрастаются, их сложно обслуживать и модифицировать. Можно разделить код на несколько файлов с фрагментами — общими параметрами, настройками подсистем. Затем в основной файл подключать их через якоря.

Например, есть такой кусок конфигурации mysql-сервера:

yaml
mysql:
  image: mysql:8.0
  ports:
    - 3306:3306  
  environment:
    - MYSQL_ROOT_PASSWORD=passwd
    - MYSQL_DATABASE=appdb 
  volumes:
    - mysql-data:/var/lib/mysql
volumes:
  mysql-data:

Параметры подключения к БД используются также в конфигах других сервисов. Выносим их в отдельный файл `mysql-creds.yml`:

yaml  
&default_conn
user: 'root'
pass: 'passwd'  
db: 'appdb'

Теперь подключаем в основном конфиге через якорь `*`:

yaml
mysql:
  image: mysql:8.0
  environment:  
    MYSQL_ROOT_PASSWORD: *default_conn.pass
    MYSQL_DATABASE: *default_conn.db

Общие фрагменты теперь можно многократно использовать!

Создавайте шаблоны и заготовки

При работе с похожими конфигурационным файлами имеет смысл заготовить шаблоны. Намного проще взять существующую заготовку, подставить в нее данные приложения и получить готовый YAML-файл нужной структуры.

Например, при развертывании микросервисов в Kubernetes удобно для каждого из них иметь шаблон манифеста `deployment.yaml` :

yaml 
apiVersion: apps/v1
kind: Deployment 
metadata:
  name:  <service_name> 
  labels:  
    app: <service_name>
spec:
  replicas: 3
  template:
    metadata: 
      labels:
        app: <service_name>                
    spec:
      containers:
      - name: <service_name> 
        image: <image>:<tag>
        ports:
        - containerPort: <port> 
---        
apiVersion: v1
kind: Service

Здесь уже заданы структура и все нужные поля, остается только заполнить значениями (в угловых скобках).

Пишите автоматические тесты

Еще один способ упростить поддержку YAML в актуальном состоянии — написать автоматические тесты с использованием фреймворков вроде pytest. В них каждый YAML-файл будет импортироваться, проверяться на валидность и соответствие бизнес-требованиям.

Например, можно протестировать, что в конфигурации запуска приложения присутствуют нужные параметры:

python 
import yaml
import pytest

def test_config_has_variables(yaml_config):
  
  config = yaml.safe_load(yaml_config)  
  
  # Check properties 
  assert config['app']['version'] == '1.3' 
  assert config['database']['port'] == 3306
  
  # More assertions of config schema...

Такие тесты гарантируют, что инфраструктурный код не сломается после очередных изменений. Их можно запускать автоматически в рамках CI после любых коммитов в репозиторий.

Используйте визуальные редакторы

Если не хочется разбираться в синтаксисе и писать все вручную, попробуйте визуальные редакторы YAML. В них вы создаете конфигурационный файл, перетаскивая элементы и выставляя связи на диаграммах.

Популярные графические редакторы YAML:

Kui. Инструмент для создания манифестов ресурсов Kubernetes с помощью визуальных диаграмм
YAML Editor. Онлайн-редактор для общих конфигураций YAML с компонентами пользовательского интерфейса.

Такой подход больше подходит для структурирования простых и средних по сложности файлов.

Заключение

Работу с YAML можно значительно упростить и ускорить с помощью специализированных инструментов и подходов. Главное — выбрать подходящий для вас набор методов и последовательно его применять. Комбинация нескольких указанных советов (линтеры, генерация кода, шаблоны) способна полностью автоматизировать рутинную работу с конфигурационными файлами и избавить разработчика от бесконечной головной боли. Надеемся это сборник совет был вам полезен и желаем, чтобы работа с YAML была для вас легкой и приятной!

Теги:

Хабы: