Работа с YAML в Kubernetes

Введение

Работа с Kubernetes тесно связана с использованием файлов YAML. Если вы управляете деплоем приложений, настройкой сервисов, созданием конфигураций или политик безопасности, то YAML становится обязательной частью вашего ежедневного опыта. В Kubernetes описание ресурсов — от простых Pod-ов до сложных сетевых политик — базируется на структуре, которую вы записываете в виде человекочитаемого текстового файла с расширением .yaml или .yml. Здесь я покажу вам как эффективно использовать YAML для управления ресурсами Kubernetes, какие особенности нужно учитывать, и дам конкретные примеры использования.

Что такое YAML и почему он используется в Kubernetes

Общие сведения о YAML

YAML (YAML Ain’t Markup Language — YAML не язык разметки) — это формат сериализации данных, который очень легко читать человеку. Он основан на структированном отступах тексте, похожем на Python-стиль отбивки пробелами, и используется для конфигурирования, обмена данными и другого.

Почему Kubernetes использует YAML

Kubernetes управляет различными объектами (pods, deployments, services и др.), описанными в виде ресурсов API. YAML идеально подходит для такой задачи благодаря простоте, наглядности и поддержке вложенных структур.

• YAML хорошо подходит для описания иерархических структур данных, таких как спецификации Kubernetes.
• Уменьшает вероятность ошибок по сравнению с аналогичной записью в JSON.
• Легко воспринимается глазами, моментально видна структура ресурса.

Основные структуры YAML в Kubernetes

Давайте разберём, как выглядит типичный YAML-файл для Kubernetes и какие ключевые поля в нём используются.

Пример простого YAML-файла для Pod

Здесь я размещаю пример конфигурации:

apiVersion: v1              # Версия API Kubernetes
kind: Pod                   # Тип ресурса - Pod
metadata:                   # Метаинформация о ресурсе
  name: simple-pod          # Имя Pod
  labels:                   # Метки (ключ-значение)
    app: demo
spec:                       # Спецификация, описывающая содержимое Pod
  containers:               # Контейнеры внутри Pod
    - name: main-container  # Имя контейнера
      image: nginx:1.21     # Имя и версия Docker-образа
      ports:                # Открытые порты
        - containerPort: 80

Разбор основных полей

• apiVersion — указывает версию API для данного ресурса. Это важно при миграциях ресурсов между версиями Kubernetes.
• kind — определяет тип ресурса (Pod, Deployment, Service и пр.).
• metadata — данные о ресурсе: имя, метки, аннотации.
• spec — контейнер для описания спецификации ресурса. Здесь указывается всё, что касается сущности, которую вы разворачиваете в кластере.

Структуры с несколькими объектами

В Kubernetes YAML-файл может содержать несколько объектов одновременно. Для этого используется разделитель ---.

Давайте посмотрим, как это реализовано:

---
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: demo
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: demo
  template:
    metadata:
      labels:
        app: demo
    spec:
      containers:
      - name: main
        image: nginx:1.21

Комментарии к примеру выше

• С помощью --- вы можете объединять описание Service и Deployment, чтобы применить всё разом.
• Каждый новый объект начинается с разделителя.
• Когда вы применяете такой файл командой, все ресурсы создаются последовательно.

Как применять YAML-файлы в Kubernetes

Использование kubectl

Главная команда для работы со всеми YAML-файлами — это kubectl apply. Покажу вам, как это делается.

kubectl apply -f path/to/your-file.yaml  # Применяет всё, что описано в файле

• -f указывает путь к файлу или директории с файлами.

Проверка и удаление объектов

Также вам пригодятся команды:

kubectl get pods                     # Показать все поды
kubectl describe pod simple-pod      # Подробно описать pod
kubectl delete -f your-file.yaml     # Удалить все объекты, описанные в файле

Основные возможности YAML в Kubernetes

Метки (labels) и селекторы

Метки используются для логической группировки ресурсов и последующего поиска или управления ими.

metadata:
  labels:
    environment: production
    tier: frontend

Для выбора ресурсов, собранных по меткам, используются селекторы:

spec:
  selector:
    matchLabels:
      environment: production
      tier: frontend

Это позволяет, например, связать Pod-ы и Service внутри одного приложения по их назначению или окружению.

Аннотации

Аннотации (annotations) похожи на метки, но используются для хранения произвольной нефильтруемой информации (например, версии деплоя, команды автообновления).

metadata:
  annotations:
    deployment.kubernetes.io/revision: "2"

Аннотации не влияют на выборку ресурсов — только для описания.

Использование переменных и шаблонов (Helm и Kustomize)

Иногда вам требуется шаблонизировать YAML для разных окружений (staging, production и др.). Для этого в Kubernetes существует два подхода: Helm и Kustomize.

Helm Charts

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

Пример шаблона Helm:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
      - name: main
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

• {{ .Release.Name }} и {{ .Values.replicaCount }} — переменные, которые подставляются во время установки чарта.

Kustomize

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

Пример использования Kustomize:

kustomization.yaml:

resources:
- deployment.yaml

patchesStrategicMerge:
- patch.yaml

Где patch.yaml содержит частичный YAML только для изменяемых полей.

Секреты и ConfigMap

Конфигурационные файлы и секреты часто хранятся отдельно от приложения. В Kubernetes есть специальные ресурсы для этого — ConfigMap и Secret.

Пример ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  CONFIG_PARAM: "value"

Подключение ConfigMap в Pod:

