K3S/docs/troubleshooting.md

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

Таблица проблем

Проблема	Причина	Решение
Permission denied (publickey)	Ключ не скопирован	ssh-copy-id user@server
Vault decryption failed	Неверный пароль vault	Проверь VAULT_PASSWORD в .env
kube-vip VIP не пингуется	Неверный интерфейс	Проверь kube_vip_interface — должен совпадать с ip a на master01
RPi K3S не стартует	Не включены cgroups	`ssh pi@rpi "cat /proc/cgroups
PVC в Pending	NFS не монтируется	kubectl get events -A — проверь монтирование NFS на нодах
ingress EXTERNAL-IP <pending>	kube-vip не работает	`kubectl -n kube-system get pods
etcd нет кворума	Нода упала	Нужно минимум 2 из 3 нод. kubectl get nodes
worker01/rpi01 не присоединились	master01 не готов	Убедись что master01 полностью стартовал. serial: 1 гарантирует порядок
Kiali: "Could not get token"	Нет Secret	kubectl -n istio-system get secret kiali-admin-token
Grafana PVC Pending	NFS StorageClass не default	kubectl get sc — nfs-master01 должен быть (default)
Molecule: image pull failed	Нет интернета	docker pull geerlingguy/docker-ubuntu2204-ansible:latest вручную
Molecule: idempotency failed	Таск не идемпотентен	Добавь changed_when: false
ansible-lint ошибки	Синтаксис	make molecule-lint и исправь файлы
etcd restore: снимок не найден	Неверный путь	make etcd-list-snapshots — снимок должен быть на первом мастере
add-node: нода не присоединяется	kube-vip не работает	`kubectl -n kube-system get pods
remove-node: drain завис	PodDisruptionBudget	kubectl get pdb -A — проверь PDB
cert-manager: сертификат Pending	Нет публичного домена	При letsencrypt нужен публичный домен + ingress-nginx
Harbor: registry push fails	Неверный externalURL	harbor_ingress_host должен совпадать с реальным hostname
Jenkins: агент не стартует	RBAC	kubectl get events -n jenkins — проверь ServiceAccount
Vault: sealed после рестарта	Нет auto-unseal	Настрой vault_auto_unseal_type или используй k8s unsealer
NetBird: клиент не подключается	DNS не настроен	Настрой A-записи для Management, Signal, Coturn LB IPs
MinIO: distributed не поднимается	Мало нод	Distributed требует минимум 4 реплики/ноды
Nextcloud: redirect loop	HTTP→HTTPS конфликт	Добавь TRUSTED_PROXIES в конфиг Nextcloud

Подробный вывод

ANSIBLE_VERBOSITY=2 make install                # основной вывод
ANSIBLE_VERBOSITY=4 make install                # максимальный вывод
ANSIBLE_VERBOSITY=2 ANSIBLE_TAGS=k3s make install  # подробно для k3s

Диагностика нод

make shell   # открыть bash в ansible-контейнере

# Внутри контейнера:
ansible all -m ping
ansible all -m shell -a "systemctl status k3s"
ansible k3s_master -m shell -a "k3s kubectl get nodes"
ansible k3s_master -m shell -a "journalctl -u k3s -n 50 --no-pager"

Диагностика кластера

export KUBECONFIG=$(pwd)/kubeconfig

# Общий статус
kubectl get nodes -o wide
kubectl get pods -A | grep -v Running
kubectl get events -A --sort-by='.lastTimestamp' | tail -30

# Ресурсы
kubectl top nodes
kubectl top pods -A --sort-by=cpu

# Конкретный под
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --tail=100 -f
kubectl logs <pod> -n <namespace> --previous   # логи предыдущего контейнера

# PVC проблемы
kubectl describe pvc <pvc> -n <namespace>
kubectl get pv

# Ingress проблемы
kubectl describe ingress <name> -n <namespace>
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller -f

Проверка etcd

kubectl -n kube-system exec -it \
  $(kubectl -n kube-system get pods -l component=etcd -o name | head -1) \
  -- etcdctl --endpoints=https://127.0.0.1:2379 \
     --cacert=/var/lib/kubernetes/k3s/server/tls/etcd/server-ca.crt \
     --cert=/var/lib/kubernetes/k3s/server/tls/etcd/server-client.crt \
     --key=/var/lib/kubernetes/k3s/server/tls/etcd/server-client.key \
     member list

Диагностика NFS

# На NFS сервере:
make shell
ansible nfs_server -m shell -a "exportfs -v"
ansible nfs_server -m shell -a "showmount -e localhost"

# На нодах кластера:
ansible k3s_cluster -m shell -a "mount | grep nfs"
ansible k3s_cluster -m shell -a "showmount -e 192.168.1.10"

Диагностика kube-vip

# Статус подов
kubectl -n kube-system get pods -l app.kubernetes.io/name=kube-vip

# Логи
kubectl -n kube-system logs -l app.kubernetes.io/name=kube-vip

# Проверить VIP
ping 192.168.1.100   # kube_vip_address
curl -k https://192.168.1.100:6443/healthz

Диагностика cert-manager

kubectl get certificate -A
kubectl get certificaterequest -A
kubectl get challenges -A
kubectl describe certificate <name> -n <namespace>
kubectl logs -n cert-manager deployment/cert-manager -f

Типичные Molecule ошибки

Ошибка	Решение
Unable to pull image	docker pull geerlingguy/docker-ubuntu2204-ansible:latest
FAILED: assert ... is defined	Добавь переменную в converge.yml секцию vars:
Idempotency: CHANGED	Добавь changed_when: false к таску
yamllint: wrong indentation	Исправь отступы, запусти make molecule-lint
ansible-lint: no-changed-when	Добавь changed_when: <условие>
sysctl: Operation not permitted	Добавь privileged: true в molecule.yml