Чтобы вести разработку в среде Kubernetes, необходимо:

  • локально установленный werf — сделано на предыдущих шагах;
  • приложение в Git — сделано на предыдущих шагах;
  • кластер Kubernetes;
  • реестр контейнеров (container registry);
  • правильные DNS-записи.

Настройка окружения — это сложная задача. Не рекомендуем закапываться в решение проблем своими руками: используйте существующие на рынке услуги, позовите на помощь коллег, которые имеют практику настройки инфраструктуры, или задавайте вопросы в Telegram-сообществе werf.

Чек-лист для самопроверки окружения
  • У вас есть кластер Kubernetes (версии 1.14 или выше).
    • В кластере установлен ingress-контроллер и на него направлен домен example.com, т.е. туда можно заходить браузером.
  • У вас есть registry.
    • Registry доступен по домену registry.example.com.
    • Кластер может pull’ить образы из вашего registry.
  • С локального компьютера:
    • есть доступ в кластер (работает kubectl version);
    • есть доступ в registry (работает docker push);
    • в браузере открывается example.com (пусть и показывает 404 от Ingress).

Выберите, как будете реализовывать окружение:

Minikube

Это «облегчённая» версия Kubernetes, работающая только на одном узле.

Установка

Установите minikube и запустите его:

minikube start --driver=docker

ВАЖНО: Если Minikube уже запущен в вашей системе, то надо удостоверится, что используется driver под названием docker. Если нет, то требуется перезапустить Minikube с помощью команды minikube delete и команды для старта, показанной выше.

В результате автоматически будет создан файл .kube/config с ключами доступа к локальному кластеру и werf сможет подключиться к локальному registry.

Итогом этих манипуляций должна стать возможность получить доступ к кластеру с помощью утилиты kubectl (возможно, эту утилиту придётся установить отдельно). Например, вызов:

kubectl get ns

… покажет список всех namespace’ов в кластере, а не сообщение об ошибке.

Ingress

В Minikube нужно включить addon:

minikube addons enable ingress
Как убедиться, что с Ingress всё хорошо?

По умолчанию можно считать, что всё хорошо. Если не уверены, что тут написано, вернитесь к этому пункту позже.

  • Балансировщик установлен.
  • Pod с балансировщиком корректно поднялся (для nginx-ingress это можно посмотреть так: kubectl -n ingress-nginx get po).
  • На 80-м порту (это можно посмотреть с помощью lsof -n | grep LISTEN) работает нужное приложение.

Registry

Включите addon minikube registry:

minikube addons enable registry

И далее, в зависимости от ОС:

Windows

Вывод команды должен содержать похожую строку:

...
* Registry addon on with docker uses 32769 please use that instead of default 5000
...

Запомните порт (например, 32769).

Запустите следующий проброс портов в отдельном терминале, заменив порт 32769 вашим портом:

docker run -ti --rm --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:32769"

Запустите сервис с привязкой к порту 5000:

kubectl -n kube-system expose rc/registry --type=ClusterIP --port=5000 --target-port=5000 --name=werf-registry --selector=actual-registry=true

Запустите следующий проброс портов в отдельном терминале:

kubectl port-forward --namespace kube-system service/werf-registry 5000
MacOS

Вывод команды должен содержать похожую строку:

...
* Registry addon on with docker uses 32769 please use that instead of default 5000
...

Запомните порт (например, 32769).

Запустите следующий проброс портов в отдельном терминале, заменив порт 32769 вашим портом:

docker run -ti --rm --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:32769"

Запустите следующий проброс портов в отдельном терминале, заменив порт 32769 вашим портом:

brew install socat
socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:32769
Linux

Запустите следующий проброс портов в отдельном терминале:

sudo apt-get install -y socat
socat -d -d TCP-LISTEN:5000,reuseaddr,fork TCP:$(minikube ip):5000

Hosts

