API Kubernetes
Ogólne reguły dotyczące API opisane są w dokumentacji API conventions.
Punkty dostępowe (endpoints) API, typy zasobów oraz przykłady są dostępne w API Reference.
Zdalny dostęp do API omówiono w dokumentacji Controlling API Access.
API Kubernetes to także podstawa deklaratywnego schematu konfiguracji dla systemu. Obiekty API mogą być tworzone, zmieniane, kasowane i odpytywane sa pomocą narzędzia linii poleceń kubectl.
Kubernetes przechowuje także swój serializowany stan (obecnie w etcd) w postaci obiektów API.
Kubernetes jako taki składa się z wielu elementów składowych, które komunikują się ze sobą poprzez swoje API.
- Zmiany w API
- Definicje OpenAPI i Swagger
- Obsługa wersji API
- Grupy API
- Włączanie i wyłączanie grup API
- Jak włączać dostęp do grup zasobów extensions/v1beta1
Zmiany w 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 oczekujemy, że API też będzie się zmieniało i rozrastało. W dłuższym horyzoncie nie planujemy jednak żadnych zmian, które mogą być niezgodne z istniejącymi klientami. 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.
Definicja zmiany zgodnej (kompatybilnej) oraz metody wprowadzania zmian w API opisano w szczegółach w API change document.
Definicje OpenAPI i Swagger
Pełne szczegóły API są udokumentowane zgodnie z OpenAPI.
Począwszy od Kubernetes w wersji 1.10, serwer Kubernetes API dostarcza specyfikację OpenAPI poprzez punkt końcowy /openapi/v2
.
Wymagany format określa się w nagłówkach HTTP:
Nagłówek | Dopuszczalne wartości |
---|---|
Accept | application/json , application/com.github.proto-openapi.spec.v2@v1.0+protobuf (domyślnie content-type to application/json dla */* lub pominięcie tego nagłówka) |
Accept-Encoding | gzip (pominięcie nagłówka jest dozwolone) |
W wersjach wcześniejszych niż 1.14, punkty końcowe określone przez ich format (/swagger.json
, /swagger-2.0.0.json
, /swagger-2.0.0.pb-v1
, /swagger-2.0.0.pb-v1.gz
) udostępniały specyfikację OpenAPI zgodnie z tymi formatami. Te punkty końcowe były stopniowo wycofywane i ostatecznie usunięte w wersji 1.14 Kubernetes.
Przykłady pobierania specyfikacji OpenAPI:
Przed 1.10 | Kubernetes 1.10 i nowszy |
---|---|
GET /swagger.json | GET /openapi/v2 Accept: application/json |
GET /swagger-2.0.0.pb-v1 | GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf |
GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf Accept-Encoding: gzip |
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.
Przed wersją 1.14, apiserver Kubernetes udostępniał też specyfikację API Swagger v1.2 poprzez /swaggerapi
.
Ten punkt końcowy został skierowany do wycofania i ostatecznie usunięty w wersji Kubernetes 1.14.
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/extensions/v1beta1
.
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. API and release versioning proposal 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 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.
- Nazwa wersji zawiera słowo
- 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.
- Nazwa wersji zawiera słowo
- Poziom Stabilny:
- Nazwa wersji jest w postaci
vX
, gdzieX
jest liczbą naturalną. - Stabilne funkcjonalności będą dostępne w wielu kolejnych wersjach oprogramowania.
- Nazwa wersji jest w postaci
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:
Grupa podstawowa (core), nazywana także legacy group, jest dostępna przez ścieżkę REST
/api/v1
i używaapiVersion: v1
.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:
- CustomResourceDefinition jest przewidziana dla użytkowników z minimalnymi wymaganiami CRUD.
- 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 apiserwerze. --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ą apiserwera.
Informacja: Włączenie lub wyłączenie grup lub zasobów wymaga restartu apiserver i controller-manager, aby zmiany w--runtime-config
zostały wprowadzone.
Jak włączać dostęp do grup zasobów extensions/v1beta1
DaemonSets, Deployments, HorizontalPodAutoscalers, Ingresses, Jobs i ReplicaSets znajdują się w grupie API extensions/v1beta1
i są domyślnie włączone.
Przykładowo: aby włączyć deployments i daemonsets, ustaw
--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true
.
Informacja: Włączanie i wyłączanie pojedynczych zasobów możliwe jest jedynie w ramach grupy APIextensions/v1beta1
z przyczyn historycznych
Twoja opinia
Czy ta strona była przydatna?
Dziękujemy za informację zwrotną. Jeśli masz konkretne pytanie dotyczące użycia Kubernetesa, odwiedź Stack Overflow. Otwórz zgłoszenie w repozytorium GitHub, jeśli chcesz zgłosić problem lub zaproponować poprawkę.