terraform-grafana-loki/README.md

# Terraform: Grafana Loki на Proxmox

Этот проект Terraform автоматизирует развертывание виртуальной машины на Proxmox с установленными и настроенными **Grafana Loki** и **Promtail**.

## 📋 Описание

Проект создает полностью настроенную VM с:
- **Loki** - система агрегации логов (порт 3100)
- **Promtail** - агент для сбора логов (порт 9080)
- Автоматическая установка и настройка systemd сервисов
- Сбор системных логов из `/var/log/*.log`

## 🔧 Требования

### Локальные требования
- [Terraform](https://www.terraform.io/downloads.html) >= 1.0
- SSH ключ для доступа к VM (`~/.ssh/id_rsa` по умолчанию)
- Доступ к Proxmox API

### Требования к Proxmox
- Proxmox VE 6.x или 7.x
- API токен с правами для создания VM
- Ubuntu 20.04 шаблон с поддержкой cloud-init и DHCP
- Настроенное хранилище (по умолчанию `local-lvm`)
- Сетевой мост (по умолчанию `vmbr0`)

## 🚀 Быстрый старт

### 1. Клонируйте репозиторий

```bash
git clone https://git.mscsrv.ru/your-username/terraform-grafana-loki.git
cd terraform-grafana-loki
```

### 2. Настройте переменные

Создайте файл `terraform.tfvars` на основе примера:

```bash
cp terraform.tfvars.example terraform.tfvars
```

Отредактируйте `terraform.tfvars` и заполните необходимые значения:

```hcl
proxmox_api_url          = "https://your-proxmox-host:8006/api2/json"
proxmox_api_token_id     = "terraform-user@pve!token-id"
proxmox_api_token_secret = "your-secret-token"
target_node              = "pve"
vm_template              = "ubuntu-20.04-template"
```

### 3. Инициализируйте Terraform

```bash
terraform init
```

### 4. Проверьте план развертывания

```bash
terraform plan
```

### 5. Примените конфигурацию

```bash
terraform apply
```

Подтвердите создание ресурсов, введя `yes`.

### 6. Получите информацию о созданной VM

После успешного развертывания Terraform выведет:
- IP адрес VM
- URL для доступа к Loki
- URL для доступа к Promtail
- Команду для SSH подключения

```bash
terraform output
```

## 📁 Структура проекта

```
terraform-grafana-loki/
├── providers.tf              # Конфигурация провайдеров Terraform
├── variables.tf              # Определение переменных
├── main.tf                   # Основной код: ресурс VM и provisioners
├── outputs.tf                # Выходные данные (IP, URLs)
├── terraform.tfvars.example  # Пример файла с переменными
├── .gitignore                # Исключения для Git
└── README.md                 # Документация проекта
```

## ⚙️ Переменные

### Обязательные переменные

| Переменная | Описание |
|-----------|----------|
| `proxmox_api_url` | URL адрес Proxmox API |
| `proxmox_api_token_id` | ID токена для API |
| `proxmox_api_token_secret` | Секретный токен |

### Опциональные переменные

| Переменная | Значение по умолчанию | Описание |
|-----------|----------------------|----------|
| `target_node` | `pve` | Имя узла Proxmox |
| `vm_name` | `grafana-loki` | Имя VM |
| `vm_template` | `ubuntu-20.04-template` | Шаблон для клонирования |
| `vm_cores` | `2` | Количество CPU ядер |
| `vm_memory` | `4096` | Память в MB |
| `vm_disk_size` | `40G` | Размер диска |
| `loki_version` | `2.9.1` | Версия Loki |
| `loki_port` | `3100` | HTTP порт Loki |
| `promtail_port` | `9080` | HTTP порт Promtail |

## 🔐 Настройка Proxmox API токена

1. Войдите в веб-интерфейс Proxmox
2. Перейдите в **Datacenter** → **Permissions** → **API Tokens**
3. Создайте новый токен для пользователя (например, `terraform-user@pve`)
4. Сохраните Token ID и Secret
5. Убедитесь, что у пользователя есть необходимые права (PVEVMAdmin или Administrator)

## 🖥️ Подготовка Ubuntu шаблона

Шаблон VM должен соответствовать следующим требованиям:

1. Ubuntu 20.04 LTS (или новее)
2. Установлен и настроен cloud-init
3. Настроено получение IP через DHCP
4. Включен qemu-guest-agent
5. Добавлен ваш публичный SSH ключ

## 📊 Проверка работы сервисов

После развертывания подключитесь к VM:

```bash
ssh ubuntu@<VM_IP>
```

Проверьте статус сервисов:

```bash
# Статус Loki
sudo systemctl status loki

# Статус Promtail
sudo systemctl status promtail

# Логи Loki
sudo journalctl -u loki -f

# Логи Promtail
sudo journalctl -u promtail -f
```

Проверьте доступность Loki API:

```bash
curl http://localhost:3100/ready
curl http://localhost:3100/metrics
```

## 🔍 Интеграция с Grafana

Для визуализации логов в Grafana:

1. Установите Grafana (отдельно или на той же VM)
2. Добавьте Loki как Data Source:
   - URL: `http://<VM_IP>:3100`
   - Access: Server (по умолчанию)
3. Создайте дашборды для визуализации логов

## 🗑️ Удаление ресурсов

Для удаления созданной VM:

```bash
terraform destroy
```

## 📝 Примечания

- VM создается с использованием DHCP, IP адрес назначается автоматически
- Loki хранит данные локально в `/var/loki/`
- Promtail собирает логи из `/var/log/*.log`
- Оба сервиса настроены на автоматический запуск при старте системы

## 🐛 Устранение неполадок

### Ошибка подключения SSH

Убедитесь, что:
- SSH ключ правильно настроен в шаблоне VM
- Путь к приватному ключу корректен (`ssh_private_key_path`)
- VM получила IP адрес (проверьте в Proxmox)

### Loki не запускается

Проверьте логи:
```bash
sudo journalctl -u loki -n 100
```

Проверьте конфигурацию:
```bash
cat /etc/loki-config.yaml
```

### Promtail не отправляет логи

Проверьте подключение к Loki:
```bash
curl http://localhost:3100/ready
```

Проверьте конфигурацию Promtail:
```bash
cat /etc/promtail-config.yaml
```

## 📚 Дополнительные ресурсы

- [Документация Grafana Loki](https://grafana.com/docs/loki/latest/)
- [Документация Promtail](https://grafana.com/docs/loki/latest/clients/promtail/)
- [Terraform Proxmox Provider](https://registry.terraform.io/providers/Telmate/proxmox/latest/docs)

## 📄 Лицензия

Этот проект распространяется свободно для использования и модификации.

## 🤝 Вклад

Предложения и улучшения приветствуются! Создавайте Issue или Pull Request.