feat: Полная переработка документации и структуры проекта
- Переписан главный README.md с подробной навигацией - Создана структурированная документация в docs/: - getting-started.md - быстрый старт - creating-roles.md - создание ролей - cicd-setup.md - настройка CI/CD - monitoring.md - мониторинг и диагностика - site-yml-guide.md - руководство по site.yml - molecule-guide.md - подробное руководство по Molecule - Переписан dockerfiles/README.md с детальным описанием всех образов - Перенесен deploy.yml из корня в roles/ для лучшей организации - Обновлен site.yml для импорта roles/deploy.yml - Добавлены fallback значения в create.yml для надежности - Созданы скрипты автоматизации: - update-playbooks.sh - обновление playbook'ов - generate-role-docs.sh - генерация документации - setup-cicd.sh - настройка CI/CD - Добавлен env.example с примерами переменных - Обновлен Makefile с новыми командами автоматизации - Улучшена навигация по документации
This commit is contained in:
Сергей Антропов
291
docs/getting-started.md
Normal file
291
docs/getting-started.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# Быстрый старт с AnsibleTemplate
|
||||
|
||||
**Автор:** Сергей Антропов
|
||||
**Сайт:** https://devops.org.ru
|
||||
|
||||
## 🚀 Установка и настройка
|
||||
|
||||
### 1. Клонирование репозитория
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-username/AnsibleTemplate.git
|
||||
cd AnsibleTemplate
|
||||
```
|
||||
|
||||
### 2. Настройка переменных окружения
|
||||
|
||||
```bash
|
||||
# Копирование файла переменных
|
||||
cp env.example .env
|
||||
|
||||
# Редактирование переменных
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 3. Настройка Docker
|
||||
|
||||
```bash
|
||||
# Настройка multi-arch builder
|
||||
make docker setup-builder
|
||||
|
||||
# Сборка всех образов
|
||||
make docker build
|
||||
|
||||
# Проверка собранных образов
|
||||
make docker info
|
||||
```
|
||||
|
||||
## 🧪 Первое тестирование
|
||||
|
||||
### 1. Просмотр доступных preset'ов
|
||||
|
||||
```bash
|
||||
# Список всех preset'ов
|
||||
make presets list
|
||||
|
||||
# Информация о конкретном preset'е
|
||||
make presets info PRESET=default
|
||||
```
|
||||
|
||||
### 2. Тестирование роли ping
|
||||
|
||||
```bash
|
||||
# Тестирование с default preset
|
||||
make role test
|
||||
|
||||
# Тестирование с minimal preset
|
||||
make role test minimal
|
||||
```
|
||||
|
||||
### 3. Проверка результатов
|
||||
|
||||
```bash
|
||||
# Просмотр логов
|
||||
docker logs ansible-controller
|
||||
|
||||
# Вход в контейнер для отладки
|
||||
docker exec -it ansible-controller bash
|
||||
```
|
||||
|
||||
## 🔧 Создание первой роли
|
||||
|
||||
### 1. Создание структуры роли
|
||||
|
||||
```bash
|
||||
# Создание директории роли
|
||||
mkdir -p roles/my-role/{tasks,handlers,templates,files,vars,defaults,meta}
|
||||
|
||||
# Создание основных файлов
|
||||
touch roles/my-role/{tasks,handlers,meta}/main.yml
|
||||
touch roles/my-role/defaults/main.yml
|
||||
touch roles/my-role/vars/main.yml
|
||||
touch roles/my-role/README.md
|
||||
```
|
||||
|
||||
### 2. Разработка роли
|
||||
|
||||
**`roles/my-role/tasks/main.yml`:**
|
||||
```yaml
|
||||
---
|
||||
# Основные задачи для роли my-role
|
||||
# Автор: Сергей Антропов
|
||||
# Сайт: https://devops.org.ru
|
||||
|
||||
- name: Установка пакетов
|
||||
package:
|
||||
name: "{{ my_role_packages }}"
|
||||
state: present
|
||||
when: my_role_enabled | default(true)
|
||||
tags:
|
||||
- my-role
|
||||
- install
|
||||
|
||||
- name: Настройка конфигурации
|
||||
template:
|
||||
src: my-role.conf.j2
|
||||
dest: /etc/my-role/my-role.conf
|
||||
owner: root
|
||||
group: root
|
||||
mode: '0644'
|
||||
notify: restart my-role
|
||||
tags:
|
||||
- my-role
|
||||
- config
|
||||
```
|
||||
|
||||
**`roles/my-role/defaults/main.yml`:**
|
||||
```yaml
|
||||
---
|
||||
# Переменные по умолчанию для роли my-role
|
||||
# Автор: Сергей Антропов
|
||||
# Сайт: https://devops.org.ru
|
||||
|
||||
# Основные настройки
|
||||
my_role_enabled: true
|
||||
my_role_packages:
|
||||
- nginx
|
||||
- curl
|
||||
|
||||
# Конфигурация
|
||||
my_role_config_file: /etc/my-role/my-role.conf
|
||||
my_role_log_level: info
|
||||
```
|
||||
|
||||
### 3. Тестирование роли
|
||||
|
||||
```bash
|
||||
# Lint проверка
|
||||
make role lint
|
||||
|
||||
# Тестирование в Docker
|
||||
make role test minimal
|
||||
|
||||
# Тестирование с custom preset
|
||||
make role test my-custom-preset
|
||||
```
|
||||
|
||||
## 🚀 Развертывание на продакшн
|
||||
|
||||
### 1. Настройка инвентори
|
||||
|
||||
**`inventory/hosts.ini`:**
|
||||
```ini
|
||||
# Продакшн серверы
|
||||
[web_servers]
|
||||
web1.example.com ansible_host=192.168.1.10
|
||||
web2.example.com ansible_host=192.168.1.11
|
||||
|
||||
[db_servers]
|
||||
db1.example.com ansible_host=192.168.1.20
|
||||
db2.example.com ansible_host=192.168.1.21
|
||||
|
||||
[all:vars]
|
||||
ansible_user=devops
|
||||
ansible_ssh_private_key_file=~/.ssh/id_rsa
|
||||
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
|
||||
```
|
||||
|
||||
### 2. Настройка SSH ключей
|
||||
|
||||
```bash
|
||||
# Генерация SSH ключа
|
||||
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa
|
||||
|
||||
# Копирование ключа на серверы
|
||||
ssh-copy-id devops@web1.example.com
|
||||
ssh-copy-id devops@web2.example.com
|
||||
```
|
||||
|
||||
### 3. Тестирование подключения
|
||||
|
||||
```bash
|
||||
# Проверка подключения
|
||||
ansible all -i inventory/hosts.ini -m ping
|
||||
|
||||
# Dry-run развертывания
|
||||
make role deploy
|
||||
```
|
||||
|
||||
### 4. Развертывание
|
||||
|
||||
```bash
|
||||
# Развертывание на продакшн
|
||||
make role deploy
|
||||
# Подтвердить развертывание: y
|
||||
```
|
||||
|
||||
## 🔐 Управление секретами
|
||||
|
||||
### 1. Инициализация vault
|
||||
|
||||
```bash
|
||||
# Создание файла пароля
|
||||
make vault init
|
||||
|
||||
# Создание файла секретов
|
||||
make vault create
|
||||
```
|
||||
|
||||
### 2. Работа с секретами
|
||||
|
||||
```bash
|
||||
# Редактирование секретов
|
||||
make vault edit
|
||||
|
||||
# Просмотр секретов
|
||||
make vault show
|
||||
|
||||
# Шифрование файла
|
||||
make vault encrypt
|
||||
```
|
||||
|
||||
## 🏗️ CI/CD интеграция
|
||||
|
||||
### 1. GitHub Actions
|
||||
|
||||
```yaml
|
||||
# .github/workflows/ansible-test.yml
|
||||
name: Ansible Testing
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Run tests
|
||||
run: make role test
|
||||
```
|
||||
|
||||
### 2. Azure DevOps
|
||||
|
||||
```yaml
|
||||
# azure-pipelines.yml
|
||||
trigger:
|
||||
- main
|
||||
pool:
|
||||
vmImage: 'ubuntu-latest'
|
||||
stages:
|
||||
- stage: Test
|
||||
jobs:
|
||||
- job: TestJob
|
||||
steps:
|
||||
- script: make role test
|
||||
```
|
||||
|
||||
## 📊 Мониторинг и диагностика
|
||||
|
||||
### 1. Диагностика Docker
|
||||
|
||||
```bash
|
||||
# Диагностика buildx проблем
|
||||
make docker diagnose
|
||||
|
||||
# Проверка builder'а
|
||||
make docker setup-builder
|
||||
|
||||
# Сброс builder'а при проблемах
|
||||
make docker reset-builder
|
||||
```
|
||||
|
||||
### 2. Логи и отчеты
|
||||
|
||||
```bash
|
||||
# Просмотр логов контейнера
|
||||
docker logs ansible-controller
|
||||
|
||||
# Вход в контейнер для отладки
|
||||
docker exec -it ansible-controller bash
|
||||
```
|
||||
|
||||
## 🎯 Следующие шаги
|
||||
|
||||
1. **Изучите документацию** по [созданию ролей](creating-roles.md)
|
||||
2. **Настройте CI/CD** по [инструкции](cicd-setup.md)
|
||||
3. **Изучите Docker образы** в [dockerfiles/README.md](../dockerfiles/README.md)
|
||||
4. **Настройте мониторинг** по [руководству](monitoring.md)
|
||||
|
||||
---
|
||||
|
||||
**Автор:** Сергей Антропов
|
||||
**Сайт:** https://devops.org.ru
|
||||
Reference in New Issue
Block a user