DevOpsLab/docs/kubernetes-kind.md

# Kubernetes Kind Кластеры

**Автор:** Сергей Антропов  
**Сайт:** https://devops.org.ru

## Содержание

- [Описание](#описание)
- [Требования к системе](#требования-к-системе)
- [Возможности](#возможности)
- [Быстрый старт](#быстрый-старт)
- [Команды управления](#команды-управления)
- [Работа с Helm](#работа-с-helm)
- [Работа с манифестами](#работа-с-манифестами)
- [Управление Ingress](#управление-ingress)
- [Проброс портов (Port-forward)](#проброс-портов-port-forward)
- [Мониторинг и логи](#мониторинг-и-логи)
- [Конфигурация](#конфигурация)
- [Архитектура](#архитектура)
- [Доступ к приложениям](#доступ-к-приложениям)
- [Кроссплатформенность](#кроссплатформенность)
- [Подробная документация по скриптам](#подробная-документация-по-скриптам)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

---

## Описание

Проект поддерживает автоматическое создание и управление Kubernetes кластерами на базе [Kind](https://kind.sigs.k8s.io/) для тестирования в изолированной лабораторной среде.

Kind позволяет создавать локальные Kubernetes кластеры внутри Docker контейнеров, что идеально подходит для разработки и тестирования без необходимости устанавливать полный Kubernetes.

## Требования к системе

### Обязательные требования

1. **Docker** - для запуска Kind кластеров
2. **Python 3** - для управления port-forward
3. **kubectl** - для работы с кластером

**Установка на macOS:**
```bash
brew install docker python3 kubectl
```

**Установка на Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install -y docker.io python3 python3-pip kubectl
```

**Установка на CentOS/RHEL:**
```bash
sudo yum install -y docker python3 python3-pip kubectl
sudo systemctl start docker
sudo systemctl enable docker
```

### Проверка установки

```bash
docker --version
python3 --version
kubectl version --client
```

### Docker группы

На Linux добавьте пользователя в группу docker:
```bash
sudo usermod -aG docker $USER
# Выйдите и войдите заново
```

---

## Возможности

- ✅ Создание Kind кластеров с настраиваемым количеством worker-узлов
- ✅ Автоматическая установка аддонов (Ingress NGINX, Metrics Server, Istio, Kiali, Prometheus Stack)
- ✅ **Автоматический port-forward** для доступа к сервисам
- ✅ Работа с Helm (установка, удаление, обновление, rollback)
- ✅ Работа с Kubernetes манифестами
- ✅ Управление Helm репозиториями
- ✅ Автоматическое управление `/etc/hosts` для Ingress
- ✅ Управление Docker контейнерами в лабораторной сети
- ✅ Интеграция с Istio Service Mesh
- ✅ Детальный отчет о состоянии кластера

---

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

### 1. Создание кластера

```bash
# Создание кластера с полным набором аддонов
make k8s create kubernetes
```

### 2. Проверка статуса

```bash
# Детальный отчет о кластере
make k8s status kubernetes
```

### 3. Доступ к аддонам

После создания кластера автоматически создаются port-forward:
- Grafana: http://localhost:3000
- Prometheus: http://localhost:9090
- Kiali: http://localhost:20001

### 4. Удаление кластера

```bash
make k8s destroy kubernetes
```

---

## Команды управления

### Создание кластера

```bash
# Минимальный кластер (без аддонов)
make k8s create

# Полный кластер с аддонами
make k8s create kubernetes

# Пользовательский пресет
make k8s create my-custom-preset
```

**Что происходит:**
1. Создается контейнер `k8s-controller` с инструментами (Kind, kubectl, Helm, Istio CLI)
2. Создаются Docker контейнеры из раздела `hosts` (если есть)
3. Создается Kind кластер
4. Устанавливаются аддоны
5. Создается автоматический port-forward
6. Добавляются записи в `/etc/hosts` для Ingress

### Управление жизненным циклом

```bash
# Удаление кластера (с очисткой port-forward и /etc/hosts)
make k8s destroy [preset]

# Остановка кластера (без удаления)
make k8s stop [preset]

# Запуск остановленного кластера
make k8s start [preset]

# Детальный отчет о состоянии
make k8s status [preset]

# Показать узлы кластера
make k8s nodes [preset]
```

### Получение kubeconfig

```bash
# Сохранить kubeconfig для подключения
make k8s config [preset]

# Использовать конфиг
export KUBECONFIG=kubeconfig
kubectl get nodes
```

### Shell доступ

```bash
# Открыть shell в контейнере k8s-controller
make k8s shell [preset]
```

---

## Работа с Helm

Helm - это менеджер пакетов для Kubernetes.

### Управление релизами

```bash
# Установить чарт
make k8s helm apply kubernetes nginx stable/nginx-ingress

# Обновить релиз
make k8s helm update kubernetes nginx stable/nginx-ingress

# Откатить релиз
make k8s helm rollback kubernetes nginx

# Посмотреть статус релиза
make k8s helm status kubernetes nginx

# Удалить релиз
make k8s helm delete kubernetes nginx

# Список всех релизов
make k8s helm list kubernetes
```

### Управление репозиториями

```bash
# Добавить репозиторий
make k8s helmrepo add kubernetes stable https://charts.helm.sh/stable

# Обновить репозиторий
make k8s helmrepo update kubernetes stable

# Список репозиториев
make k8s helmrepo list kubernetes

# Показать доступные чарты
make k8s helmrepo packages kubernetes stable

# Удалить репозиторий
make k8s helmrepo delete kubernetes stable
```

### Пример: установка MySQL

```bash
# Добавить репозиторий Bitnami
make k8s helmrepo add kubernetes bitnami https://charts.bitnami.com/bitnami

# Установить MySQL
make k8s helm apply kubernetes mysql bitnami/mysql

# Проверить статус
make k8s helm status kubernetes mysql
```

---

## Работа с манифестами

Применение обычных Kubernetes манифестов (без Helm).

```bash
# Применить манифест из URL
make k8s manifest apply kubernetes https://example.com/deploy.yaml

# Применить манифест из файла
make k8s manifest apply kubernetes /path/to/manifest.yaml

# Удалить манифест
make k8s manifest delete kubernetes https://example.com/deploy.yaml
```

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

```yaml
# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
```

```bash
# Применить
make k8s manifest apply kubernetes ./nginx-deployment.yaml
```

---

## Управление Ingress

### Доступ к приложениям через Ingress

Для доступа к приложениям по доменным именам нужно вручную добавить записи в `/etc/hosts`:

```bash
# Добавить запись в /etc/hosts
echo "127.0.0.1 grafana.local #k8s" | sudo tee -a /etc/hosts

# Очистить DNS кеш macOS
sudo killall -HUP mDNSResponder
```

После этого приложение будет доступно по адресу:
```
http://grafana.local:8081
```

**Пример манифеста Ingress:**

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grafana-ingress
  namespace: monitoring
spec:
  rules:
  - host: grafana.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: monitoring-grafana
            port:
              number: 80
```

**Важно:** 
- Записи в `/etc/hosts` нужно добавлять вручную
- Используйте порт 8081 для HTTP и 8443 для HTTPS
- Для удаления записей используйте sudo

---

## Проброс портов (Port-forward)

Port-forward позволяет получить доступ к ClusterIP сервисам извне кластера.

### Автоматический port-forward

После создания кластера автоматически создаются порты:
- Ingress HTTP: `8081:80`
- Ingress HTTPS: `8443:443`
- Grafana: `3000:80`
- Prometheus: `9090:9090`
- Kiali: `20001:20001`

### Управление вручную

```bash
# Создать port-forward
make k8s portforward create

# Список активных портов
make k8s portforward list

# Удалить конкретный порт
make k8s portforward delete 3000

# Очистить все порты
make k8s portforward clear

# Пересоздать порты
make k8s portforward recreate
```

### Ручной port-forward для своих сервисов

```bash
# Подключиться к кластеру
export KUBECONFIG=$(docker exec k8s-controller cat /root/.kube/config)

# Создать port-forward
kubectl port-forward -n default svc/my-service 8080:80
```

---

## Мониторинг и логи

### Детальный статус кластера

```bash
make k8s status kubernetes
```

Показывает:
- Узлы кластера
- Namespaces
- Pods
- Services
- Ingress
- Deployments
- DaemonSets
- StatefulSets
- PVC
- События
- Helm релизы
- Использование ресурсов

### Доступ к аддонам

**Grafana:**
```
URL: http://localhost:3000
Login: admin
Password: admin
```

**Prometheus:**
```
URL: http://localhost:9090
```

**Kiali:**
```
URL: http://localhost:20001
Login: admin
Password: admin
```

### Логи контейнера

```bash
# Логи k8s-controller
docker logs k8s-controller

# Логи в реальном времени
docker logs -f k8s-controller
```

### Логи кластера

```bash
# Логи конкретного pod
make k8s shell kubernetes
kubectl logs -n monitoring <pod-name>

# Все логи в namespace
kubectl logs -n monitoring --all-containers=true --tail=100
```

---

## Конфигурация

### Пресеты

Пресеты находятся в `molecule/presets/k8s/`:

**kubernetes.yml** - полный набор аддонов:
- Ingress NGINX
- Metrics Server
- Istio
- Kiali
- Prometheus + Grafana

### Структура пресета

```yaml
k8s_cluster:
  name: lab
  nodes: 1
  
addons:
  ingress: true
  metrics_server: true
  istio: true
  kiali: true
  prometheus_stack: true

addon_ports:
  ingress_http: 8081
  ingress_https: 8443
  prometheus: 9090
  grafana: 3000
  kiali: 20001
  metrics_server: 4443

hosts:
  - name: test1
    image: centos8
    systemd_defaults:
      container: true
  
images:
  centos8:
    name: inecs/ansible-lab:centos8-latest
```

### Пользовательский пресет

Создайте файл `molecule/presets/k8s/my-preset.yml`:

```yaml
k8s_cluster:
  name: my-cluster
  nodes: 2

addons:
  ingress: true
  metrics_server: false
  istio: false
  kiali: false
  prometheus_stack: false
```

Использование:
```bash
make k8s create my-preset
```

---

## Архитектура

```
┌─────────────────────────────────────────────────────┐
│              Локальная машина                      │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │  Makefile → Python скрипты → Docker API     │  │
│  │  kubectl (port-forward)                      │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────┐
│           Docker: k8s-controller                    │
│  ┌──────────────────────────────────────────────┐  │
│  │ kind, kubectl, helm, istioctl                │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────┐
│            Docker сеть: kind                        │
│  ┌──────────────────────────────────────────────┐  │
│  │         Kind Kubernetes Cluster              │  │
│  │  • Control Plane (6443)                      │  │
│  │  • Worker Nodes                              │  │
│  │  • Services (ClusterIP)                      │  │
│  │  • Ingress Controller                        │  │
│  │  • Istio Service Mesh                        │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
```

### Компоненты

1. **k8s-controller** - контейнер с инструментами управления
2. **Kind кластер** - Kubernetes кластер в Docker контейнерах
3. **Port-forward** - локальные процессы на хосте
4. **Ingress** - маршрутизация трафика внутрь кластера

---

## Доступ к приложениям

### Доступ через Ingress

1. Создайте Ingress манифест
2. Примените через `make k8s manifest apply`
3. Запись автоматически добавится в `/etc/hosts`
4. Приложение доступно по доменному имени

### Доступ через port-forward

Для ClusterIP сервисов:
```bash
kubectl port-forward -n namespace svc/service-name 8080:80
```

Доступ: http://localhost:8080

### Доступ внутри кластера

Из другого pod:
```bash
kubectl exec -it pod-name -- curl http://service-name.namespace:80
```

---

## Кроссплатформенность

### Поддерживаемые платформы

- **macOS (Intel & Apple Silicon)** - полная поддержка
- **Linux (amd64 & arm64)** - полная поддержка
- **Windows** - через WSL2

### Проблемы на разных платформах

**Apple Silicon (M1/M2):**
- Используется ARM64 образы
- Автоматическое определение архитектуры

**Linux:**
- Требуются права на Docker socket
- Возможны проблемы с selinux

---

## Подробная документация по скриптам

Для подробного описания работы всех скриптов управления Kubernetes смотрите:

📖 [Документация по скриптам Kubernetes](k8s-scripts.md)

Включает:
- Описание каждого скрипта
- Принцип работы
- Примеры использования
- Архитектура взаимодействия
- Отладка

---

## Best Practices

### 1. Используйте пресеты

Не создавайте кластеры вручную, используйте пресеты для консистентности.

### 2. Очищайте после работы

```bash
# После тестирования
make k8s destroy kubernetes
```

### 3. Проверяйте статус

```bash
# Регулярно проверяйте статус
make k8s status kubernetes
```

### 4. Используйте Helm для сложных приложений

Для многослойных приложений лучше использовать Helm вместо сырых манифестов.

### 5. Логируйте изменения

Все изменения в кластере через `make k8s` автоматически логируются.

---

## Troubleshooting

### Кластер не создается

**Проблема:** `kind create cluster` завершается с ошибкой

**Решение:**
```bash
# Проверьте Docker
docker ps

# Перезапустите Docker
sudo systemctl restart docker

# Очистите старые кластеры
kind delete cluster --all
```

### Port-forward не работает

**Проблема:** Невозможно подключиться к порту

**Решение:**
```bash
# Проверьте процессы
make k8s portforward list

# Пересоздайте порты
make k8s portforward recreate

# Проверьте, что порт свободен
lsof -i :3000
```

### kubectl не подключается

**Проблема:** `kubectl get nodes` выдает ошибку

**Решение:**
```bash
# Проверьте контейнер
docker ps | grep k8s-controller

# Зайдите в контейнер
make k8s shell kubernetes

# Проверьте кластер
kubectl get nodes

# Если не работает, пересоздайте кластер
make k8s destroy kubernetes
make k8s create kubernetes
```

### Аддоны не устанавливаются

**Проблема:** Grafana/Prometheus/Kiali не доступны

**Решение:**
```bash
# Проверьте статус кластера
make k8s status kubernetes

# Проверьте pods
make k8s shell kubernetes
kubectl get pods -n monitoring
kubectl logs -n monitoring <pod-name>

# Пересоздайте кластер
make k8s destroy kubernetes
make k8s create kubernetes
```

### Ingress не работает

**Проблема:** Доменные имена не резолвятся

**Решение:**
```bash
# Проверьте Ingress
make k8s shell kubernetes
kubectl get ingress --all-namespaces

# Добавьте запись в /etc/hosts вручную
echo "127.0.0.1 grafana.local #k8s" | sudo tee -a /etc/hosts

# Очистите DNS кеш
sudo killall -HUP mDNSResponder

# Проверьте доступность
curl http://grafana.local:8081
```

### Helm чарты не устанавливаются

**Проблема:** `helm install` завершается с ошибкой

**Решение:**
```bash
# Проверьте репозитории
make k8s helmrepo list kubernetes

# Обновите репозитории
make k8s helmrepo update kubernetes stable

# Проверьте логи
make k8s shell kubernetes
kubectl logs -l app=<release-name>
```

### Контейнер k8s-controller не запускается

**Проблема:** `docker: Error response from daemon: ...`

**Решение:**
```bash
# Проверьте образ
docker images | grep k8s

# Пересоберите образ
make docker build-image IMAGE=k8s-amd64
make docker build-image IMAGE=k8s-arm64

# Проверьте Docker
docker system prune -f
```

---

## Контакты

- **Автор:** Сергей Антропов
- **Сайт:** https://devops.org.ru
- **GitHub:** https://github.com/your-repo

---

## Лицензия

MIT