proxmox-loki-terraform/README.md

# Terraform конфигурация для развертывания Grafana Loki на Proxmox

Этот проект содержит полный набор Terraform файлов для автоматического развертывания виртуальной машины на Proxmox с установкой и настройкой Grafana Loki и Promtail для сбора и хранения логов.

## 📋 Описание проекта

Проект автоматизирует следующие задачи:
- Создание SSH ключей для безопасного доступа к VM
- Развертывание виртуальной машины на Proxmox с заданными параметрами
- Установка и настройка Grafana Loki (система хранения и агрегации логов)
- Установка и настройка Promtail (агент для сбора логов)
- Настройка автоматического сбора системных логов из `/var/log`

## 🎯 Параметры виртуальной машины

- **CPU**: 4 ядра
- **RAM**: 4 GB
- **Диск**: 31 GB
- **ОС**: Ubuntu 22.04 (из cloud-init template)
- **Сеть**: DHCP (динамическое получение IP)

## 📦 Установленные компоненты

### Grafana Loki
- Версия: 2.9.3
- Порт: 3100
- Режим: Standalone
- Хранилище: Filesystem
- Retention: 31 день

### Promtail
- Версия: 2.9.3
- Порт: 9080
- Собирает логи из:
  - `/var/log/*log` (все системные логи)
  - `/var/log/syslog`
  - `/var/log/auth.log`
  - `/var/log/kern.log`
  - Systemd journal
  - Apache, Nginx, Docker (если установлены)

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

