feat: Создана полная документация проекта с централизованным хранением
- Создан новый README.md с полной документацией проекта - Перемещены все MD файлы в папку /docs - Создана структура документации: - docs/universal-lab.md - руководство по лаборатории - docs/presets.md - описание всех 21 пресета - docs/roles.md - структура и создание Ansible ролей - docs/examples.md - практические примеры использования - docs/troubleshooting.md - решение проблем - docs/api.md - справочник по API Основные возможности документации: - Полное описание всех возможностей лаборатории - 21 готовый пресет для различных сценариев - Подробные инструкции по использованию - Примеры создания собственных пресетов - Руководство по созданию Ansible ролей - Troubleshooting для решения проблем - API Reference для всех команд и параметров Структура проекта: - README.md - основная документация с ссылками - docs/ - централизованное хранение документации - molecule/presets/ - 21 готовый пресет - files/ - файлы для ролей и playbooks - scripts/ - скрипты для управления лабораторией Автор: Сергей Антропов Сайт: https://devops.org.ru
This commit is contained in:
572
docs/api.md
Normal file
572
docs/api.md
Normal file
@@ -0,0 +1,572 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
### 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
|
||||
# Создание снапшотов лаборатории
|
||||
|
||||
# Параметры
|
||||
OUT_DIR="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
|
||||
# Восстановление из снапшотов
|
||||
|
||||
# Параметры
|
||||
IN_DIR="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
|
||||
# Очистка лаборатории
|
||||
|
||||
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).
|
||||
Reference in New Issue
Block a user