В самоучителе предполагается, что кластер (вернее, его Nginx Ingress) доступен по адресу example.com, а registry — по адресу registry.example.com. Именно этот домен и его поддомены указаны в дальнейшем в конфигах. В случае, если вы будете использовать другие адреса, скорректируйте конфигурацию самостоятельно.

Обновите локальный файл /etc/hosts:

printf "\n$(minikube ip) example.com\n127.0.0.1 registry.example.com\n" | sudo tee -a /etc/hosts

Авторизация в Registry

Registry, установленный в minikube, не требует авторизации. Никаких дополнительных действий предпринимать не нужно.

Docker Desktop

Установка

Установите Docker Desktop на Windows или macOS.

Включите Kubernetes и настройте выделенные на него ресурсы.

Почему ресурсы — это важно?

Если у кластера будет слишком мало ресурсов, не сможет запуститься ваше приложение, Ingress или даже какой-то из необходимых самому оркестратору системных компонентов. Без опыта администрирования кластера разобраться в таких проблемах будет очень тяжело.

Составители самоучителя тестировали приложения на конфигурации 6 CPU, 6 ГБ памяти, swap на 1,5 ГБ, образ диска на 24 ГБ.

В результате автоматически будет создан файл .kube/config с ключами доступа к локальному кластеру и werf сможет подключиться к локальному registry.

Итогом этих манипуляций должна стать возможность получить доступ к кластеру с помощью утилиты kubectl (возможно, эту утилиту придётся установить отдельно). Например, вызов:

kubectl get ns

… покажет список всех namespace’ов в кластере, а не сообщение об ошибке.

Ingress

Нужно в явном виде установить Nginx Ingress вручную.

В случае Docker Desktop иногда бывают сложности с доступом к Ingress: порты могут не проброситься на хост-машину. Чтобы быть уверенным, что Ingress корректно работает, проверьте:

  • Pod с Ingress-контроллером корректно поднялся (для nginx-ingress это можно посмотреть так: kubectl -n ingress-nginx get po);
  • наличие службы на 80-м порту (это можно посмотреть с помощью lsof -n | grep LISTEN или аналогичным способом).

Если на 80-м порту (HTTP) нет Kubernetes — возможно, нужно пробросить порт вручную. Посмотрите имя Pod’а с ingress-controller:

kubectl -n ingress-nginx get po

… и затем запустите проброс порта:

kubectl port-forward --address 0.0.0.0 -n ingress-nginx ingress-nginx-controller-<тут_будут_буквы_цифры> 80:80

После описанных операций проверьте, что появилось на 80-м порту (например, lsof -n | grep LISTEN).

Registry

Docker Desktop не содержит встроенного registry. Самый простой способ — это запустить его вручную как Docker-образ:

docker run -d -p 5000:5000 --restart=always --name registry registry:2

Обратите внимание, что в этом случае по умолчанию registry будет работать без SSL-шифрования. А значит, при работе с werf потребуется добавлять параметр --insecure-registry=true.

Hosts

В самоучителе предполагается, что кластер (вернее, его Nginx Ingress) доступен по адресу example.com, а registry — по адресу registry.example.com. Именно этот домен и его поддомены указаны в дальнейшем в конфигах. В случае, если вы будете использовать другие адреса, скорректируйте конфигурацию самостоятельно.

Пропишите в локальном файле /etc/hosts строки вида:

127.0.0.1           example.com
127.0.0.1           registry.example.com

Авторизация в Registry

Если вы запустили registry локально, как приведено в примере выше, то ваш локальный registry работает без пароля и ничего делать не нужно.

Я использую внешний registry или установил логин/пароль

Для того, чтобы werf смог загрузить собранный образ в registry, нужно на локальной машине авторизоваться с помощью docker login примерно так:

docker login <registry_domain> -u <account_login> -p <account_password>

Выбираем один из облачных провайдеров

Существует огромное количество услуг, позиционирующихся как Managed Kubernetes. Часть из них включает серверные мощности, часть — нет.

