Kubernetes API overview Polish docs sync

2020-06-19 09:54:34 +02:00 · 2020-06-19 09:54:34 +02:00 · 8f791213ab
parent cad0588597
commit 8f791213ab
1 changed files with 87 additions and 43 deletions
--- a/content/pl/docs/concepts/overview/kubernetes-api.md
+++ b/content/pl/docs/concepts/overview/kubernetes-api.md
@ -9,17 +9,13 @@ card:

 <!-- overview -->

-Ogólne reguły dotyczące API opisane są w dokumentacji [API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md).
+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.

-Punkty dostępowe *(endpoints)* API, typy zasobów oraz przykłady są dostępne w [API Reference](/docs/reference).
+API Kubernetes pozwala na sprawdzanie i zmianę stanu obiektów (przykładowo: pody, _Namespaces_, _ConfigMaps_, _Events_).

-Zdalny dostęp do API omówiono w dokumentacji [Controlling API Access](/docs/reference/access-authn-authz/controlling-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](/docs/reference/kubectl/overview/).
-
-Kubernetes przechowuje także swój serializowany stan (obecnie w [etcd](https://coreos.com/docs/distributed-configuration/getting-started-with-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.
+Punkt dostępowe _(endpoints)_ API, typy zasobów i przykłady opisane są w [API Reference](/docs/reference/kubernetes-api/).



@ -28,48 +24,76 @@ Kubernetes jako taki składa się z wielu elementów składowych, które komunik

 ## 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](/docs/reference/using-api/deprecation-policy/).
+Jednym z wymagań, które odnoszą się do każdego systemu, który odniósł sukces, jest zdolność do rozwoju i ewolucji w miarę pojawiających się i zmieniających potrzeb.
+Dlatego Kubernetes został zaprojektowany tak, aby umożliwić ciągły rozwój i zmiany w API.
+Celem projektu Kubernetes jest _zachowanie_ zgodności z istniejącymi klientami i utrzymanie tej zgodności
+przez odpowiednio długi czas, pozwalający innym projektom na stopniowe dostosowanie.

-Definicja zmiany zgodnej (kompatybilnej) oraz metody wprowadzania zmian w API opisano w szczegółach w [API change document](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md).
+W skrócie, nowe zasoby API i nowe pola dla konkretnych zasobów mogą być dodawane stosunkowo często.
+Usunięcie zasobów lub pól wymaga stosowania
+[API deprecation policy](/docs/reference/using-api/deprecation-policy/).

-## Definicje OpenAPI i Swagger
+Szczegółowe objaśnienia, jak wygląda zmiana, która zachowuje zgodność i jak zmieniać API, znajdują się w dokumencie
+[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).

-Pełne szczegóły API są udokumentowane zgodnie z [OpenAPI](https://www.openapis.org/).
+## Specyfikacja OpenAPI {#api-specification}

-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:
+Pełną specyfikację API udokumentowano za pomocą [OpenAPI](https://www.openapis.org/).

-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)
+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:

-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
+<table>
+  <thead>
+     <tr>
+        <th>Nagłówek</th>
+        <th style="min-width: 50%;">Dopuszczalne wartości</th>
+        <th>Uwagi</th>
+     </tr>
+  </thead>
+  <tbody>
+     <tr>
+        <td><code>Accept-Encoding</code></td>
+        <td><code>gzip</code></td>
+        <td><em>pominięcie tego nagłówka jest dozwolone</em></td>
+     </tr>
+     <tr>
+        <td rowspan="3"><code>Accept</code></td>
+        <td><code>application/com.github.proto-openapi.spec.v2@v1.0+protobuf</code></td>
+        <td><em>głównie do celu komunikacji wewnątrz klastra</em></td>
+     </tr>
+     <tr>
+        <td><code>application/json</code></td>
+        <td><em>domyślne</em></td>
+     </tr>
+     <tr>
+        <td><code>*</code></td>
+        <td><em>udostępnia </em><code>application/json</code></td>
+     </tr>
+  </tbody>
+  <caption>Dozwolone nagłówki żądań dla zapytania OpenAPI v2</caption>
+</table>

 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](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md). 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](http://swagger.io/) 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
+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.
+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.

-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](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) opisuje związki pomiędzy zarządzaniem wersjami API i oprogramowania.
+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.

-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](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions). Podsumowanie zamieszczono poniżej poniżej:
+Należy mieć na uwadze, że wersje API i wersje oprogramowania są powiązane ze sobą w sposób niebezpośredni. Proponowany
+[Kubernetes Release Versioning](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) 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](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
+Podsumowanie zamieszczono poniżej:

 - Poziom Alfa:
  - Nazwa wersji zawiera słowo `alpha` (np. `v1alpha1`).
@ -81,8 +105,11 @@ Różne wersje API oznaczają inną stabilność i poziom wsparcia. Kryteria dla
  - 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ąć.
+  - 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.**
 - Poziom Stabilny:
  - Nazwa wersji jest w postaci `vX`, gdzie `X` jest liczbą naturalną.
@ -111,18 +138,35 @@ API może być rozbudowane na dwa sposoby przy użyciu [custom resources](/docs/
 ## 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ć
+w kube-apiserver.
+
+`--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.
+Ta opcja przyjmuje rozdzielony przecinkami zbiór par klucz=wartość, który opisuje konfigurację wykonawczą serwera API.

-{{< note >}}Włączenie lub wyłączenie grup lub zasobów wymaga restartu apiserver i controller-manager, aby zmiany w `--runtime-config` zostały wprowadzone.{{< /note >}}
+{{< note >}}Włączenie lub wyłączenie grup lub zasobów wymaga restartu kube-apiserver i kube-controller-manager,
+aby zmiany w `--runtime-config` zostały wprowadzone.{{< /note >}}

-## Jak włączać dostęp do grup zasobów extensions/v1beta1
+## 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.
+DaemonSets, Deployments, HorizontalPodAutoscalers, Ingresses, Jobs i ReplicaSets znajdują się w grupie API `extensions/v1beta1` i są domyślnie wyłączone.
 Przykładowo: aby włączyć deployments i daemonsets, ustaw
 `--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true`.

 {{< note >}}Włączanie i wyłączanie pojedynczych zasobów możliwe jest jedynie w ramach grupy API `extensions/v1beta1` z przyczyn historycznych{{< /note >}}

+## Trwałość

+Kubernetes przechowuje swój stan w postaci serializowanej jako zasoby API zapisywane w
+{{< glossary_tooltip term_id="etcd" >}}.
+
+
+## {{% heading "whatsnext" %}}
+
+[Controlling API Access](/docs/reference/access-authn-authz/controlling-access/) opisuje
+sposoby, jakimi klaster zarządza dostępem do API.
+
+Ogólne wytyczne dotyczące API opisano w
+[API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions).
+
+Punkty dostępowe API endpoints, typy zasobów i przykłady zamieszczono w [API Reference](/docs/reference/kubernetes-api/).