Alauda Container Platform
  • Русский

    • Руководство по использованию Kubernetes API

    Содержание

    Дизайн документации

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

    1. Последовательность: Все ресурсы Kubernetes API следуют одному и тому же RESTful шаблону, поэтому повторять одинаковые схемы вызовов для каждого ресурса избыточно.

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

    3. Фокус на важном: Для большинства пользователей важнее понимать схему ресурса (какие поля доступны и что они означают), чем детали HTTP-механики вызовов API.

    4. Совместимость с инструментами: Большинство пользователей взаимодействуют с этими API через Kubernetes клиенты (kubectl, client-go и др.), а не напрямую через HTTP, поэтому детали HTTP менее актуальны для повседневной работы.

    Хотя наша документация по Kubernetes APIs сосредоточена на определениях схем ресурсов, это руководство дополняет её, объясняя общие шаблоны использования и соглашения вызовов Kubernetes API. Здесь вы узнаете, как структурировать API-запросы, разберётесь с распространёнными HTTP-методами и увидите стандартные URL-пути для различных операций — информацию, применимую ко всем ресурсам Kubernetes.

    Стандартные шаблоны вызовов Kubernetes API

    Tip

    Этот раздел содержит лишь базовое введение в шаблоны использования 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.