API Kubernetesa
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ą:
| 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
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.
| 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:
- Definicje zasobów własnych (custom resources) pozwalają deklaratywnie określać, jak serwer API powinien dostarczać wybrane przez Ciebie zasoby API.
- Można także rozszerzać API Kubernetesa implementując warstwę agregacji.
Co dalej?
- Naucz się, jak rozbudowywać API Kubernetesa poprzez dodawanie własnych CustomResourceDefinition.
- Controlling Access To The Kubernetes API opisuje sposoby, jakimi klaster zarządza dostępem do API.
- Punkty dostępowe API (endpoints), typy zasobów i przykłady zamieszczono w API Reference.
- Aby dowiedzieć się, jaki rodzaj zmian można określić jako zgodne i jak zmieniać API, zajrzyj do API changes.