×

Подключение к пространству через kubectl

 
ВВЕДЕНИЕ
 
Всё, что вы делаете в дашборде DevSpace, можно делать и из командной строки — утилитой kubectl. Она обращается к тому же API платформы, но позволяет описывать сервисы файлами, хранить их в репозитории и запускать из скриптов и CI.
 
Подключение идёт к пространству — изолированной части платформы, выделенной вашей команде. Права ограничены им: вы видите и меняете только свои сервисы, и не видите чужие.
 
Из командной строки доступно то же, что и в дашборде, плюс то, чего в нём нет:
 
  • разворачивать и менять сервисы DevSpace — базы данных, брокеры, кластеры Kubernetes, виртуальные машины
  • настраивать их тоньше, чем позволяет форма, вплоть до правки YAML
  • смотреть состояние компонентов, события и логи при разборе проблем
  • применять готовые наборы манифестов одним файлом
  • автоматизировать всё это в CI или локальных скриптах
 
Вход устроен не через статический токен, а через учётную запись: платформа использует OIDC-аутентификацию, поэтому кроме kubectl понадобится вспомогательная утилита kubelogin.
 
ПЕРЕД НАЧАЛОМ
 
  • пространство в DevSpace создано и активно
  • вам выдана роль для управления его ресурсами
  • есть логин (адрес электронной почты) и пароль для входа
  • установлены kubectl и kubelogin — как это сделать, в следующих двух разделах
 
О версии kubectl: берите свежую и близкую к версии 1.34, расхождение в один минорный релиз допустимо. Версию кластера покажет команда kubectl version уже после подключения.
 
УСТАНОВКА KUBECTL
 
kubectl— стандартная консольная утилита управления Kubernetes. Проверить, установлена ли она:
kubectl version --client
 
Linux. Скачайте бинарный файл и положите его в системный каталог:
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/
 
macOS. Через Homebrew:
brew install kubernetes-cli
 
Windows. Через менеджер пакетов — Chocolatey или winget:
choco install kubernetes-cli
winget install -e --id Kubernetes.kubectl
 
УСТАНОВКА KUBELOGIN
 
kubelogin— стандартный плагин kubectl для входа по OIDC. Без него подключиться к пространству нельзя: kubectl сам по себе не умеет проходить вход по логину и паролю.
 
Работает он незаметно: вы запускаете обычную команду kubectl, та вызывает kubelogin, он открывает браузер для входа, получает токен и дальше обновляет его сам. Повторно вводить пароль нужно, только когда токен истечёт.
 
Linux. Скачайте бинарный файл под свою архитектуру (uname -m покажет её) и положите в системный каталог:
curl -L -o kubelogin https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64
chmod +x kubelogin && sudo mv kubelogin /usr/local/bin/kubectl-oidc_login
 
macOS. Через Homebrew, обязательно из репозитория автора:
brew install int128/kubelogin/kubelogin
Подсказка: в Homebrew есть два разных пакета с именем kubelogin. Короткая команда brew install kubelogin может поставить одноимённую утилиту для входа в облако Azure — она к DevSpace отношения не имеет. Указывайте полное имя, как в команде выше.
 
Windows. Скачайте файл kubelogin_windows_amd64.zip со страницы релизов проекта, распакуйте и положите kubelogin.exe в любой каталог из PATH под именем kubectl-oidc_login.exe.
 
Проверьте установку:
kubelogin --version
kubectl ищет плагин по имени kubectl-oidc_login в каталогах PATH. Пакетные менеджеры создают нужную ссылку сами, а при установке бинарным файлом имя задаёте вы — поэтому в команде выше файл переименован.
 
ПОШАГОВОЕ РУКОВОДСТВО
 
Шаг 1. Скачайте файл доступа
 
Файл доступа (kubeconfig) выдаёт панель управления Облакотеки. Откройте в ней раздел Портфель услуг → DevSpace, выберите своё пространство и найдите на его странице карточку Файлы доступа — в ней лежит файл для управления пространством.
 
