Руководство по использованию Kubernetes API
Содержание
Дизайн документации
В документации Kubernetes APIs мы сознательно сосредоточились на определениях схем ресурсов, а не на перечислении конкретных путей API, параметров и методов запросов для каждого ресурса. Такой подход основан на следующих соображениях:
-
Последовательность: Все ресурсы Kubernetes API следуют одному и тому же RESTful шаблону, поэтому повторять одинаковые схемы вызовов для каждого ресурса избыточно.
-
Читаемость: Документирование всех деталей API для каждого ресурса привело бы к длинной и повторяющейся документации, которую было бы сложнее воспринимать и использовать.
-
Фокус на важном: Для большинства пользователей важнее понимать схему ресурса (какие поля доступны и что они означают), чем детали HTTP-механики вызовов API.
-
Совместимость с инструментами: Большинство пользователей взаимодействуют с этими API через Kubernetes клиенты (kubectl, client-go и др.), а не напрямую через HTTP, поэтому детали HTTP менее актуальны для повседневной работы.
Хотя наша документация по Kubernetes APIs сосредоточена на определениях схем ресурсов, это руководство дополняет её, объясняя общие шаблоны использования и соглашения вызовов Kubernetes API. Здесь вы узнаете, как структурировать API-запросы, разберётесь с распространёнными HTTP-методами и увидите стандартные URL-пути для различных операций — информацию, применимую ко всем ресурсам Kubernetes.
Стандартные шаблоны вызовов Kubernetes API
Этот раздел содержит лишь базовое введение в шаблоны использования Kubernetes API. Для более полного и детального объяснения обратитесь к официальной документации Kubernetes API Concepts.
Все ресурсы Kubernetes API поддерживают стандартный набор операций, соответствующих RESTful соглашениям. Ниже приведены распространённые шаблоны вызовов API, применимые ко всем ресурсам, перечисленным в нашей документации Kubernetes APIs:
Коллекции ресурсов
Для коллекций ресурсов (например, Pods, Deployments и др.):
| Операция | HTTP-метод | Путь | Описание |
|---|---|---|---|
| Получить список всех ресурсов | GET | /apis/{group}/{version}/namespaces/{namespace}/{resource} | Возвращает список ресурсов в указанном namespace |
| Получить список всех ресурсов (по всему кластеру) | GET | /apis/{group}/{version}/{resource} | Возвращает список ресурсов по всем namespace (для ресурсов, поддерживающих это) |
| Создать ресурс | POST | /apis/{group}/{version}/namespaces/{namespace}/{resource} | Создаёт новый ресурс в указанном namespace |
| Создать ресурс (по всему кластеру) | POST | /apis/{group}/{version}/{resource} | Создаёт новый ресурс с областью действия по всему кластеру (для поддерживаемых ресурсов) |
Отдельные ресурсы
Для отдельных экземпляров ресурсов:
| Операция | HTTP-метод | Путь | Описание |
|---|---|---|---|
| Получить ресурс | GET | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Возвращает детали конкретного ресурса |
| Получить ресурс (по всему кластеру) | GET | /apis/{group}/{version}/{resource}/{name} | Возвращает детали конкретного ресурса с областью действия по всему кластеру |
| Обновить ресурс | PUT | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Полностью заменяет ресурс предоставленным определением |
| Обновить ресурс (по всему кластеру) | PUT | /apis/{group}/{version}/{resource}/{name} | Полностью заменяет ресурс с областью действия по всему кластеру |
| Частично обновить ресурс | PATCH | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Обновляет отдельные поля ресурса |
| Частично обновить ресурс (по всему кластеру) | PATCH | /apis/{group}/{version}/{resource}/{name} | Обновляет отдельные поля ресурса с областью действия по всему кластеру |
| Удалить ресурс | DELETE | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Удаляет указанный ресурс |
| Удалить ресурс (по всему кластеру) | DELETE | /apis/{group}/{version}/{resource}/{name} | Удаляет указанный ресурс с областью действия по всему кластеру |
Основная группа API
Для ресурсов из основной группы API (v1) пути немного отличаются:
| Операция | HTTP-метод | Путь | Описание |
|---|---|---|---|
| Получить список всех ресурсов | GET | /api/v1/namespaces/{namespace}/{resource} | Возвращает список основных ресурсов в указанном namespace |
| Получить ресурс | GET | /api/v1/namespaces/{namespace}/{resource}/{name} | Возвращает детали конкретного основного ресурса |
Общие параметры запроса
Kubernetes API поддерживает несколько общих параметров запроса, которые можно добавить к URL:
| Параметр | Описание | Пример |
|---|---|---|
pretty=true | Возвращает ответ в более удобочитаемом формате | /api/v1/namespaces/default/pods?pretty=true |
labelSelector | Фильтрует ресурсы по меткам | /api/v1/namespaces/default/pods?labelSelector=app=nginx |
fieldSelector | Фильтрует ресурсы по значениям полей | /api/v1/namespaces/default/pods?fieldSelector=status.phase=Running |
watch=true | Запускает наблюдение за изменениями | /api/v1/namespaces/default/pods?watch=true |
resourceVersion | Указывает, с какой версии начинать наблюдение | /api/v1/namespaces/default/pods?watch=true&resourceVersion=12345 |
limit | Ограничивает количество возвращаемых результатов | /api/v1/namespaces/default/pods?limit=50 |
continue | Токен для продолжения предыдущего запроса списка | /api/v1/namespaces/default/pods?continue=eyJ2IjoibWV0Y... |
Заключение
Следуя стандартным шаблонам Kubernetes API, описанным в этом документе, вы сможете взаимодействовать с любыми ресурсами, описанными в разделе Kubernetes APIs. Схемы, приведённые в документации API, показывают, какие данные можно отправлять и получать, а это руководство объясняет, как структурировать ваши API-запросы.
Для подробной информации о конкретных схемах ресурсов обращайтесь к разделу Kubernetes APIs.