Teraz oglądasz dokumentację Kubernetesa w wersji: v1.21
Kubernetes v1.21 - dokumentacja nie jest już aktualizowana. Wyświetlona jest wersja archiwalna. Po aktualną dokumentację zajrzyj na najnowszą wersję.
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 Kubernetes API 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.
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.
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.