DevOpsLab/docs/api.md

API Reference

Автор

Сергей Антропов
Сайт: https://devops.org.ru

Описание

Этот документ содержит справочник по API универсальной лаборатории, включая все доступные команды, параметры и конфигурации.

Содержание

• Makefile команды
• Пресеты API
• Kubernetes API
• Docker API
• Molecule API
• Отчеты API
• Скрипты API

Makefile команды

Основные команды

Команда	Описание	Параметры
make lab-up	Поднять контроллер	-
make lab-down	Погасить контроллер	-
make lab-sh	Войти в контроллер	-
make lab-test	Полный цикл Molecule	SCENARIO=universal
make lab-create	Создать инфраструктуру	-
make lab-converge	Запустить роли	-
make lab-verify	Проверить работу	-
make lab-destroy	Уничтожить инфраструктуру	-
make lab-reset	Полный сброс	-

Kubernetes команды

Команда	Описание	Параметры
make kube-sh	Shell с kubectl	-
make kube-cmd	Выполнить kubectl команду	CLUSTER=lab CMD="get pods"
make kube-enter	Войти в кластер	CLUSTER=lab
make kiali-port-forward	Port-forward Kiali	CLUSTER=lab
make istio-gw-port-forward	Port-forward Istio Gateway	CLUSTER=lab
make grafana-port-forward	Port-forward Grafana	CLUSTER=lab
make prom-port-forward	Port-forward Prometheus	CLUSTER=lab
make kube-pf-stop	Остановить все port-forward	-

Отчеты и мониторинг

Команда	Описание	Параметры
make lab-report	Сгенерировать HTML отчет	-
make lab-snapshot	Сохранить снапшот	-
make lab-restore	Восстановить из снапшота	-
make lab-cleanup	Очистить лабораторию	-
make bookinfo-url	Получить URL Bookinfo	-
make grafana-open	Открыть Grafana	-

Pre-commit команды

Команда	Описание	Параметры
make pre-commit-install	Установить pre-commit хуки	-
make pre-commit-run	Запустить pre-commit	-

Пресеты API

Структура пресета

---
# ПРЕСЕТ: Название (количество машин)
# 
# Описание: Подробное описание пресета
# 
# Использование: make lab-test SCENARIO=universal LAB_SPEC=molecule/presets/your-preset.yml
# 
# Автор: Ваше имя
# Сайт: https://your-site.com

# Сеть для лаборатории
docker_network: labnet

# Kind кластеры (опционально)
kind_clusters:
  - name: cluster-name
    workers: 2
    api_port: 6443
    addons:
      ingress_nginx: true
      metrics_server: true
      istio: true
      kiali: true
      prometheus_stack: true
    ingress_host_http_port: 8081
    ingress_host_https_port: 8443

# Образы для разных семейств ОС
images:
  debian: "ghcr.io/ansible-community/molecule-ubuntu-systemd:jammy"
  rhel: "quay.io/centos/centos:stream9-systemd"

# Настройки по умолчанию для systemd контейнеров
systemd_defaults:
  privileged: true
  command: "/sbin/init"
  volumes:
    - "/sys/fs/cgroup:/sys/fs/cgroup:ro"
  tmpfs:
    - "/run"
    - "/run/lock"
  capabilities:
    - "SYS_ADMIN"

# Определение хостов лаборатории
hosts:
  - name: host-name
    family: debian|rhel
    type: systemd|dind|dood
    group: group-name
    publish:
      - "host-port:container-port"
    env:
      KEY: value
    volumes:
      - "host-path:container-path"
    tmpfs:
      - "/tmp"
    capabilities:
      - "SYS_ADMIN"

Параметры хостов

Параметр	Тип	Описание	Обязательный
name	string	Имя хоста	Да
family	string	Семейство ОС (debian/rhel)	Нет
type	string	Тип контейнера (systemd/dind/dood)	Нет
group	string	Группа хоста	Нет
publish	array	Публикация портов	Нет
env	object	Переменные окружения	Нет
volumes	array	Монтирование томов	Нет
tmpfs	array	Временные файловые системы	Нет
capabilities	array	Capabilities	Нет

Параметры Kind кластеров

Параметр	Тип	Описание	Обязательный
name	string	Имя кластера	Да
workers	integer	Количество worker узлов	Нет
api_port	integer	Порт API сервера	Нет
addons	object	Включенные аддоны	Нет
ingress_host_http_port	integer	HTTP порт для ingress	Нет
ingress_host_https_port	integer	HTTPS порт для ingress	Нет

Аддоны Kind кластеров

Аддон	Тип	Описание
ingress_nginx	boolean	Ingress NGINX контроллер
metrics_server	boolean	Metrics Server для метрик
istio	boolean	Istio service mesh
kiali	boolean	Kiali для визуализации
prometheus_stack	boolean	Prometheus + Grafana

