API Kubernetesa

API Kubernetesa służy do odpytywania i zmiany stanu obiektów Kubernetesa. Sercem warstwy sterowania Kubernetesa jest serwer API i udostępniane po HTTP API. Przez ten serwer odbywa się komunikacja pomiędzy użytkownikami, różnymi częściami składowymi klastra oraz komponentami zewnętrznymi.

Sercem warstwy sterowania Kubernetes jest serwer API. 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 Kubernetesa pozwala na sprawdzanie i zmianę stanu obiektów (przykładowo: pody, Namespaces, ConfigMaps, Events).

Większość operacji może zostać wykonana poprzez interfejs linii komend (CLI) kubectl lub inne programy, takie jak kubeadm, które używają API. Możesz też korzystać z API bezpośrednio przez wywołania typu REST.

Jeśli piszesz aplikację używającą API Kubernetesa, warto rozważyć użycie jednej z bibliotek klienckich.

Specyfikacja OpenAPI

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

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

Dopuszczalne wartości nagłówka żądania dla zapytań OpenAPI v2
Nagłówek Dopuszczalne wartości Uwagi
Accept-Encoding gzip pominięcie tego nagłówka jest dozwolone
Accept application/com.github.proto-openapi.spec.v2@v1.0+protobuf głównie do celu komunikacji wewnątrz klastra
application/json domyślne
* udostępnia application/json

W Kubernetesie zaimplementowany jest alternatywny format serializacji na potrzeby API oparty o Protobuf, który jest przede wszystkim przeznaczony na potrzeby wewnętrznej komunikacji w klastrze. Więcej szczegółów znajduje się w dokumencie Kubernetes Protobuf serialization. oraz w plikach Interface Definition Language (IDL) dla każdego ze schematów zamieszczonych w pakietach Go, które definiują obiekty API.

OpenAPI V3

FEATURE STATE: Kubernetes v1.23 [alpha]

Kubernetes v1.23 umożliwia (na razie w we wczesnej wersji roboczej) publikowanie swojego API jako OpenAPI v3. Ta funkcjonalność jest w wersji alfa i jest domyślnie wyłączona. Funkcjonalności w wersji alfa można włączać poprzez feature gate o nazwie OpenAPIV3 składnika kube-apiserver.

Po włączeniu tej funkcjonalności, serwer API Kubernetesa udostępnia zagregowaną specyfikację OpenAPI v3 dla odpowiednich grup i wersji poprzez ścieżkę /openapi/v3/apis/<group>/<version>. Tabela poniżej podaje dopuszczalne wartości nagłówków żądania.

Dopuszczalne wartości nagłówka żądania dla zapytań OpenAPI v3
Nagłówek Dopuszczalne wartości Uwagi
Accept-Encoding gzip pominięcie tego nagłówka jest dozwolone
Accept application/com.github.proto-openapi.spec.v3@v1.0+protobuf głównie do celu komunikacji wewnątrz klastra
application/json domyślne
* udostępnia application/json

Poprzez ścieżkę /openapi/v3 można wyświetlić pełną listę dostępnych grup i wersji. Formatem odpowiedzi jest tylko JSON.

Przechowywanie stanu

Kubernetes przechowuje serializowany stan swoich obiektów w etcd.

Grupy i wersje 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.

Rozdział wersji wprowadzony jest na poziomie całego API, a nie na poziomach 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 oraz pozwala na kontrolowany dostęp do tych API, które są w fazie wycofywania lub fazie eksperymentalnej.

Aby ułatwić rozbudowę API Kubernetes, wprowadziliśmy grupy API, które mogą być włączane i wyłączane.

Zasoby API są rozróżniane poprzez przynależność do grupy API, typ zasobu, przestrzeń nazw (namespace,
o ile ma zastosowanie) oraz nazwę. Serwer API może przeprowadzać konwersję między różnymi wersjami API w sposób niewidoczny dla użytkownika: wszystkie te różne wersje reprezentują w rzeczywistości ten sam zasób. Serwer API może udostępniać te same dane poprzez kilka różnych wersji API.

Załóżmy przykładowo, że istnieją dwie wersje v1 i v1beta1 tego samego zasobu. Obiekt utworzony przez wersję v1beta1 może być odczytany, zaktualizowany i skasowany zarówno przez wersję v1beta1, jak i v1.

Trwałość API

Z naszego doświadczenia wynika, że każdy system, który odniósł sukces, musi się nieustająco rozwijać w miarę zmieniających się potrzeb. Dlatego Kubernetes został tak zaprojektowany, aby API mogło się zmieniać i rozrastać. Projekt Kubernetes dąży do tego, aby nie wprowadzać zmian niezgodnych z istniejącymi aplikacjami klienckimi i utrzymywać zgodność przez wystarczająco długi czas, aby inne projekty zdążyły się dostosować do zmian.

W ogólności, nowe zasoby i pola definiujące zasoby API są dodawane stosunkowo często. Usuwanie zasobów lub pól jest regulowane przez API deprecation policy.

Po osiągnięciu przez API statusu ogólnej dostępności (general availability - GA), oznaczanej zazwyczaj jako wersja API v1, bardzo zależy nam na utrzymaniu jej zgodności w kolejnych wydaniach. Kubernetes utrzymuje także zgodność dla wersji beta API tam, gdzie jest to możliwe: jeśli zdecydowałeś się używać API w wersji beta, możesz z niego korzystać także później, kiedy dana funkcjonalność osiągnie status stabilnej.

Zajrzyj do API versions reference po szczegółowe definicje różnych poziomów wersji API.

Rozbudowa API

API Kubernetesa można rozszerzać na dwa sposoby:

  1. Definicje zasobów własnych (custom resources) pozwalają deklaratywnie określać, jak serwer API powinien dostarczać wybrane przez Ciebie zasoby API.
  2. Można także rozszerzać API Kubernetesa implementując warstwę agregacji.

Co dalej?

Ostatnia modyfikacja January 22, 2022 at 12:58 PM PST : Synchronize Polish localization for ver 1.23, part 1 (65887b7e5)