Kubernetes API: как устроен и как с ним работать

Kubernetes API открывает главный вход в кластер, группу серверов под управлением Kubernetes. Любая команда, от kubectl (консольной утилиты для команд кластеру) до собственной автоматизации, превращается в HTTP-запрос к компоненту kube-apiserver. Он проверяет, кто вы и что вам можно, а затем меняет состояние кластера. Понимание Kubernetes API объясняет, как кластер устроен изнутри, а заодно открывает дорогу к автоматизации рутинных операций.

Kubernetes кажется набором разрозненных команд и YAML-файлов, пока не увидишь за ними одну конструкцию: всё в кластере описывается объектами API, а инструменты лишь по-разному эти объекты читают и меняют. После этого наблюдения манифесты (текстовые описания объектов в YAML), kubectl и ошибки доступа складываются в одну картину, и учить их по отдельности больше не нужно.

Как устроен

1. API-сервер работает единой точкой входа. По официальной документации управляющий слой это компоненты, которые управляют кластером и работают на мастер-узлах, а его ядро состоит из API-сервера и его HTTP-интерфейса: через него общаются и пользователи, и компоненты самого кластера.

2. Всё вокруг объектов. Поды (единицы запуска контейнеров), Deployment (описание копий приложения), Service (их общий адрес), секреты (пароли и ключи): каждый из них существует как объект API, а YAML-манифест даёт его текстовое описание. Когда вы применяете манифест, вы создаёте или меняете объект через API.

3. Декларативный подход. Вы описываете желаемое состояние, а контроллеры кластера через тот же API приводят реальность к описанию: пересоздают под после сбоя, добирают недостающую копию.

На схеме ниже три слоя: клиенты (kubectl, собственный код, компоненты кластера), затем kube-apiserver с проверкой прав, за ним объекты кластера, от подов и Deployment до секретов.

Как работать

1. Через kubectl, основной клиент. Каждая его команда уходит запросом к API-серверу. Для управляемого кластера VK Cloud (сервис Managed Containers) подключение настраивается по инструкции. Файл kubeconfig с адресом кластера и реквизитами скачивается из личного кабинета через меню кластера. Аутентификацию ведёт плагин client-keystone-auth. Путь к файлу задаётся переменной KUBECONFIG. Проверка связи идёт командой kubectl cluster-info (подключение через kubectl).

2. Из своего кода. Для Go, Python, Java, JavaScript и других языков существуют официальные клиентские библиотеки, с ними автоматизация пишется как работа с любым REST-сервисом. Подойдёт и прямой HTTP-запрос с токеном в заголовке, kubeconfig здесь не нужен. Это файл с настройками клиента, а не единственный ключ от кластера. Актуальный список библиотек ищите в документации Kubernetes, отправная точка та же страница про API.

3. С оглядкой на права. Доступ к API разграничивается ролями: человеку и роботу выдаются только нужные действия над нужными объектами. Сервисным учётным записям (учёткам для программ, а не людей) выдаются минимальные права, а ключи и kubeconfig хранятся как пароли.

С чего начать практику с API

1. Смотрите на kubectl как на переводчика. Привычка простая: после каждой команды спрашивать себя, какой объект она читала или меняла. Держите привычку, пока ответ не начнёт приходить раньше вывода команды, тогда структура API уложилась.

2. Читайте ошибки как ответы сервера. Ответ Unauthorized означает, что сервер вас не узнал, проверяйте kubeconfig и токен. Ответ Forbidden означает нехватку прав у вашей учётной записи, а сообщение о неизвестном поле означает расхождение манифеста с версией API кластера. Каждый из трёх ответов говорит, что чинить, без гадания.

3. Заведите для автоматизации отдельную учётную запись. Роботу выдаются права только на его объекты, а kubeconfig для него хранится отдельно от вашего личного. Утечка ключа робота тогда стоит пересоздания одной учётной записи, а не всего доступа к кластеру.

Четыре слова, которых хватит для этой и следующих статей цикла

1. Объект: единица состояния кластера, от пода до секрета.

2. Манифест: текстовое описание объекта, которое вы применяете.

3. Контроллер: процесс, который приводит кластер к описанному состоянию, а также объект, которым этот процесс управляет, например Deployment.

4. Роль: набор разрешённых действий над объектами, который отдельной привязкой выдаётся учётной записи.

Короче говоря для заметки:

1. Все дороги в кластер ведут через API-сервер, kubectl лишь один из его клиентов наравне с библиотеками и прямыми HTTP-запросами.

2. Манифесты описывают объекты API, а кластер сам приводит себя к описанному состоянию.

3. Доступ к API охраняется аутентификацией, ролями и ограничением сетевого доступа, реквизиты доступа храним как любые пароли.