Kubernetes API

kubectl команды

# Получить информацию о кластере
kubectl cluster-info

# Получить ноды
kubectl get nodes

# Получить поды
kubectl get pods -A

# Получить сервисы
kubectl get svc -A

# Получить события
kubectl get events --sort-by=.metadata.creationTimestamp

# Описать ресурс
kubectl describe pod <pod-name>

# Логи пода
kubectl logs <pod-name>

# Войти в под
kubectl exec -it <pod-name> -- /bin/sh

Ansible-lint команды

# Проверить весь проект
make lint

# Проверить роли
make role lint

# Проверить конкретную роль
ansible-lint --config-file .ansible-lint roles/my-role/

# Проверить playbook
ansible-lint --config-file .ansible-lint files/playbooks/site.yml

Настройки ansible-lint (.ansible-lint)

skip_list:
  - fqcn                                    # Полные имена модулей
  - yaml[new-line-at-end-of-file]          # Новая строка в конце файла
  - yaml[truthy]                           # Булевы значения
  - yaml[line-length]                      # Длина строки
  - var-naming[no-role-prefix]             # Префиксы переменных
  - 'ignore-errors'                        # Игнорирование ошибок

exclude_paths:
  - molecule/universal/                     # Исключить файлы Molecule
  - files/playbooks/                       # Исключить playbooks с Docker модулями

Описание пропускаемых правил:

• fqcn - позволяет использовать короткие имена модулей (например, yum вместо ansible.builtin.yum)
• yaml[new-line-at-end-of-file] - не требует новой строки в конце YAML файлов
• yaml[truthy] - позволяет использовать yes/no вместо true/false
• yaml[line-length] - не ограничивает длину строк в YAML
• var-naming[no-role-prefix] - не требует префиксов для переменных ролей
• ignore-errors - позволяет использовать ignore_errors: yes

Исключенные пути:

• molecule/universal/ - файлы Molecule с Docker модулями
• files/playbooks/ - playbooks с Docker Compose модулями

Port-forward команды

# Port-forward сервиса
kubectl port-forward svc/<service-name> <local-port>:<remote-port>

# Port-forward пода
kubectl port-forward pod/<pod-name> <local-port>:<remote-port>

# Port-forward в фоне
kubectl port-forward svc/<service-name> <local-port>:<remote-port> &

# Остановить все port-forward
pkill -f "kubectl .* port-forward"

Istio команды

# Проверить Istio
istioctl version

# Установить Istio
istioctl install --set profile=demo

# Удалить Istio
istioctl uninstall --purge

# Проверить статус
istioctl proxy-status

# Получить конфигурацию
istioctl proxy-config cluster <pod-name>

Docker API

Docker команды

# Список контейнеров
docker ps

# Список образов
docker images

# Список сетей
docker network ls

# Список томов
docker volume ls

# Информация о контейнере
docker inspect <container-name>

# Логи контейнера
docker logs <container-name>

# Войти в контейнер
docker exec -it <container-name> /bin/sh

Docker Compose команды

# Запустить стек
docker-compose up -d

# Остановить стек
docker-compose down

# Логи стека
docker-compose logs

# Масштабирование
docker-compose up --scale service=3

Docker Swarm команды

# Инициализировать Swarm
docker swarm init

# Присоединиться к Swarm
docker swarm join --token <token> <manager-ip>:2377

# Список нод
docker node ls

# Создать сервис
docker service create --name <service-name> <image>

# Масштабировать сервис
docker service scale <service-name>=3

Molecule API

Molecule команды

# Создать сценарий
molecule init scenario <scenario-name>

# Создать роль
molecule init role <role-name>

# Проверить синтаксис
molecule syntax

# Проверить конфигурацию
molecule lint

# Валидация
molecule validate

# Создать инфраструктуру
molecule create

# Запустить роли
molecule converge

# Проверить работу
molecule verify

# Уничтожить инфраструктуру
molecule destroy

# Полный цикл
molecule test

Конфигурация molecule.yml

---
driver:
  name: docker

platforms:
  - name: instance
    image: "ghcr.io/ansible-community/molecule-ubuntu-systemd:jammy"
    privileged: true
    pre_build_image: true
    command: "/sbin/init"
    volumes:
      - "/sys/fs/cgroup:/sys/fs/cgroup:ro"
    capabilities:
      - "SYS_ADMIN"
    tmpfs:
      - "/run"
      - "/run/lock"

provisioner:
  name: ansible
  config_options:
    defaults:
      stdout_callback: default
      callbacks_enabled: profile_tasks
  env:
    ANSIBLE_STDOUT_CALLBACK: default

dependency:
  name: galaxy
  enabled: false

verifier:
  name: ansible

lint: |-
  set -e
  ansible-lint

