Informacje zawarte w tym dokumencie mogą być już nieaktualne
Ten dokument po raz ostatni został zmodyfikowany wcześniej niż wskazuje na to data publikacji jego wersji referencyjnej. To oznacza, że może być już nieaktualny. Jeśli znasz angielski, zajrzyj do oryginalnej, aktualizowanej na bieżąco, wersji dokumentacji: The Kubernetes API
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/[email protected]+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.24 [beta]
Kubernetes v1.31 publikuje (na razie w wersji roboczej) własne API zgodnie ze specyfikacją OpenAPI v3.
Ta funkcjonalność jest w wersji beta i jest domyślnie włączona.
Funkcjonalności w wersji beta można wyłączać poprzez
feature gate o nazwie OpenAPIV3
składnika kube-apiserver.
Pod adresem /openapi/v3
można znaleźć listę wszystkich
dostępnych grup/wersji. Zwracane wartości są dostępne tylko w formacie JSON. Grupy/wersje
opisane są następującym schematem:
{
"paths": {
...,
"api/v1": {
"serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
},
"apis/admissionregistration.k8s.io/v1": {
"serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
},
....
}
}
Względne adresy URL wskazują na niezmieniające się opisy OpenAPI,
aby umożliwić trzymanie cache po stronie klienta. Serwer API zwraca
również odpowiednie nagłówki HTTP dla cache (Expires
ustawione na 1 rok wprzód,
Cache-Control
jako immutable
). Wysłanie zapytania do nieaktualnego URL
spowoduje przekierowanie przez serwer API do wersji najnowszej.
Serwer API Kubernetesa udostępnia specyfikację OpenAPI v3
pod adresem /openapi/v3/apis/<group>/<version>?hash=<hash>
,
zgodnie z podziałem na grupy i wersje.
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/[email protected]+protobuf | głównie do celu komunikacji wewnątrz klastra |
application/json | domyślne | |
* | udostępnia application/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
, do czasu aż wersja v1beta1
będzie przestarzała i usunięta.
Wtedy możesz dalej korzystać i modyfikować obiekt poprzez wersję 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.
Informacja:
Mimo, że Kubernetes stara się także zachować zgodność dla API w wersji alpha, zdarzają się przypadki, kiedy nie jest to możliwe. Jeśli korzystasz z API w wersji alfa, przed aktualizacją klastra do nowej wersji zalecamy sprawdzenie w informacjach o wydaniu, czy nie nastąpiła jakaś zmiana w tej części API.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.