kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
website/content/pl/docs/concepts/overview/kubernetes-api.md

9.2 KiB
Raw Blame History

title content_type weight description card
API Kubernetesa concept 30 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.
name weight
concepts 30

Sercem {{< glossary_tooltip text="warstwy sterowania" term_id="control-plane" >}} Kubernetes jest {{< glossary_tooltip text="serwer API" term_id="kube-apiserver" >}}. 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 state="alpha" for_k8s_version="v1.23" >}}

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 {{< glossary_tooltip term_id="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.

{{< note >}} 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. {{< /note >}}

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.

{{% heading "whatsnext" %}}