Edit This Page

API Kubernetes

Sercem warstwy sterowaniaThe container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers. Kubernetes jest serwer APISkładnik warstwy sterowania udostępniający API Kubernetes. . Serwer udostępnia API poprzez HTTP, umożliwiając wzajemną komunikację pomiędzy użytkownikami, częściami składowymi klastra i komponentami zewnętrznymi.

API Kubernetes pozwala na sprawdzanie i zmianę stanu obiektów (przykładowo: pody, Namespaces, ConfigMaps, Events).

Punkt dostępowe (endpoints) API, typy zasobów i przykłady opisane są w API Reference.

Zmiany w API

Jednym z wymagań, które odnoszą się do każdego systemu, który odniósł sukces, jest zdolność do rozwoju i ewolucji w miarę pojawiających się i zmieniających potrzeb. Dlatego Kubernetes został zaprojektowany tak, aby umożliwić ciągły rozwój i zmiany w API. Celem projektu Kubernetes jest zachowanie zgodności z istniejącymi klientami i utrzymanie tej zgodności przez odpowiednio długi czas, pozwalający innym projektom na stopniowe dostosowanie.

W skrócie, nowe zasoby API i nowe pola dla konkretnych zasobów mogą być dodawane stosunkowo często. Usunięcie zasobów lub pól wymaga stosowania API deprecation policy.

Szczegółowe objaśnienia, jak wygląda zmiana, która zachowuje zgodność i jak zmieniać API, znajdują się w dokumencie API changes.

Specyfikacja OpenAPI

Pełną specyfikację API udokumentowano za pomocą OpenAPI.

Serwer API Kubernetes API udostępnia specyfikację OpenAPI poprzez ścieżkę /openapi/v2. Aby wybrać format odpowiedzi, użyj nagłówków żądania zgodnie z:

W Kubernetes zaimplementowany jest alternatywny format serializacji na potrzeby API oparty o Protobuf, który jest przede wszystkim przeznaczony na potrzeby wewnętrznej komunikacji w klastrze i opisany w design proposal. Pliki IDL dla każdego ze schematów można znaleźć w pakietach Go, które definiują obiekty API.

Obsługa wersji API

Aby ułatwić usuwanie poszczególnych pól lub restrukturyzację reprezentacji zasobów, Kubernetes obsługuje równocześnie wiele wersji API, każde poprzez osobną ścieżkę API, na przykład: /api/v1 lub /apis/rbac.authorization.k8s.io/v1alpha1.

Zdecydowaliśmy się na rozdział wersji na poziomie całego API, a nie na poziomie poszczególnych zasobów lub pól, aby być pewnym, że API odzwierciedla w sposób przejrzysty i spójny zasoby systemowe i ich zachowania i pozwala na kontrolowany dostęp do tych API, które są w fazie wycofywania lub fazie eksperymentalnej.

Schematy serializacji JSON i Protobuf stosują się do tych samych reguł wprowadzania zmian schematów — cały opis poniżej odnosi się do obydwu z nich.

Należy mieć na uwadze, że wersje API i wersje oprogramowania są powiązane ze sobą w sposób niebezpośredni. Proponowany Kubernetes Release Versioning opisuje związki pomiędzy zarządzaniem wersjami API i oprogramowania.

Różne wersje API oznaczają inną stabilność i poziom wsparcia. Kryteria dla każdego z tych poziomów opisano szczegółowo w API Changes documentation. Podsumowanie zamieszczono poniżej:

• Poziom Alfa:
  • Nazwa wersji zawiera słowo alpha (np. v1alpha1).
  • Może zawierać błędy. Włączenie tej funkcjonalności może wyeksponować różne błędy. Domyślnie jest wyłączona.
  • Wsparcie dla tej funkcjonalności może być zakończone w dowolnej chwili bez uprzedniego powiadomienia.
  • W kolejnych wersjach API może zostać zmienione w sposób niezgodny z wersjami wcześniejszymi.
  • Rekomendowana do użycia tylko na często przebudowywanych klastrach testowych ze względu na duże ryzyko wystąpienia błędów i brak gwarancji wsparcia w dalszym horyzoncie.