Проще всего взять услугу в AWS (EKS) или Google Cloud (GKE). При первой регистрации они представляют бонус, которого должно хватить на неделю-другую работы с кластером. Однако для регистрации понадобится ввести данные банковской карты.

Альтернативой может стать использование Yandex.Cloud: здесь также предоставляется Managed Kubernetes и тоже требуется ввести данные карты. Но в качестве карты можно воспользоваться, например, виртуальной картой от Яндекс.Денег, позволяющей проводить платежи внутри России по подписке.

Также можно попробовать развернуть Kubernetes самостоятельно в Hetzner на основании их статьи — это один из самых дешёвых облачных провайдеров. Однако надо понимать, что вам придётся самостоятельно разбираться с большим пластом работ по администрированию платформы. Для production найдите надёжного провайдера или команду поддержки. Если вы ещё ни разу не устанавливали Kubernetes самостоятельно и/или не обладаете опытом системного администрирования — не стоит пытаться освоить такую объемную тему в рамках этого самоучителя.

Вне зависимости от выбранного облачного провайдера вам потребуется получить ключи доступа к Kubernetes-кластеру в виде файла .kube/config.

Что за .kube/config?

Это файл, хранящий реквизиты доступа к кластеру. Если разместить его по пути ~/.kube/config, утилиты, работающие с Kubernetes, смогут подключиться к кластеру.

Файл выглядит примерно так:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: ALotOfNumbersAndLettersAndSoOnAveryVERYveryLongStringInBase64=
    server: https://127.0.0.1:6445
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: kubernetes-admin
  name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: {}
users:
- name: kubernetes-admin
  user:
    client-certificate-data: ManyNumbersAndLettersAVERYveryVerylongString=
    client-key-data: ManyLettersAndNumbersAveryVeryVERYlongString=
apiVersion: v1 clusters: - cluster: certificate-authority-data: ALotOfNumbersAndLettersAndSoOnAveryVERYveryLongStringInBase64= server: https://127.0.0.1:6445 name: kubernetes contexts: - context: cluster: kubernetes user: kubernetes-admin name: kubernetes-admin@kubernetes current-context: kubernetes-admin@kubernetes kind: Config preferences: {} users: - name: kubernetes-admin user: client-certificate-data: ManyNumbersAndLettersAVERYveryVerylongString= client-key-data: ManyLettersAndNumbersAveryVeryVERYlongString=

Обратите внимание, что кроме ключей для подключения здесь содержится путь до API Kubernetes — например, server: https://127.0.0.1:6445. Важно, чтобы этот путь был корректным. Некоторые утилиты, генерирующие .kube/config, не подставляют туда публичный IP — тогда его нужно скорректировать вручную.

Проверка работоспособности и доступа к кластеру

Проверьте свой кластер по чек-листу в начале этой статьи.

Итогом всех манипуляций должна стать возможность получить доступ к кластеру с помощью утилиты kubectl (возможно, эту утилиту придётся установить отдельно). Например, вызов:

kubectl get ns

… покажет список всех namespace’ов в кластере, а не сообщение об ошибке.

Ingress

Нужно установить в кластер Nginx Ingress. На сайте решения есть подробные инструкции для ключевых провайдеров.

Registry

Скорее всего облачный провайдер registry как одну из услуг, но не всегда.

Мой провайдер не предоставляет registry, как быть?

Вы можете развернуть Docker Registry самостоятельно на отдельно стоящей виртуальной машине или воспользоваться каким-то облачным решением. werf поддерживает множество имплементаций реестров для контейнеров.

Обеспечьте сетевую связность кластера и registry: опять же, скорее всего облачный провайдер решает эту проблему самостоятельно, либо в нём есть специальные мануалы на этот счёт.

Hosts

В самоучителе предполагается, что кластер (вернее, его Nginx Ingress) доступен по адресу example.com, а registry — по адресу registry.example.com. Мы ожидаем, что вы самостоятельно выберете и настроите нужные DNS-записи, а при прохождении самоучителя будете подставлять в код свои домены.

