635 lines
23 KiB
Markdown
635 lines
23 KiB
Markdown
---
|
||
title: "Блог на Hugo в K3s: часть 5 - что делать когда всё внезапно сломалось"
|
||
date: 2026-02-17
|
||
draft: false
|
||
description: "Алгоритм диагностики Hugo блога в K3s за 5 минут: от DNS до пода. Сайт отдаёт 503 — находим причину без паники."
|
||
tags: ["kubernetes", "k3s", "traefik", "debugging", "nginx", "troubleshooting"]
|
||
categories: ["Kubernetes", "DevOps практики"]
|
||
series: ["Блог на Hugo в K3s"]
|
||
series_order: 5
|
||
---
|
||
|
||
В части 4 мы разобрались с Git workflow. Всё работает: пушишь в `dev` - видишь на тестовом окружении, мержишь в `main` - публикуется на production.
|
||
|
||
А потом в один прекрасный день открываешь свой сайт и видишь `503 Service Temporarily Unavailable`.
|
||
|
||
Вчера же все работало! Ты ничего не менял. Что произошло?
|
||
|
||
Добро пожаловать в мир эксплуатации Kubernetes, где проблемы тоже возникают и требуют системного подхода без паники.
|
||
|
||
Эта статья - алгоритм диагностики от DNS до пода. Проходишь по шагам сверху вниз, находишь проблему за 5 минут. Не гадаешь, не тыкаешь наугад - работаешь по системе.
|
||
|
||
---
|
||
|
||
## Анатомия HTTP запроса в K3s
|
||
|
||
Прежде чем искать проблему, нужно понять путь запроса от браузера до nginx:
|
||
|
||
```
|
||
Браузер
|
||
↓ DNS запрос
|
||
DNS сервер (провайдер или Cloudflare)
|
||
↓ Возвращает IP адрес
|
||
Роутер/Файрвол (OPNsense, MikroTik)
|
||
↓ Port Forward 443 → K3s node
|
||
MetalLB LoadBalancer
|
||
↓ External IP
|
||
Traefik Ingress Controller
|
||
↓ IngressRoute matching
|
||
Kubernetes Service
|
||
↓ Endpoint selection
|
||
Pod (Nginx контейнер)
|
||
↓ Volume mount
|
||
NFS хранилище
|
||
```
|
||
|
||
Проблема может быть на любом из этих уровней. Секрет эффективной диагностики - проверять снаружи внутрь, последовательно исключая рабочие компоненты.
|
||
|
||
Когда тыкаешь наугад, проверяя сначала поды, потом DNS, потом снова поды - тратишь время. Когда идёшь по алгоритму - находишь проблему за минуты.
|
||
|
||
---
|
||
|
||
## Шаг 1: DNS - доходит ли домен до твоего IP
|
||
|
||
Первым делом проверяем что домен резолвится в правильный IP. Без этого дальше проверять бессмысленно - браузер просто не знает куда направлять запрос.
|
||
|
||
### Проверка
|
||
|
||
```bash
|
||
# Проверяем DNS резолв (используй свой домен)
|
||
dig blog.example.com +short
|
||
|
||
# Альтернатива если dig не установлен
|
||
nslookup blog.example.com
|
||
```
|
||
|
||
### Ожидаемый результат
|
||
|
||
```
|
||
77.37.XXX.XXX
|
||
```
|
||
|
||
Должен вернуться твой **публичный IP адрес** (тот который прописан в A-записи у DNS провайдера).
|
||
|
||
### Что может пойти не так
|
||
|
||
| Симптом | Причина | Как проверить | Решение |
|
||
|---------|---------|---------------|---------|
|
||
| Возвращается старый IP | DNS кеш не обновился | `dig blog.example.com @8.8.8.8` | Подожди TTL (обычно 300-3600 сек) |
|
||
| `NXDOMAIN` ошибка | Домен не делегирован | Проверь NS записи у регистратора | Настрой DNS правильно |
|
||
| Возвращается `127.0.0.1` | Локальный override | `cat /etc/hosts \| grep blog` | Удали строку из /etc/hosts |
|
||
| Возвращается несколько IP | Round-robin DNS | Проверь все ли IP твои | Удали лишние A-записи |
|
||
|
||
Если DNS правильный - идём дальше.
|
||
|
||
---
|
||
|
||
## Шаг 2: Внешний доступ - доходит ли запрос до сервера
|
||
|
||
Теперь проверяем что запрос физически доходит до сервера. DNS может быть правильным, но файрвол может блокировать трафик.
|
||
|
||
### Проверка
|
||
|
||
```bash
|
||
# Пробуем подключиться извне (важно - НЕ из локальной сети!)
|
||
curl -v https://blog.example.com 2>&1 | head -30
|
||
```
|
||
|
||
**Важно:** Запускай эту команду с **внешнего** сервера или используй мобильный интернет. Тест из локальной сети ничего не докажет - можешь обходить файрвол.
|
||
|
||
### Ситуация А: Connection refused или timeout
|
||
|
||
```
|
||
curl: (7) Failed to connect to blog.example.com port 443: Connection refused
|
||
```
|
||
|
||
Запрос вообще не дошёл до сервера. Проблема на сетевом уровне.
|
||
|
||
**Возможные причины:**
|
||
|
||
**1. Порт 443 закрыт на файрволе/роутере**
|
||
|
||
Проверь Port Forward правила на OPNsense/MikroTik. Должно быть:
|
||
```
|
||
WAN:443 → 192.168.X.X:443 (IP любой K3s ноды)
|
||
```
|
||
|
||
**2. MetalLB не назначил External IP для Traefik**
|
||
|
||
```bash
|
||
# Проверяем MetalLB
|
||
kubectl get svc -n traefik traefik
|
||
|
||
# Ожидаемый результат
|
||
NAME TYPE EXTERNAL-IP PORT(S)
|
||
traefik LoadBalancer 192.168.X.X 80:30080/TCP,443:30443/TCP
|
||
```
|
||
|
||
Если `EXTERNAL-IP` показывает `<pending>` - MetalLB не работает или пул IP адресов не настроен.
|
||
|
||
**3. Traefik под не запущен**
|
||
|
||
```bash
|
||
# Проверяем что Traefik работает
|
||
kubectl get pods -n traefik
|
||
|
||
# Должны быть все Running
|
||
NAME READY STATUS
|
||
traefik-xxxxxxxxxx-xxxxx 1/1 Running
|
||
```
|
||
|
||
### Ситуация Б: TLS handshake прошёл, но 503
|
||
|
||
```
|
||
< HTTP/2 503
|
||
< content-type: text/plain; charset=utf-8
|
||
< content-length: 20
|
||
no available server
|
||
```
|
||
|
||
Отлично - наша ситуация! Traefik работает, SSL сертификат отдаёт, но дальше запрос упирается в стену.
|
||
|
||
Сообщение `no available server` означает что Traefik **нашёл роутер**, но **не нашёл живой бэкенд** за ним.
|
||
|
||
Проблема внутри кластера. Идём глубже.
|
||
|
||
### Ситуация В: SSL certificate problem
|
||
|
||
```
|
||
curl: (60) SSL certificate problem: unable to get local issuer certificate
|
||
```
|
||
|
||
Сертификат невалидный или не выпущен.
|
||
|
||
```bash
|
||
# Проверяем Certificate объект (используй свой namespace)
|
||
kubectl get certificate -n blog
|
||
|
||
# Должно быть READY=True
|
||
NAME READY SECRET AGE
|
||
blog-tls True blog-tls 2d
|
||
```
|
||
|
||
Если `READY=False` - cert-manager не смог выпустить сертификат.
|
||
|
||
```bash
|
||
# Смотрим что пошло не так
|
||
kubectl describe certificate blog-tls -n blog
|
||
|
||
# Ищем секцию Events внизу вывода - там описание проблемы
|
||
```
|
||
|
||
### Главное: Запрос доходит до Traefik
|
||
|
||
```bash
|
||
# Проверка (с ВНЕШНЕГО сервера!)
|
||
curl -I https://blog.example.com
|
||
|
||
# Ожидаемый результат (любой из двух)
|
||
HTTP/2 200 # Всё работает
|
||
HTTP/2 503 # Traefik работает, но бэкенд недоступен
|
||
|
||
# Если connection refused/timeout - проблема в сети (см. выше)
|
||
```
|
||
|
||
---
|
||
|
||
## Шаг 3: Traefik - правильно ли маршрутизируется трафик
|
||
|
||
Traefik получил запрос на твой домен. Что он с ним делает? Смотрим логи.
|
||
|
||
### Проверка логов Traefik
|
||
|
||
```bash
|
||
# Смотрим последние 50 строк логов Traefik
|
||
kubectl logs -n traefik deployment/traefik --tail=50
|
||
|
||
# Фильтруем только свой домен (убираем шум от других сервисов)
|
||
kubectl logs -n traefik deployment/traefik --tail=100 | grep blog.example
|
||
```
|
||
|
||
### Что искать в логах
|
||
|
||
**Нормальный запрос:**
|
||
|
||
```json
|
||
{
|
||
"request": "GET / HTTP/2.0",
|
||
"status": 200,
|
||
"size": 8994,
|
||
"router": "blog-blog-https-xxxxx@kubernetescrd",
|
||
"service": "blog-nginx-blog@kubernetescrd",
|
||
"backend": "http://10.42.2.40:80",
|
||
"duration": 12
|
||
}
|
||
```
|
||
|
||
Ключевые поля:
|
||
- **router:** Traefik нашёл нужный IngressRoute (`blog-blog-https`)
|
||
- **backend:** IP пода nginx куда проксируется запрос (`10.42.2.40:80`)
|
||
- **status:** HTTP код ответа от nginx (`200` = всё хорошо)
|
||
|
||
**Проблемный запрос:**
|
||
|
||
```json
|
||
{
|
||
"request": "GET / HTTP/2.0",
|
||
"status": 503,
|
||
"router": "blog-blog-https-xxxxx@kubernetescrd",
|
||
"error": "no available server"
|
||
}
|
||
```
|
||
|
||
Traefik нашёл роутер, но поле `backend` отсутствует - под недоступен или не существует.
|
||
|
||
### Проверяем список IngressRoute
|
||
|
||
```bash
|
||
# Смотрим все IngressRoute в кластере
|
||
kubectl get ingressroute -A
|
||
|
||
# Фильтруем только свой домен
|
||
kubectl get ingressroute -A | grep blog.example
|
||
```
|
||
|
||
**Важный момент:** Если один и тот же домен прописан в **двух разных IngressRoute** из разных namespace - Traefik будет балансировать между ними.
|
||
|
||
Например:
|
||
|
||
```bash
|
||
NAMESPACE NAME AGE
|
||
blog blog-https 10d # СТАРЫЙ namespace
|
||
blog-new blog-https 2d # НОВЫЙ namespace
|
||
```
|
||
|
||
Оба IngressRoute имеют `match: Host('blog.example.com')`. Traefik видит оба, честно балансирует трафик 50/50.
|
||
|
||
Если один из бэкендов мёртв - половина запросов уходит в пустоту. 503 через раз.
|
||
|
||
**Решение:** Удалить старый IngressRoute:
|
||
|
||
```bash
|
||
# Удаляем дубль из старого namespace
|
||
kubectl delete ingressroute blog-https blog-http -n blog
|
||
```
|
||
|
||
### Проверяем синтаксис match
|
||
|
||
Traefik очень требователен к синтаксису. Частая ошибка - забыть backticks или скобки.
|
||
|
||
**Неправильно:**
|
||
```yaml
|
||
match: Host(blog.example.com) # Нет backticks
|
||
match: Host `blog.example.com` # Нет скобок вокруг Host
|
||
match: Host("blog.example.com") # Двойные кавычки вместо backticks
|
||
```
|
||
|
||
**Правильно:**
|
||
```yaml
|
||
match: Host(`blog.example.com`)
|
||
```
|
||
|
||
Проверяем:
|
||
|
||
```bash
|
||
# Смотрим манифест IngressRoute
|
||
kubectl get ingressroute blog-https -n blog -o yaml | grep match:
|
||
|
||
# Должно быть со скобками и backticks
|
||
match: Host(`blog.example.com`)
|
||
```
|
||
|
||
### Главное: Traefik нашёл роутер
|
||
|
||
```bash
|
||
# Проверка
|
||
kubectl logs -n traefik deployment/traefik --tail=50 | grep blog.example
|
||
|
||
# Ожидаемый результат - есть строки с "router": "blog-blog-https"
|
||
# Если router не найден - проблема в IngressRoute match синтаксисе
|
||
```
|
||
|
||
---
|
||
|
||
## Шаг 4: Service - видит ли он поды
|
||
|
||
Traefik нашёл роутер, проксирует трафик на Service. Но Service может не видеть поды если selector неправильный.
|
||
|
||
### Проверка endpoints
|
||
|
||
```bash
|
||
# Смотрим endpoints для Service (используй своё имя Service)
|
||
kubectl get endpoints nginx -n blog
|
||
|
||
# Ожидаемый результат - НЕ пустой список IP
|
||
NAME ENDPOINTS
|
||
nginx 10.42.0.44:80,10.42.2.40:80
|
||
```
|
||
|
||
Если видишь `<none>` - Service не нашёл ни одного пода. Две возможные причины.
|
||
|
||
### Причина 1: Selector не совпадает с labels
|
||
|
||
```bash
|
||
# Смотрим selector у Service
|
||
kubectl get svc nginx -n blog -o yaml | grep -A3 "selector:"
|
||
|
||
# Вывод
|
||
selector:
|
||
app: nginx
|
||
|
||
# Смотрим labels у подов
|
||
kubectl get pods -n blog --show-labels | grep nginx
|
||
|
||
# Вывод
|
||
nginx-xxxxxxxxxx-xxxxx 1/1 Running app=nginx-old
|
||
```
|
||
|
||
Видишь проблему? Service ищет `app: nginx`, а под помечен `app: nginx-old`. Не совпадает.
|
||
|
||
**Решение:** Исправить Deployment или Service чтобы labels совпадали.
|
||
|
||
### Причина 2: Поды не Running
|
||
|
||
```bash
|
||
# Смотрим статус подов
|
||
kubectl get pods -n blog
|
||
|
||
# Видим
|
||
NAME READY STATUS
|
||
nginx-xxxxxxxxxx-xxxxx 0/1 CreateContainerError
|
||
```
|
||
|
||
Под существует, но не работает. Service правильно не включает его в endpoints. Идём в следующий шаг - разбираемся почему под не запускается.
|
||
|
||
### Главное: Service видит поды
|
||
|
||
```bash
|
||
# Проверка
|
||
kubectl get endpoints nginx -n blog
|
||
|
||
# Ожидаемый результат - НЕ пустой
|
||
nginx 10.42.0.44:80,10.42.2.40:80
|
||
|
||
# Если <none> - проблема в селекторах или поды не Running
|
||
```
|
||
|
||
---
|
||
|
||
## Шаг 5: Pod - что происходит внутри контейнера
|
||
|
||
Самый глубокий уровень. Под не запускается или падает в цикле перезапусков.
|
||
|
||
### Проверка статуса подов
|
||
|
||
```bash
|
||
# Смотрим все поды в namespace
|
||
kubectl get pods -n blog
|
||
|
||
# Фильтруем только nginx
|
||
kubectl get pods -n blog | grep nginx
|
||
```
|
||
|
||
**Возможные статусы проблем:**
|
||
|
||
### CreateContainerError
|
||
|
||
Контейнер вообще не может стартануть. Обычно проблема с volumes или образом.
|
||
|
||
```bash
|
||
# Смотрим детали пода (используй своё имя пода)
|
||
kubectl describe pod nginx-xxxxxxxxxx-xxxxx -n blog | tail -30
|
||
```
|
||
|
||
Ищем секцию `Events` внизу вывода. Там будет описание проблемы:
|
||
|
||
**Пример 1: PVC не примонтировался**
|
||
|
||
```
|
||
Events:
|
||
Warning FailedMount MountVolume.SetUp failed for volume "blog-public-pvc":
|
||
mount failed: mount.nfs: Connection timed out
|
||
```
|
||
|
||
NFS хранилище недоступно. Возможные причины:
|
||
- NFS сервер выключен или перезагружается
|
||
- Неправильный IP или путь в PersistentVolume
|
||
- Файрвол блокирует NFS трафик (порт 2049)
|
||
|
||
**Пример 2: Образ не скачался**
|
||
|
||
```
|
||
Events:
|
||
Warning Failed Failed to pull image "nginx:latest": rpc error: code = Unknown
|
||
```
|
||
|
||
Контейнер не может скачать образ. Обычно это означает что `imagePullPolicy: Never`, а образ не импортирован на ноду.
|
||
|
||
```bash
|
||
# Проверяем что образ есть на ноде (используй IP своей worker ноды)
|
||
ssh user@192.168.X.X "sudo k3s crictl images | grep nginx"
|
||
```
|
||
|
||
Если образа нет - импортируй его через `k3s ctr images import`.
|
||
|
||
**Пример 3: ConfigMap не найден**
|
||
|
||
```
|
||
Events:
|
||
Warning FailedMount ConfigMap "nginx-config" not found
|
||
```
|
||
|
||
Deployment ссылается на несуществующий ConfigMap.
|
||
|
||
```bash
|
||
# Проверяем что ConfigMap существует
|
||
kubectl get configmap -n blog | grep nginx-config
|
||
```
|
||
|
||
Если нет - создай или исправь имя в Deployment.
|
||
|
||
### CrashLoopBackOff
|
||
|
||
Контейнер запускается, но сразу падает. Смотрим логи **предыдущего** запуска:
|
||
|
||
```bash
|
||
# Логи последнего упавшего контейнера
|
||
kubectl logs nginx-xxxxxxxxxx-xxxxx -n blog --previous
|
||
```
|
||
|
||
**Пример: Nginx падает из-за неправильного конфига**
|
||
|
||
```
|
||
nginx: [emerg] unexpected "}" in /etc/nginx/nginx.conf:15
|
||
nginx: configuration file /etc/nginx/nginx.conf test failed
|
||
```
|
||
|
||
Синтаксическая ошибка в `nginx.conf`. Проверяем ConfigMap:
|
||
|
||
```bash
|
||
# Смотрим содержимое конфига
|
||
kubectl get configmap nginx-config -n blog -o yaml
|
||
```
|
||
|
||
Находим ошибку, исправляем, применяем. Под перезапустится автоматически.
|
||
|
||
### Главное: Под работает
|
||
|
||
```bash
|
||
# Проверка
|
||
kubectl get pods -n blog | grep nginx
|
||
|
||
# Ожидаемый результат - все Running
|
||
nginx-xxxxxxxxxx-xxxxx 1/1 Running 0 2d
|
||
|
||
# Если не Running - смотри troubleshooting выше
|
||
```
|
||
|
||
---
|
||
|
||
## Шаг 6: Контент - есть ли файлы для отдачи
|
||
|
||
Под работает, Service видит его, Traefik проксирует трафик. Но сайт отдаёт `404 Not Found` или пустую страницу.
|
||
|
||
Проблема: Hugo Builder не записал файлы на NFS или записал не туда.
|
||
|
||
### Проверка
|
||
|
||
```bash
|
||
# Заходим в под nginx (используй своё имя пода)
|
||
kubectl exec -it nginx-xxxxxxxxxx-xxxxx -n blog -- sh
|
||
|
||
# Внутри пода смотрим что примонтировалось
|
||
ls -la /usr/share/nginx/html/
|
||
|
||
# Должен быть index.html и папки posts, tags, etc
|
||
```
|
||
|
||
**Если директория пустая** - Hugo Builder не сработал. Проверяем его логи:
|
||
|
||
```bash
|
||
# Логи Hugo Builder
|
||
kubectl logs -n blog deployment/hugo-builder-prod --tail=50
|
||
```
|
||
|
||
Ищем строку `Build successful!` и список созданных файлов. Если её нет:
|
||
|
||
1. **Webhook не сработал** - проверь настройки webhook в Gitea
|
||
2. **Hugo упал с ошибкой** - читай логи выше, смотри на что ругается
|
||
3. **Собрал в другую директорию** - проверь переменную `OUTPUT_DIR` в build.sh
|
||
|
||
### Главное: Контент на месте
|
||
|
||
```bash
|
||
# Проверка (используй своё имя пода)
|
||
kubectl exec -it nginx-xxxxxxxxxx-xxxxx -n blog -- ls /usr/share/nginx/html/ | head -5
|
||
|
||
# Ожидаемый результат
|
||
index.html
|
||
posts/
|
||
tags/
|
||
categories/
|
||
|
||
# Если пусто - Hugo Builder не отработал (см. выше)
|
||
```
|
||
|
||
---
|
||
|
||
## Быстрый чеклист для любой проблемы
|
||
|
||
Сохрани эту последовательность - она работает для 95% проблем:
|
||
|
||
```
|
||
[ ] DNS: dig домен → правильный IP?
|
||
[ ] Сеть: curl -v https://домен → доходит до Traefik?
|
||
[ ] MetalLB: kubectl get svc -n traefik → External IP назначен?
|
||
[ ] Traefik: kubectl get pods -n traefik → Running?
|
||
[ ] IngressRoute: kubectl get ingressroute -A | grep домен → нет дублей?
|
||
[ ] Match синтаксис: Host(`домен`) со скобками и backticks?
|
||
[ ] Endpoints: kubectl get endpoints -n namespace → не пустые?
|
||
[ ] Selector: labels подов совпадают с selector Service?
|
||
[ ] Pods: kubectl get pods -n namespace → все Running?
|
||
[ ] PVC: kubectl get pvc -n namespace → все Bound?
|
||
[ ] Контент: kubectl exec ls /usr/share/nginx/html → файлы есть?
|
||
```
|
||
|
||
Проходишь по списку сверху вниз. Останавливаешься на первом `[ ]` где что-то не так. Чинишь. Проверяешь снова.
|
||
|
||
Не прыгай хаотично между уровнями. Алгоритм экономит время.
|
||
|
||
---
|
||
|
||
## Реальный пример: 503 через раз
|
||
|
||
Мой сайт отдавал `503` примерно в 50% запросов. Половина запросов работала, половина нет.
|
||
|
||
Прошёл по алгоритму:
|
||
|
||
1. ✅ DNS - правильный IP
|
||
2. ✅ Сеть - Traefik отвечает
|
||
3. ✅ MetalLB - External IP назначен
|
||
4. ✅ Traefik - поды Running
|
||
5. ❌ IngressRoute - **два роутера на один домен**
|
||
|
||
```bash
|
||
kubectl get ingressroute -A | grep oakazanin
|
||
|
||
NAMESPACE NAME
|
||
blog blog-https # СТАРЫЙ, бэкенд в CreateContainerError
|
||
oakazanin blog-https # НОВЫЙ, работает
|
||
```
|
||
|
||
Traefik видел два роутера, честно балансировал трафик 50/50. Каждый второй запрос улетал в мёртвый `blog/nginx`.
|
||
|
||
Диагноз поставлен за 3 минуты. Лечение - одна команда:
|
||
|
||
```bash
|
||
# Удаляем дубль из старого namespace
|
||
kubectl delete ingressroute blog-https blog-http -n blog
|
||
```
|
||
|
||
Мораль: **всегда чисти за собой**. Старые namespace с нерабочими сервисами - источник неочевидных проблем.
|
||
|
||
---
|
||
|
||
## Откат и cleanup
|
||
|
||
Если в процессе диагностики что-то сломал ещё больше - откатываемся:
|
||
|
||
```bash
|
||
# Восстанавливаем предыдущую версию манифеста
|
||
kubectl apply -f nginx-deployment.yaml
|
||
|
||
# Перезапускаем поды принудительно
|
||
kubectl rollout restart deployment/nginx -n blog
|
||
|
||
# Смотрим что изменения применились
|
||
kubectl rollout status deployment/nginx -n blog
|
||
```
|
||
|
||
**Золотое правило:** Перед экспериментами делай бэкапы манифестов:
|
||
|
||
```bash
|
||
# Экспортируем текущее состояние с датой
|
||
kubectl get deployment,service,ingressroute -n blog -o yaml > backup-$(date +%Y%m%d).yaml
|
||
```
|
||
|
||
---
|
||
|
||
## Что дальше
|
||
|
||
Ты умеешь диагностировать проблемы. Но лучше их вообще не создавать.
|
||
|
||
В следующей части покажу как правильно мигрировать сервисы между namespace - без даунтайма, дублей IngressRoute и других сюрпризов которые приводят к 503.
|
||
|
||
Разберём реальный пример: переносим Gitea между namespace с NFS данными, получаем новый SSL за 32 секунды, и удаляем старый namespace навсегда.
|
||
|
||
---
|
||
|
||
**Стек этой части:**
|
||
- Traefik 2.11 IngressRoute
|
||
- Kubernetes 1.30 (K3s)
|
||
- kubectl CLI
|
||
- curl для внешних проверок
|
||
- dig для DNS диагностики
|