diff --git a/content/pl/docs/concepts/overview/kubernetes-api.md b/content/pl/docs/concepts/overview/kubernetes-api.md index 7e8c842ff0..8d0a0fcedd 100644 --- a/content/pl/docs/concepts/overview/kubernetes-api.md +++ b/content/pl/docs/concepts/overview/kubernetes-api.md @@ -10,34 +10,156 @@ card: weight: 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. +Sercem {{< glossary_tooltip text="warstwy sterowania" term_id="control-plane" >}} +Kubernetesa 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_). +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](/docs/reference/kubectl/) lub inne -programy, takie jak -[kubeadm](/docs/reference/setup-tools/kubeadm/), które używają -API. Możesz też korzystać z API bezpośrednio przez wywołania typu REST. +Większość operacji może zostać wykonana poprzez interfejs +linii komend (CLI) [kubectl](/docs/reference/kubectl/) lub +inne programy, takie jak [kubeadm](/docs/reference/setup-tools/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](/docs/reference/using-api/client-libraries/). -Jeśli piszesz aplikację używającą API Kubernetesa, -warto rozważyć użycie jednej z [bibliotek klienckich](/docs/reference/using-api/client-libraries/). +Każdy klaster Kubernetesa publikuje specyfikację dostępnych interfejsów API. Dostępne +są dwa mechanizmy udostępniania tych specyfikacji, które +umożliwiają automatyczną integrację i interoperacyjność z narzędziami zewnętrznymi. +Na przykład narzędzie `kubectl` pobiera i buforuje specyfikację API w celu +umożliwienia autouzupełniania wiersza poleceń i innych funkcji. Te dwa mechanizmy to: + +- [Discovery API](#discovery-api) dostarcza informacji o interfejsach API + Kubernetesa: nazwach API, zasobach, wersjach i obsługiwanych operacjach. W + Kubernetesie ten termin ma szczególne znaczenie, ponieważ to odrębny + interfejs od OpenAPI i jest traktowany jako osobna część systemu. Jest to zwięzłe + podsumowanie dostępnych zasobów i nie obejmuje szczegółowych definicji + schematów. Szczegółowe informacje o strukturze zasobów można znaleźć w dokumencie OpenAPI. + +- [Kubernetes OpenAPI Document](#openapi-interface-definition) + dostarcza (pełne) [schematy OpenAPI v2.0 i 3.0](https://www.openapis.org/) + dla wszystkich endpointów API + Kubernetesa. OpenAPI v3 to zalecany sposób uzyskiwania dostępu do + specyfikacji API, ponieważ zapewnia pełniejszy i + dokładniejszy obraz. Zawiera wszystkie ścieżki API oraz komplet danych + wejściowych i wyjściowych dla każdej operacji na wszystkich endpointach. + Specyfikacja obejmuje także wszystkie + rozszerzenia wspierane przez klaster. Jest to pełna definicja API, która + znacząco przewyższa pod względem szczegółowości dane z Discovery API. + +## Discovery API {#discovery-api} + +Kubernetes przez Discovery API udostępnia pełną listę obsługiwanych grup +API, ich wersji oraz zasobów. Dla każdego zasobu można uzyskać następujące dane: + +- Nazwa +- Klaster lub zasięg w przestrzeni nazw +- URL endpointu oraz obsługiwane metody HTTP +- Alternatywne nazwy +- Grupa, wersja, typ + +API jest dostępne zarówno w formie zagregowanej, jak i niezagregowanej. +W trybie zagregowanym Discovery API udostępnia dwa endpointy, natomiast +w trybie niezagregowanym jest to oddzielny endpoint dla każdej wersji grupy. + +### Zagregowane Discovery API {#aggregated-discovery} + +{{< feature-state feature_gate_name="AggregatedDiscoveryEndpoint" >}} + +Kubernetes zapewnia stabilne wsparcie dla zagregowanego +Discovery API, publikując wszystkie zasoby obsługiwane przez klaster za +pośrednictwem dwóch endpointów (`/api` i `/apis`). +Korzystanie z tych endpointów znacząco ogranicza liczbę zapytań +potrzebnych do pobrania danych z klastra. Dostęp do tych danych +uzyskuje się, wysyłając żądanie na odpowiedni endpoint z +nagłówkiem `Accept`, który wskazuje na zagregowany zasób Discovery: +`Accept: application/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList`. + +W przypadku braku nagłówka `Accept` wskazującego +typ zasobu, zapytania do endpointów `/api` i +`/apis` zwracają domyślnie dane w formacie niezagregowanym. + +[Discovery document](https://github.com/kubernetes/kubernetes/blob/release-{{< skew currentVersion >}}/api/discovery/aggregated_v2.json) +znajduje się w oficjalnym repozytorium +GitHub Kubernetesa. Może on służyć jako odniesienie do podstawowego zestawu zasobów +dostępnych w Kubernetesie, gdy nie masz możliwości wykonania zapytania do rzeczywistego klastra. + +Endpoint obsługuje także mechanizm ETag oraz możliwość przesyłania danych w formacie protobuf. + +### Niezagregowane Discovery API {#unaggregated-discovery} + +W przypadku braku agregacji Discovery API, dane udostępniane są w strukturze +wielopoziomowej, w której główne endpointy publikują informacje prowadzące do podrzędnych dokumentów. + +Wszystkie wersje grup API dostępnych w klastrze są +udostępniane pod endpointami /api i /apis. Oto przykład: + +``` +{ + "kind": "APIGroupList", + "apiVersion": "v1", + "groups": [ + { + "name": "apiregistration.k8s.io", + "versions": [ + { + "groupVersion": "apiregistration.k8s.io/v1", + "version": "v1" + } + ], + "preferredVersion": { + "groupVersion": "apiregistration.k8s.io/v1", + "version": "v1" + } + }, + { + "name": "apps", + "versions": [ + { + "groupVersion": "apps/v1", + "version": "v1" + } + ], + "preferredVersion": { + "groupVersion": "apps/v1", + "version": "v1" + } + }, + ... +} +``` + +Żeby pobrać informacje o zasobach dostępnych w konkretnej +wersji API, trzeba wysłać osobne zapytanie pod +`/apis//` - np. `/apis/rbac.authorization.k8s.io/v1alpha1`. Ten +endpoint zawiera listę typów zasobów w danej grupie. Używa go +polecenie kubectl, żeby dowiedzieć się, jakie zasoby są dostępne w klastrze. -## Specyfikacja OpenAPI {#api-specification} + + +## Interfejs OpenAPI {#openapi-interface-definition} Pełną specyfikację API udokumentowano za pomocą [OpenAPI](https://www.openapis.org/). -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ą: +Kubernetes obsługuje zarówno OpenAPI 2.0, jak i 3.0. Wersja +3 jest preferowana, ponieważ umożliwia +dokładniejszy i kompletny opis zasobów (bez utraty +informacji). W OpenAPI 2 niektóre pola, np. `default`, +`nullable`, `oneOf`, są pomijane z powodu ograniczeń formatu. +### OpenAPI V2 {#openapi-v2} + +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ą: @@ -70,25 +192,22 @@ użyj nagłówków żądania zgodnie z tabelą:
Dopuszczalne wartości nagłówka żądania dla zapytań OpenAPI v2
-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](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md). -oraz w plikach *Interface Definition Language* (IDL) dla każdego ze schematów -zamieszczonych w pakietach Go, które definiują obiekty API. +{{< warning >}} +Reguły walidacyjne publikowane w ramach schematów OpenAPI mogą być niekompletne – i zazwyczaj nie +zawierają wszystkich warunków. Dodatkowa walidacja realizowana jest przez serwer API. Aby uzyskać pełną i +precyzyjną weryfikację, zaleca się użycie polecenia `kubectl apply --dry-run=server`, które uruchamia wszystkie +mechanizmy walidacji, również te wykonujące się podczas przyjmowania zasobów do klastra (ang. admission checks). +{{< /warning >}} -### OpenAPI V3 +### OpenAPI V3 {#openapi-v3} -{{< feature-state state="beta" for_k8s_version="v1.24" >}} +{{< feature-state feature_gate_name="OpenAPIV3" >}} -Kubernetes {{< param "version" >}} 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](/docs/reference/command-line-tools-reference/feature-gates/) o nazwie `OpenAPIV3` -składnika kube-apiserver. +Kubernetes publikuje własne API zgodnie ze specyfikacją OpenAPI v3. 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: +dostępnych grup/wersji. Zwracane wartości są dostępne tylko w formacie +JSON. Grupy/wersje opisane są następującym schematem: ```yaml { @@ -106,14 +225,14 @@ opisane są następującym schematem: ``` -Względne adresy URL wskazują na niezmieniające się opisy OpenAPI, -aby umożliwić trzymanie cache po stronie klienta. Serwer API zwraca +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. +`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//?hash=`, +Serwer API Kubernetesa udostępnia specyfikację +OpenAPI v3 pod adresem `/openapi/v3/apis//?hash=`, zgodnie z podziałem na grupy i wersje. Tabela poniżej podaje dopuszczalne wartości nagłówków żądania. @@ -149,67 +268,85 @@ Tabela poniżej podaje dopuszczalne wartości nagłówków żądania. -## Przechowywanie stanu +W pakiecie [`k8s.io/client-go/openapi3`](https://pkg.go.dev/k8s.io/client-go/openapi3) +znajduje się implementacja w Golang do pobierania OpenAPI V3. -Kubernetes przechowuje serializowany stan swoich obiektów w -{{< glossary_tooltip term_id="etcd" >}}. +Kubernetes {{< skew currentVersion >}} publikuje OpenAPI w wersji +2.0 i 3.0; nie ma planów wsparcia wersji 3.1 w najbliższej przyszłości. -## Grupy i wersje API +### Serializacja Protobuf {#protobuf-serialization} -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`. +Kubernetes implementuje alternatywny format serializacji oparty na +Protobuf, który jest głównie przeznaczony do komunikacji w obrębie klastra. Aby +uzyskać więcej informacji na temat tego formatu, zobacz +[Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md) propozycję +projektową oraz pliki Interface Definition Language +(IDL) dla każdego schematu znajdujące się w pakietach Go, które definiują obiekty API. -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. +## Przechowywanie stanu {#persistence} + +Kubernetes przechowuje serializowany stan swoich +obiektów w {{< glossary_tooltip term_id="etcd" >}}. + +## Grupy i wersje API {#api-groups-and-versioning} + +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*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md), które mogą być [włączane i wyłączane](/docs/reference/using-api/#enabling-or-disabling). -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. +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`. +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 +### Zmiany w API {#api-changes} -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. +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 +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](/docs/reference/using-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. +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. +Dodatkowo, Kubernetes zachowuje kompatybilność z danymi zapisanymi za pomocą wersji _beta_. Gdy dana +funkcja osiąga stabilność (GA), dane te mogą być automatycznie konwertowane i dostępne w docelowej wersji API. + +Jeśli korzystasz z wersji beta API, musisz przejść na kolejną wersję beta lub stabilną, gdy +dana wersja zostanie wycofana. Najlepszy moment na migrację to okres wycofywania +wersji beta - wtedy obiekty są dostępne równocześnie w obu wersjach API. Po zakończeniu +tego okresu wersja beta przestaje być obsługiwana i konieczne jest użycie wersji docelowej. {{< 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. +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. Może się okazać, że API +uległo niekompatybilnym zmianom, co wymaga usunięcia wszystkich istniejących obiektów alfa przed wykonaniem aktualizacji. {{< /note >}} Zajrzyj do [API versions reference](/docs/reference/using-api/#api-versioning) po szczegółowe definicje różnych poziomów wersji API. - - -## Rozbudowa API +## Rozbudowa API {#api-extension} API Kubernetesa można rozszerzać na dwa sposoby: @@ -222,9 +359,9 @@ API Kubernetesa można rozszerzać na dwa sposoby: - Naucz się, jak rozbudowywać API Kubernetesa poprzez dodawanie własnych [CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/). -- [Controlling Access To The Kubernetes API](/docs/concepts/security/controlling-access/) 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](/docs/reference/kubernetes-api/). +- [Controlling Access To The Kubernetes API](/docs/concepts/security/controlling-access/) + 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](/docs/reference/kubernetes-api/). - Aby dowiedzieć się, jaki rodzaj zmian można określić jako zgodne i jak zmieniać API, zajrzyj do [API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).