Отчеты API

HTML отчет

# Генерация отчета
python3 scripts/report_html.py <input.json> <output.html>

# Параметры
# input.json - JSON файл с данными
# output.html - HTML файл для вывода

JSON структура

{
  "timestamp": "2024-01-01T00:00:00Z",
  "idempotence_raw": "changed=0",
  "haproxy_select1": "1",
  "helm_ingress_toolbox_raw": "ingress ready",
  "istio_kiali_raw": "istio-system pods running",
  "istio_bookinfo_raw": "bookinfo deployed",
  "k8s_overview_raw": "nodes ready"
}

HTML структура

<!doctype html>
<html lang="ru">
<head>
  <meta charset="utf-8">
  <title>Lab Report</title>
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <style>
    /* CSS стили */
  </style>
</head>
<body>
  <div class="container">
    <div class="hdr">
      <h1>Ansible Lab Report</h1>
      <div class="time">generated: timestamp</div>
    </div>
    <div class="grid">
      <!-- Отчеты -->
    </div>
  </div>
</body>
</html>

Скрипты API

snapshot.sh

#!/usr/bin/env bash
# Создание снапшотов лаборатории (запускается через Docker)

# Параметры
OUT_DIR="/ansible/snapshots"

# Создать директорию
mkdir -p "$OUT_DIR"

# Получить ID контейнеров
ids=$(docker ps -q --filter "label=ansible.lab=true")

# Создать снапшоты
for id in $ids; do
  name=$(docker inspect --format '{{.Name}}' "$id" | sed 's#^/##')
  img="lab-snap-$name:latest"
  echo "[snapshot] $name -> $img"
  docker commit "$id" "$img" >/dev/null
  echo "$img" > "$OUT_DIR/$name.image"
done

restore.sh

#!/usr/bin/env bash
# Восстановление из снапшотов (запускается через Docker)

# Параметры
IN_DIR="/ansible/snapshots"

# Проверить директорию
[ -d "$IN_DIR" ] || { echo "No snapshots dir"; exit 1; }

# Восстановить контейнеры
for f in "$IN_DIR"/*.image; do
  [ -f "$f" ] || continue
  name=$(basename "$f" .image)
  img=$(cat "$f")
  echo "[restore] $name from $img"
  docker rm -f "$name" >/dev/null 2>&1 || true
  docker run -d --name "$name" "$img" >/dev/null
done

cleanup.sh

#!/usr/bin/env bash
# Очистка лаборатории (запускается через Docker)

echo "[cleanup] removing lab containers/volumes/networks"

# Удалить контейнеры
docker ps -aq --filter "label=ansible.lab=true" | xargs -r docker rm -f

# Удалить тома
docker volume ls -q --filter "name=_docker$" | xargs -r docker volume rm

# Удалить сеть
docker network rm labnet >/dev/null 2>&1 || true

echo "done."

Переменные окружения

Основные переменные

Переменная	Описание	Значение по умолчанию
LAB_SPEC	Путь к пресету	molecule/presets/minimal.yml
SCENARIO	Сценарий Molecule	universal
COMPOSE	Docker Compose команда	docker compose
ROLES_DIR	Директория с ролями	./roles
LAB_PAUSE_MINUTES	Пауза для ручной проверки	10

Kubernetes переменные

Переменная	Описание	Значение по умолчанию
KUBECONFIG	Путь к kubeconfig	~/.kube/config
KUBE_CONTEXT	Контекст Kubernetes	kind-lab
ISTIO_VERSION	Версия Istio	1.22.1
KIND_VERSION	Версия Kind	v0.23.0

Docker переменные

Переменная	Описание	Значение по умолчанию
DOCKER_HOST	Docker daemon адрес	unix:///var/run/docker.sock
DOCKER_TLS_CERTDIR	Директория TLS сертификатов	""
DOCKER_BUILDKIT	Использовать BuildKit	1

Конфигурационные файлы

docker-compose.yaml

version: "3.9"

services:
  ansible-controller:
    image: quay.io/ansible/creator-ee:latest
    container_name: ansible-controller
    privileged: true
    command: sleep infinity
    environment:
      DOCKER_HOST: unix:///var/run/docker.sock
      ANSIBLE_VAULT_PASSWORD_FILE: /ansible/vault-password.txt
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./molecule:/ansible/molecule
      - ./files:/ansible/files
      - ./vault-password.txt:/ansible/vault-password.txt
      - ${ROLES_DIR:-./roles}:/ansible/roles:ro
    working_dir: /ansible

.pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
  - repo: https://github.com/ansible/ansible-lint
    rev: v6.17.2
    hooks:
      - id: ansible-lint

Заключение

Этот справочник содержит все необходимые API для работы с универсальной лабораторией. Для получения дополнительной информации обратитесь к основной документации и примерам использования.