### На локальной машине:
- [Terraform](https://www.terraform.io/downloads) >= 1.0
- Доступ к Proxmox API
- Proxmox API Token (Token ID и Secret)

### В Proxmox:
- Ubuntu 22.04 Cloud-Init template (можно создать из cloud image)
- Достаточно ресурсов (4 CPU, 4GB RAM, 31GB диск)
- Настроенная сеть с DHCP
- Хранилище (storage) для дисков VM

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

```
proxmox-loki-terraform/
├── main.tf                    # Основная конфигурация Terraform
├── variables.tf               # Переменные
├── outputs.tf                 # Выходные данные
├── install_loki.sh           # Скрипт установки Loki
├── install_promtail.sh       # Скрипт установки Promtail
├── loki-config.yaml          # Конфигурация Loki
├── promtail-config.yaml      # Конфигурация Promtail
├── README.md                 # Эта инструкция
├── terraform.tfvars          # Файл с вашими значениями переменных (создать)
└── ssh_key.pem              # SSH ключ (будет создан после apply)
```

## 🚀 Инструкция по использованию

### Шаг 1: Подготовка Proxmox

1. Создайте API Token в Proxmox:
   ```bash
   # В Proxmox Web UI:
   # Datacenter → Permissions → API Tokens → Add
   # Сохраните Token ID и Secret
   ```

2. Убедитесь, что у вас есть Ubuntu 22.04 Cloud-Init template:
   ```bash
   # Пример создания template в Proxmox (выполнить на Proxmox сервере):
   wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
   qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci
   qm importdisk 9000 jammy-server-cloudimg-amd64.img local-lvm
   qm set 9000 --scsi0 local-lvm:vm-9000-disk-0
   qm set 9000 --boot c --bootdisk scsi0
   qm set 9000 --ide2 local-lvm:cloudinit
   qm set 9000 --serial0 socket --vga serial0
   qm set 9000 --agent enabled=1
   qm template 9000
   qm set 9000 --name ubuntu-22.04-cloudimg
   ```

### Шаг 2: Настройка переменных

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

```hcl
# terraform.tfvars
proxmox_api_url      = "https://your-proxmox-server.com:8006/api2/json"
proxmox_token_id     = "user@pam!token_name"
proxmox_token_secret = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
target_node          = "pve"  # Имя вашего Proxmox узла
storage              = "local-lvm"  # Ваше хранилище
template_name        = "ubuntu-22.04-cloudimg"  # Имя вашего template
network_bridge       = "vmbr0"  # Ваш сетевой мост

# Опционально - можно изменить параметры VM:
vm_name              = "loki-vm"
vm_cores             = 4
vm_memory            = 4096
vm_disk_size         = "31G"
ssh_user             = "ubuntu"
```

### Шаг 3: Инициализация Terraform

```bash
cd /home/ubuntu/proxmox-loki-terraform
terraform init
```

### Шаг 4: Проверка плана развертывания

```bash
terraform plan
```

Проверьте, что все параметры корректны и соответствуют вашим требованиям.

### Шаг 5: Развертывание

```bash
terraform apply
```

Введите `yes` для подтверждения. Процесс займет 5-10 минут:
1. Создание SSH ключей
2. Создание VM в Proxmox
3. Ожидание запуска cloud-init
4. Установка Grafana Loki
5. Установка Promtail

### Шаг 6: Получение информации о VM

После успешного развертывания вы получите:

```bash
# Просмотр всех outputs:
terraform output

# IP адрес VM:
terraform output vm_ip_address

# SSH команда для подключения:
terraform output ssh_connection_command

# Сохранение SSH ключа:
terraform output -raw ssh_private_key > ssh_key.pem
chmod 600 ssh_key.pem

# URL Loki:
terraform output loki_url
```

## 🔐 Подключение к VM

```bash
# Сохраните SSH ключ
terraform output -raw ssh_private_key > ssh_key.pem
chmod 600 ssh_key.pem

# Подключитесь к VM
ssh -i ssh_key.pem ubuntu@<VM_IP>
```

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

### Проверка Loki:

```bash
# Статус сервиса
sudo systemctl status loki

# Проверка здоровья
curl http://localhost:3100/ready

# Просмотр логов
sudo journalctl -u loki -f

# Проверка метрик
curl http://localhost:3100/metrics
```

### Проверка Promtail:

```bash
# Статус сервиса
sudo systemctl status promtail

# Просмотр логов
sudo journalctl -u promtail -f

# Проверка метрик
curl http://localhost:9080/metrics
```

### Проверка сбора логов:

```bash
# Проверка, что логи поступают в Loki
curl -G -s "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query={job="varlogs"}' | jq

# Получить последние логи
curl -G -s "http://localhost:3100/loki/api/v1/query_range" \
  --data-urlencode 'query={job="syslog"}' \
  --data-urlencode 'limit=10' | jq
```

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

Для визуализации логов рекомендуется установить Grafana:

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

### Быстрая установка Grafana на той же VM:

```bash
# Подключитесь к VM
ssh -i ssh_key.pem ubuntu@<VM_IP>

# Установите Grafana
sudo apt-get install -y apt-transport-https software-properties-common wget
sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install grafana

# Запустите Grafana
sudo systemctl enable grafana-server
sudo systemctl start grafana-server

# Grafana будет доступна на http://<VM_IP>:3000
# Логин по умолчанию: admin/admin
```

## 🛠️ Управление инфраструктурой

### Изменение конфигурации:

```bash
# Внесите изменения в terraform.tfvars или конфигурационные файлы
# Примените изменения:
terraform apply
```

### Удаление VM:

```bash
# Удалит VM и все связанные ресурсы
terraform destroy
```

### Пересоздание VM:

```bash
# Пометить ресурс для пересоздания
terraform taint proxmox_vm_qemu.loki_vm
terraform apply
```

## 📝 Полезные команды LogQL

LogQL - язык запросов для Loki (похож на PromQL):

```bash
# Все логи с job="syslog"
{job="syslog"}

# Логи с фильтром по содержимому
{job="syslog"} |= "error"

# Логи с регулярным выражением
{job="auth"} |~ "Failed password.*"

# Количество ошибок за последний час
count_over_time({job="syslog"} |= "error" [1h])

# Логи из нескольких источников
{job=~"syslog|auth"}
```

## 🔧 Настройка и кастомизация

### Изменение retention period:

Отредактируйте `loki-config.yaml`:
```yaml
limits_config:
  retention_period: 744h  # Измените на нужное значение
```

### Добавление новых источников логов:

Отредактируйте `promtail-config.yaml`, добавьте новый `job_name`:
```yaml
scrape_configs:
  - job_name: my-app
    static_configs:
      - targets:
          - localhost
        labels:
          job: my-app
          __path__: /var/log/my-app/*.log
```

### Изменение ресурсов VM:

В `terraform.tfvars`:
```hcl
vm_cores     = 8      # Увеличить CPU
vm_memory    = 8192   # Увеличить RAM
vm_disk_size = "50G"  # Увеличить диск
```

## 🐛 Решение проблем

### VM не получает IP адрес:
```bash
# Проверьте настройки DHCP в сети Proxmox
# Проверьте, что cloud-init работает на VM
```

### Не удается подключиться по SSH:
```bash
# Проверьте, что VM запущена в Proxmox
# Проверьте firewall правила
# Убедитесь, что SSH ключ сохранен с правильными правами (chmod 600)
```

### Loki не запускается:
```bash
# Проверьте логи
sudo journalctl -u loki -n 100

# Проверьте конфигурацию
sudo /usr/local/bin/loki -config.file=/etc/loki/loki-config.yaml -verify-config
```

### Promtail не отправляет логи:
```bash
# Проверьте логи
sudo journalctl -u promtail -n 100

# Проверьте, что Promtail может читать логи
sudo -u promtail ls -la /var/log/

# Проверьте positions файл
sudo cat /var/lib/promtail/positions.yaml
```

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

- [Официальная документация Loki](https://grafana.com/docs/loki/latest/)
- [Официальная документация Promtail](https://grafana.com/docs/loki/latest/clients/promtail/)
- [LogQL синтаксис](https://grafana.com/docs/loki/latest/logql/)
- [Terraform Proxmox Provider](https://registry.terraform.io/providers/Telmate/proxmox/latest/docs)
- [Grafana Labs](https://grafana.com/)

## 📄 Лицензия

Этот проект предоставляется "как есть" для личного и коммерческого использования.

## 🤝 Поддержка

Если у вас возникли проблемы или вопросы:
1. Проверьте раздел "Решение проблем"
2. Изучите логи сервисов
3. Обратитесь к официальной документации

---

**Примечание**: Не забудьте защитить ваш `terraform.tfvars` файл и не публикуйте его в публичных репозиториях, так как он содержит конфиденциальные данные (API токены).