DevOpsLab/docs/vault-guide.md

# Руководство по работе с Ansible Vault

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

## Описание

Это руководство описывает работу с зашифрованными секретами в Ansible Vault для проекта AnsibleTemplate.

## Безопасность

⚠️ **ВАЖНО**: Зашифрованные файлы содержат секретные данные и должны храниться в безопасности!

## Команды для работы с Vault

### Инициализация Vault

```bash
# Создание файла с паролем для vault
make vault init
```

### Основные операции

```bash
# Создание нового файла секретов
make vault create

# Редактирование существующих секретов
make vault edit

# Просмотр содержимого секретов
make vault show

# Шифрование существующего файла
make vault encrypt

# Расшифровка файла
make vault decrypt

# Смена пароля шифрования
make vault rekey

# Удаление файла секретов
make vault delete

# Проверка vault файлов
make vault check
```

## Структура файлов

```
vault/
├── .vault              # Файл с паролем для vault (НЕ коммитится в git)
├── secrets.yml         # Зашифрованный файл с секретами
└── secrets/            # Директория для незашифрованных секретов
    └── *.yml           # Незашифрованные файлы секретов
```

## Примеры использования

### 1. Создание нового файла секретов

```bash
# Создать новый файл
make vault create
# Введите имя файла (без .yml): my-secrets
```

### 2. Редактирование секретов

```bash
# Редактировать существующий файл
make vault edit
# Введите имя файла (без .yml): secrets
```

### 3. Просмотр секретов

```bash
# Показать содержимое файла
make vault show
# Введите имя файла (без .yml): secrets
```

### 4. Шифрование файла

```bash
# Зашифровать незашифрованный файл
make vault encrypt
# Введите имя файла (без .yml): secrets
```

### 5. Расшифровка файла

```bash
# Расшифровать файл для редактирования
make vault decrypt
# Введите имя файла (без .yml): secrets
```

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

### Передача пароля vault

```bash
# Запуск playbook с паролем vault
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --ask-vault-pass

# Использование файла с паролем
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --vault-password-file vault/.vault
```

### Переменные из vault

```yaml
# В playbook
- name: "Использование секретов из vault"
  hosts: all
  vars_files:
    - vault/secrets.yml
  tasks:
    - name: "Использование SSH ключа"
      authorized_key:
        user: "{{ devops_user.name }}"
        key: "{{ devops_ssh_keys.public_key }}"
```

## Безопасность и лучшие практики

### 1. Защита пароля vault

```bash
# Установка правильных прав на файл пароля
chmod 600 vault/.vault

# Добавление в .gitignore
echo "vault/.vault" >> .gitignore
```

### 2. Ротация паролей

```bash
# Смена пароля vault
make vault rekey
# Введите имя файла (без .yml): secrets
```

### 3. Резервное копирование

```bash
# Создание резервной копии зашифрованного файла
cp vault/secrets.yml vault/secrets.yml.backup

# Создание резервной копии пароля
cp vault/.vault vault/.vault.backup
```

### 4. Проверка целостности

```bash
# Проверка vault файлов
make vault check
```

## Troubleshooting

### Проблема: "Unable to read source file"

```bash
# Убедитесь, что файл существует
ls -la vault/*.yml

# Проверьте права доступа
ls -la vault/
```

### Проблема: "Vault password not provided"

```bash
# Убедитесь, что файл .vault существует
ls -la vault/.vault

# Проверьте содержимое файла
cat vault/.vault
```

### Проблема: "Invalid vault password"

```bash
# Проверьте пароль в файле .vault
cat vault/.vault

# Пересоздайте файл пароля
rm vault/.vault
make vault init
```

## Интеграция с CI/CD

### GitHub Actions

```yaml
# .github/workflows/deploy.yml
- name: "Deploy with Vault"
  run: |
    echo "${{ secrets.VAULT_PASSWORD }}" > vault/.vault
    ansible-playbook -i inventory/hosts.ini roles/deploy.yml --vault-password-file vault/.vault
```

### GitLab CI

```yaml
# .gitlab-ci.yml
deploy:
  script:
    - echo "$VAULT_PASSWORD" > vault/.vault
    - ansible-playbook -i inventory/hosts.ini roles/deploy.yml --vault-password-file vault/.vault
```

## Мониторинг и логирование

### Проверка статуса vault

```bash
# Проверка всех vault файлов
make vault check

# Проверка конкретного файла
ansible-vault view vault/secrets.yml --vault-password-file vault/.vault
```

### Логирование операций

```bash
# Включение подробного логирования
export ANSIBLE_VERBOSITY=4

# Запуск с логированием
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --vault-password-file vault/.vault -vvv
```

## Поддержка

- 📧 Email: через сайт https://devops.org.ru
- 📖 Документация: `docs/`
- 🧪 Тесты: `roles/*/tests/`