spec:
  containers:
  - name: app
    image: my-app
    envFrom:
    - configMapRef:
        name: my-config

Пример Secret

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
type: Opaque
data:
  SECRET_KEY: bXktc2VjcmV0LXZhbHVl # base64-кодированное значение

Проверка и валидация YAML

Перед применением файла важно подтвердить его корректность.

Линтинг и валидация

• Используйте онлайн-валидаторы (например, yamlvalidator.com) для быстрой проверки структуры.
• kubectl apply --dry-run=client -f your-file.yaml — покажет потенциальные ошибки конструкции без реального применения к кластеру.

Проверка отступов и структуры

В YAML иерархия описывается только пробелами! Самая частая ошибка для новичков — неверные отступы.

• Используйте ровные отступы по 2 или 4 пробела.
• Не допускайте смешивания табуляций и пробелов.

Вот пример ошибки:

spec:
   containers:  # Отступ 3 пробела — плохо!
  - name: wrong-indent
    image: busybox

Здесь Kubernetes скорее всего не сможет распарсить спецификацию контейнера.

Продвинутые функции: Anchors и Aliases в YAML

YAML поддерживает дублирование блоков с помощью якорей (&) и ссылок (*). Это упрощает описание однотипных объектов. Смотрите, как это работает на практике.

default-resources: &default
  limits:
    memory: "128Mi"
    cpu: "500m"

apiVersion: v1
kind: Pod
metadata:
  name: with-default-limits
spec:
  containers:
    - name: app
      image: nginx
      resources:
        <<: *default # Используем дефолтные лимиты через alias

• С помощью &default вы создаёте якорь, а *default подставляет содержимое.

Используйте anchors там, где конфигурация часто повторяется — это экономит время и уменьшает количество ошибок.

Практические советы по работе с YAML в Kubernetes

Разбейте длинные файлы

Лучше разделить сложную структуру на несколько файлов по типу ресурса (deployment.yaml, service.yaml, configmap.yaml) — так легче поддерживать инфраструктуру.

Всегда используйте Git

Храните все ваши YAML-файлы в системе контроля версий. Это защитит от потери изменений и упростит совместную работу над инфраструктурой.

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

Добавляйте пояснения к нестандартным решениям и настройкам, чтобы спустя время самому или вашей команде было проще разобраться в логике.

Внимательно следите за apiVersion

Разные версии Kubernetes поддерживают различные версии API для ресурсов. Например, Deployment в Kubernetes 1.16+ использует apiVersion: apps/v1, а ранее был extensions/v1beta1.

Проверьте актуальные версии перед деплоем:

kubectl api-versions

Как устроены Manifest-файлы в Kubernetes

Каждый YAML-файл — это манифест объекта Kubernetes, которым вы управляете через API. Стандартная структура:

• apiVersion — версия используемого API
• kind — тип ресурса (Pod, Deployment, Service, Secret и т.д.)
• metadata — имя, метки, аннотации
• spec — спецификация желаемого состояния объекта

При подаче файла через kubectl, Kubernetes сравнивает текущее состояние с желаемым (что описано в вашем YAML), и производит нужные действия для достижения нужного состояния.

Частые ошибки при работе с YAML в Kubernetes

• Неправильные отступы (например, 3 пробела или табуляции)
• Перезапись ресурсов неверными селекторами — тогда сервисы не могут найти нужные поды
• Забыли указать обязательные поля (например, selector в Deployment)
• Применили устаревшую apiVersion
• Перепутали тип поля — например, указали числом, где ожидалась строка или наоборот

Заключение

YAML-файлы — основной инструмент для управления инфраструктурой Kubernetes. Они позволяют описывать желаемое состояние объектов в кластере, легко читаются и поддерживаются. Вам стоит освоить не только базовую структуру, но и тонкие настройки: использование шаблонов, разделения конфигурации, работу с метками, селекторами, секретами. При работе всегда обращайте внимание на корректность синтаксиса YAML, используйте систему контроля версий, и не забывайте валидировать свои манифесты перед деплоем. Аккуратное составление YAML-файлов облегчает вам и вашей команде работу с Kubernetes и снижает риск ошибок.

Частозадаваемые технические вопросы по теме статьи и ответы на них

Как заменить значение переменной в уже существующем YAML-файле?

Для быстрой замены переменных без пересоздания файла используйте например утилиту yq:

yq eval '.spec.replicas = 5' -i deployment.yaml  # Заменит количество реплик на 5

Как посмотреть, какие значения фактически подставились из Helm-шаблонов?

Выполните команду рендера Helm без деплоя:

helm template mychart/     # Покажет итоговые YAML-файлы после подстановки всех переменных

Как быстро найти ошибку в формате YAML?

Используйте валидацию через kubectl:

kubectl apply -f your-file.yaml --dry-run=client  # Покажет ошибку синтаксиса без деплоя

а также онлайн-валидаторы или утилиты yamllint/yamale.

Как создать Secret, не кодируя вручную данные в base64?

Можно воспользоваться Linux-командой:

kubectl create secret generic my-secret --from-literal=PASS=my_password --dry-run=client -o yaml > secret.yaml

или использовать echo -n 'my_password' | base64 для мануального получения значения.

Как прописать несколько контейнеров в одном Pod через YAML?

В секцию spec.containers добавьте несколько элементов:

spec:
  containers:
    - name: app1
      image: nginx
    - name: app2
      image: redis

Kubernetes запустит оба контейнера в едином поде.