Скачайте файл и положите в каталог, где вы держите конфигурации Kubernetes:
 
  • Linux и macOS — ~/.kube/
  • Windows — %USERPROFILE%\.kube\
 
Имя файла может быть любым, например devspace.yaml. Если каталога нет, создайте его:
mkdir -p ~/.kube
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.kube"
Файл доступа — это ваши учётные данные к пространству. Не выкладывайте его в репозиторий и не передавайте коллегам: доступ коллеге выдаётся отдельной ролью на пространство, а не копией файла.
 
Шаг 2. Укажите kubectl на этот файл
 
kubectl берёт конфигурацию из переменной KUBECONFIG, а если её нет — из файла ~/.kube/config. Проще всего указать путь переменной, не трогая остальные конфигурации:
export KUBECONFIG=~/.kube/devspace.yaml
$env:KUBECONFIG = "$env:USERPROFILE\.kube\devspace.yaml"
 
Переменная живёт до закрытия терминала. Чтобы не задавать её каждый раз, добавьте строку в профиль оболочки — ~/.bashrc или ~/.zshrc в Linux и macOS, профиль PowerShell в Windows.
 
Шаг 3. Войдите и выполните первую команду
 
Выполните любую команду, например список сервисов пространства:
kubectl get svc
 
При первом запуске откроется браузер со страницей входа: введите тот же адрес электронной почты и пароль, что и в панели управления. После успешного входа команда выполнится, а токен сохранится — следующие команды пароля не потребуют, пока он не истечёт.
 
Если браузер не открылся сам, скопируйте ссылку из сообщения в терминале и откройте её вручную.
 
ПРОВЕРКА
 
Убедитесь, что права на пространство выданы:
kubectl auth can-i get pods
 
Ответ yes означает, что доступ настроен верно.
 
Посмотрите, что развёрнуто в пространстве:
kubectl get svc
kubectl get pods
 
Сервисы DevSpace видны как объекты платформы — например, созданные базы данных:
kubectl get postgreses
 
Применить готовый набор манифестов можно одной командой:
kubectl apply -f my-services.yaml
 
ЕСЛИ ЧТО-ТО НЕ ТАК
 
Симптом
Причина
Что делать
 error: unknown command "oidc-login" for "kubectl"
kubelogin не установлен или лежит не под тем именем
Проверьте kubelogin --version и что файл называется kubectl-oidc_login и находится в PATH
 Браузер не открывается, команда ждёт
Терминал без графической среды, например подключение по SSH
Скопируйте ссылку из сообщения и откройте её в браузере на своём компьютере
 Error from server (Forbidden)
Команда обращается к ресурсам вне вашего пространства либо роль не выдана
Проверьте kubectl auth can-i. Если прав нет, запросите роль на пространство
 Error from server (Forbidden): ... in the namespace "default"
Команда выполнена без указания пространства
Добавьте к команде ключ -n tenant-<идентификатор> или пропишите пространство один раз: kubectl config set-context --current --namespace=tenant-<идентификатор>. Имя пространства есть в дашборде: под полем имени в форме создания сервиса (tenant-id) и в строке Namespace на карточке инстанса
Команды снова просят вход
Истёк срок действия токена
Это нормально: войдите заново, kubelogin сохранит новый токен
 The connection to the server ... was refused
В KUBECONFIG не тот файл или переменная не задана в этом терминале
Проверьте echo $KUBECONFIG и задайте путь заново
 
ЧТО ДАЛЬШЕ
 
Создание сервисов из файлов — опишите сервис в YAML и примените его kubectl apply. Примеры конфигураций есть в статьях по каждому сервису, например Создание инстанса PostgreSQL.
 
Свой кластер Kubernetes — Создание кластера K8s. У него отдельный файл доступа, не путайте его с файлом пространства.
 
Профили ресурсов — Справочник resourcesPresets и instanceTypes, чтобы задавать размеры сервисов в манифестах осознанно.