DevOpsLab/docs/api.md

# API Reference

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

## Описание

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

## Содержание

- [Makefile команды](#makefile-команды)
- [Пресеты API](#пресеты-api)
- [Kubernetes API](#kubernetes-api)
- [Docker API](#docker-api)
- [Molecule API](#molecule-api)
- [Отчеты API](#отчеты-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

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

```yaml
---
# ПРЕСЕТ: Название (количество машин)
# 
# Описание: Подробное описание пресета
# 
# Использование: 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 команды

```bash
# Получить информацию о кластере
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 команды

```bash
# Проверить весь проект
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)

```yaml
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 команды

```bash
# 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 команды

```bash
# Проверить 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 команды

```bash
# Список контейнеров
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 команды

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

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

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

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

### Docker Swarm команды

```bash
# Инициализировать 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 команды

```bash
# Создать сценарий
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

```yaml
---
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 отчет

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

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

### JSON структура

```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 структура

```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

```bash
#!/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

```bash
#!/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

```bash
#!/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

```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

```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 для работы с универсальной лабораторией. Для получения дополнительной информации обратитесь к [основной документации](universal-lab.md) и [примерам использования](examples.md).