Авторизация в registry

Для того, чтобы werf смог загрузить собранный образ в registry, нужно на локальной машине авторизоваться с помощью docker login примерно так:

docker login registry.example.com -u <account_login> -p <account_password>

где <account_login> — логин для доступа к registry, а <account_password> — пароль.

У меня уже есть кластер

Если у вас уже есть кластер, вероятно, вы уже сталкивались с его конфигурированием. Проверьте свой кластер по чек-листу в начале этой статьи.

Вне зависимости от того, как установлен кластер, необходимо получить ключи доступа к Kubernetes-кластеру в виде файла .kube/config.

Что за .kube/config?

Это файл, хранящий реквизиты доступа к кластеру. Если разместить его по пути ~/.kube/config, утилиты, работающие с Kubernetes, смогут подключиться к кластеру.

Файл выглядит примерно так:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: ALotOfNumbersAndLettersAndSoOnAveryVERYveryLongStringInBase64=
    server: https://127.0.0.1:6445
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: kubernetes-admin
  name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: {}
users:
- name: kubernetes-admin
  user:
    client-certificate-data: ManyNumbersAndLettersAVERYveryVerylongString=
    client-key-data: ManyLettersAndNumbersAveryVeryVERYlongString=
apiVersion: v1 clusters: - cluster: certificate-authority-data: ALotOfNumbersAndLettersAndSoOnAveryVERYveryLongStringInBase64= server: https://127.0.0.1:6445 name: kubernetes contexts: - context: cluster: kubernetes user: kubernetes-admin name: kubernetes-admin@kubernetes current-context: kubernetes-admin@kubernetes kind: Config preferences: {} users: - name: kubernetes-admin user: client-certificate-data: ManyNumbersAndLettersAVERYveryVerylongString= client-key-data: ManyLettersAndNumbersAveryVeryVERYlongString=

Обратите внимание, что кроме ключей для подключения здесь содержится путь до API Kubernetes — например, server: https://127.0.0.1:6445. Важно, чтобы этот путь был корректным. Некоторые утилиты, генерирующие .kube/config, не подставляют туда публичный IP — тогда его нужно скорректировать вручную.

Проверка работоспособности и доступа к кластеру

Проверьте свой кластер по чек-листу в начале этой статьи.

Итогом всех манипуляций должна стать возможность получить доступ к кластеру с помощью утилиты kubectl (возможно, эту утилиту придётся установить отдельно). Например, вызов:

kubectl get ns

… покажет список всех namespace’ов в кластере, а не сообщение об ошибке.

Ingress

В вашем кластере должен быть установлен Nginx Ingress. Если его нет, то в документации Kubernetes можно найти подробные инструкции.

Registry

werf поддерживает множество имплементаций registry.

Убедитесь, что есть сетевая связность кластера и registry.

Hosts

В самоучителе предполагается, что кластер (вернее, его Nginx Ingress) доступен по адресу example.com, а registry — по адресу registry.example.com. Мы ожидаем, что вы самостоятельно выберете и настроите нужные DNS-записи, а при прохождении самоучителя будете подставлять в код ваши домены.

Авторизация в Registry

Для того, чтобы werf смог загрузить собранный образ в registry, нужно на локальной машине авторизоваться с помощью docker login примерно так:

docker login <registry_domain> -u <account_login> -p <account_password>

Финальные проверки

Если вы уже убедились в работоспособности самого кластера, пришло время проверить registry и ingress. Эти команды:

docker pull ubuntu:18.04
docker tag ubuntu:18.04 registry.example.com:5000/ubuntu:18.04
docker push registry.example.com:5000/ubuntu:18.04

… должны успешно загрузить образ Ubuntu в registry и не выдать ошибку. А эта команда:

curl example.com

… должна выдать страницу ошибки nginx ingress (если вы ещё не задеплоили приложения в кластер).