Доработка документации

stack/kubernetes/USAGE.md

@@ -0,0 +1,133 @@
+# USAGE: как пользоваться стендом (запуск / остановка / проверка)
+
+Операционная шпаргалка, а не учебный материал — сюда смотришь, когда нужно просто поднять/погасить стенд между сессиями курса, без объяснений «зачем». Учебный курс — [LEARNING.md](LEARNING.md), окружение и характеристики сервера — [SERVER.md](SERVER.md), на чём остановился по модулям — [PROGRESS.md](PROGRESS.md), разбор каждой команды — [COMMANDS.md](COMMANDS.md).
+
+## 1. Подключение
+
+```bash
+ssh totserver@192.168.31.163
+```
+
+Ключ уже настроен, пароль не спросит. Дальше два варианта:
+
+- **Обычная интерактивная SSH-сессия** (просто зашёл и работаешь в терминале) — это login shell, `kind`/`helm`/`kubectl`/`docker` уже все видны в `PATH` без танцев.
+- **Одна неинтерактивная команда с хоста** (`ssh totserver@192.168.31.163 'команда'`) — это **non-login shell**, `~/.local/bin` (где лежат `kind` и `helm`) в `PATH` не попадает. Либо вызывать по полному пути (`~/.local/bin/kind ...`), либо оборачивать в `bash -lc "..."`:
+
+```bash
+ssh totserver@192.168.31.163 'bash -lc "kubectl get nodes"'
+```
+
+`kubectl` (snap) и `docker` видны в обоих случаях без исключений.
+
+## 2. Быстрая проверка состояния
+
+Одним блоком — что вообще сейчас поднято:
+
+```bash
+bash -lc '
+echo "--- kind-контейнеры ---"
+docker ps -a --filter "name=^lab-" --format "{{.Names}}\t{{.Status}}"
+echo "--- kubectl context ---"
+kubectl config current-context 2>&1
+echo "--- ноды ---"
+kubectl get nodes -o wide 2>&1
+echo "--- поды по всем namespace ---"
+kubectl get pods -A 2>&1
+echo "--- helm-релизы ---"
+helm list -A 2>&1
+echo "--- CI-стек Gitea (не трогать, но убедиться, что жив) ---"
+docker ps --filter name=gitea --format "{{.Names}}\t{{.Status}}"
+'
+```
+
+Если первый блок (`docker ps -a --filter "name=^lab-"`) пустой — кластера нет вообще, нужно создавать (раздел 3). Если контейнеры есть, но статус `Exited` — кластер существует, но остановлен, поднимать без пересоздания (раздел 3). Если `Up` — кластер уже работает, `kubectl get nodes` покажет `Ready`.
+
+## 3. Запуск кластера
+
+**Кластера нет вообще** (`docker ps -a` по `lab-*` пусто) — создать заново:
+
+```bash
+# одна нода, как сейчас (модули 0-1 пройдены на таком)
+bash -lc "kind create cluster --name lab"
+
+# либо с топологией модуля 2 (1 control-plane + 2 worker), если уже дошёл до неё —
+# см. kind-config.yaml с extraPortMappings 8080/8443 в SERVER.md
+bash -lc "kind create cluster --name lab --config kind-config.yaml"
+```
+
+Занимает ~50-60 секунд с нуля (в основном скачивание образа ноды при первом разе).
+
+**Контейнеры есть, но `Exited`** (типичная ситуация после перезагрузки сервера — у kind-нод, в отличие от Gitea, нет `restart: unless-stopped`, сами не поднимаются) — поднять существующие без потери состояния:
+
+```bash
+ssh totserver@192.168.31.163 'docker start $(docker ps -aq --filter "name=^lab-")'
+ssh totserver@192.168.31.163 'bash -lc "kubectl wait --for=condition=Ready nodes --all --timeout=120s"'
+```
+
+После любого из двух вариантов — проверить, что kubectl смотрит именно в этот кластер:
+
+```bash
+ssh totserver@192.168.31.163 'bash -lc "kubectl config current-context"'
+# ожидается: kind-lab
+```
+
+## 4. Остановка кластера (пауза, не удаление)
+
+Когда заканчиваешь сессию курса и не хочешь держать кластер прогретым (он ест ~500 МБ RAM и часть ядра в простое — не критично, но незачем без нужды):
+
+```bash
+ssh totserver@192.168.31.163 'docker stop $(docker ps -aq --filter "name=^lab-")'
+```
+
+Поды, PVC, всё состояние кластера остаётся на диске и возвращается как было после `docker start` (раздел 3).
+
+## 5. Полный снос кластера
+
+Когда нужно чистое состояние — например, начиная модуль 2 с новой топологией (см. [PROGRESS.md](PROGRESS.md) → «Осталось на следующую сессию»):
+
+```bash
+ssh totserver@192.168.31.163 'bash -lc "kind delete cluster --name lab"'
+```
+
+Безопасно для остального на сервере — kind-образы отдельные от всего, что использует Gitea.
+
+## 6. Чего не трогать
+
+Рядом на том же Docker крутится боевой CI-стек Gitea — не часть курса, но легко случайно задеть. Коротко (полный чек-лист — [SERVER.md → «CI-инфраструктура на сервере — что нельзя ломать»](SERVER.md#ci-инфраструктура-на-сервере--что-нельзя-ломать)):
+
+- Не занимать порты **80, 443, 3000, 3030, 222, 4400, 9090** в `kind-config.yaml` (`extraPortMappings` — только 8080/8443).
+- Не выполнять `docker system prune -a` / `docker image prune -a` — унесёт локально собранный образ `gitea-runner-armhf`, которого больше нигде нет.
+- Не удалять `.runner`-файлы раннеров (`/opt/gitea/runner*/`) и `.env` рядом.
+- Не запускать `docker-compose ... --remove-orphans` внутри `/opt/gitea`.
+- `kind delete cluster` (раздел 5) — безопасен, гасит только кластер, Gitea не задевает.
+
+## 7. Куда дальше
+
+- На чём остановился по модулям курса — [PROGRESS.md](PROGRESS.md).
+- Что проходить дальше и как — [LEARNING.md](LEARNING.md).
+
+### Шпаргалка
+```
+# === СОСТОЯНИЕ КЛАСТЕРА ===
+kubectl get nodes -o wide
+kubectl get pods -A
+kubectl get pods,svc,deploy  # pods, services, deployments разом
+
+# === ДЕТАЛИ ===
+kubectl describe pod <имя>
+kubectl logs <имя-пода> --tail=20
+kubectl logs -f <имя-пода>   # follow
+
+# === ВНУТРЬ ПОДА ===
+kubectl exec -it <имя-пода> -- /bin/sh
+kubectl exec <имя-пода> -- ls /app
+
+# === СОЗДАТЬ/УДАЛИТЬ ===
+kubectl apply -f файл.yaml
+kubectl delete -f файл.yaml
+kubectl delete pod <имя>
+
+# === ПОМОЩЬ ===
+kubectl api-resources | grep -v "^NAME" | less  # что бывает
+kubectl explain deployment --recursive | less   # все поля deployment
+```