• Poziom Beta:
  • Nazwa wersji zawiera słowo beta (np. v2beta3).
  • Oprogramowanie jest dobrze przetestowane. Włączenie tej funkcjonalności uznaje się za bezpieczne. Funkcjonalność domyślnie włączona.
  • Wsparcie dla funkcjonalności będzie utrzymywane, choć może zmieniać się w niektórych szczegółach.
  • Schemat lub semantyka obiektu może się zmienić w sposób niezgodny z poprzednimi wersjami w następnych wydaniach beta lub stabilnych. Jeśli taka zmiana będzie miała miejsce, dostarczymy instrukcję migracji do kolejnej wersji. Możemy wymagać skasowania, zmiany i odtworzenia obiektów API. Proces zmiany może wymagać dodatkowych wstępnych analiz. W czasie wprowadzania zmian mogą wystąpić przerwy w dostępności aplikacji, które z tej funkcjonalności korzystają.
  • Rekomendowane tylko dla zastosowań niekrytycznych dla biznesu ze względu na potencjalnie niezgodne zmiany w kolejnych wersjach oprogramowania. Jeśli masz wiele klastrów, które mogą być aktualizowane niezależnie, można to ograniczenie pominąć.
  • Testuj nasze funkcjonalności w fazie beta i zgłaszaj swoje uwagi! Po wyjściu z fazy beta, możemy nie mieć już możliwości — ze względów praktycznych — wprowadzać w nich żadnych zmian.
• Poziom Stabilny:
  • Nazwa wersji jest w postaci vX, gdzie X jest liczbą naturalną.
  • Stabilne funkcjonalności będą dostępne w wielu kolejnych wersjach oprogramowania.

Grupy API

Aby ułatwić rozbudowę API Kubernetes, wprowadziliśmy grupy API. Grupa API jest określona przez ścieżkę API i pole apiVersion serializowanego obiektu.

Obecne w użyciu jest kilka grup API:

1. Grupa podstawowa (core), nazywana także legacy group, jest dostępna przez ścieżkę REST /api/v1 i używa apiVersion: v1.

2. Nazwane grupy udostępnione są przez ścieżkę REST /apis/$GROUP_NAME/$VERSION i używają apiVersion: $GROUP_NAME/$VERSION (np. apiVersion: batch/v1). Pełna lista wpieranych grup API jest dostępna w Kubernetes API reference.

API może być rozbudowane na dwa sposoby przy użyciu custom resources:

1. CustomResourceDefinition jest przewidziana dla użytkowników z minimalnymi wymaganiami CRUD.
2. Użytkownicy, którzy potrzebują pełnej semantyki API Kubernetes, mogą zaimplementować własny apiserver i użyć agregatora, aby zintegrować je w sposób niezauważalny dla klientów.

Włączanie i wyłączanie grup API

Określone zasoby i grupy API są włączone domyślnie. Włączanie i wyłączanie odbywa się poprzez ustawienie --runtime-config w kube-apiserver.

--runtime-config przyjmuje wartości oddzielane przecinkami. Przykładowo, aby wyłączyć batch/v1, należy ustawić --runtime-config=batch/v1=false, aby włączyć batch/v2alpha1, należy ustawić --runtime-config=batch/v2alpha1. Ta opcja przyjmuje rozdzielony przecinkami zbiór par klucz=wartość, który opisuje konfigurację wykonawczą serwera API.

Informacja: Włączenie lub wyłączenie grup lub zasobów wymaga restartu kube-apiserver i kube-controller-manager, aby zmiany w --runtime-config zostały wprowadzone.

Trwałość

Kubernetes przechowuje swój stan w postaci serializowanej jako zasoby API zapisywane w etcdMagazyn typu klucz-wartość (key/value store), zapewniający spójność i wysoką dostępność, używany do przechowywania wszystkich danych o klastrze Kubernetes. .

Następne:

Controlling API Access opisuje sposoby, jakimi klaster zarządza dostępem do API.

Ogólne wytyczne dotyczące API opisano w API conventions.

Punkty dostępowe API (endpoints), typy zasobów i przykłady zamieszczono w API Reference.