Każdy klaster Kubernetes opisuje własne API, a sgcOpenAPI zamienia ten opis w jednostkę Pascala, którą wywołujesz z Delphi. To największa z publicznych specyfikacji na tych stronach i jedyna, w której wybór dokumentu źródłowego naprawdę zmienia wynik, więc ta strona mówi, z którego endpointu generować i jakie są dwa znane ograniczenia.
Wszystko poniżej zostało zmierzone przez uruchomienie generatora na specyfikacjach Kubernetes i skompilowanie wyniku, nie są to szacunki.
Dokumenty OpenAPI 3 na grupę, spod /openapi/v3, po jednym naraz. To droga, która daje poprawnego klienta.
Zagregowany dokument /openapi/v2. To Swagger 2.0, konwertuje się i generuje, ale dwie rzeczy wychodzą źle. Obie są opisane niżej.
Generuj z -a 2 i ustaw Authentication.Token.BearerToken, co wysyła token ServiceAccount jako Authorization: Bearer.
Kubernetes nie deklaruje hosta serwera, więc przekaż -u https://cluster:6443 przy generowaniu albo wywołaj SetBaseURL w czasie działania.
/openapi/v3 to indeks, nie dokumentTo pierwsza rzecz do zrozumienia. Klaster nie udostępnia jednego pliku OpenAPI 3. /openapi/v3 zwraca listę ścieżek grup, a każda grupa i wersja to osobny dokument pod własnym adresem URL.
# jeden dokument na grupę i wersję API, 65 w standardowym klastrze
> sgcOpenAPI.exe -i "https://10.0.0.1:6443/openapi/v3/api/v1" \
-o "k8s_core_v1.pas" -a 2 -u "https://10.0.0.1:6443"
File successfully created k8s_core_v1.pas
> sgcOpenAPI.exe -i "https://10.0.0.1:6443/openapi/v3/apis/apps/v1" \
-o "k8s_apps_v1.pas" -a 2 -u "https://10.0.0.1:6443"
File successfully created k8s_apps_v1.pas
Wygenerowana w ten sposób grupa core daje 113 ścieżek, 248 metod i 293 klasy modeli w jednostce liczącej 42 705 wierszy, a grupa apps daje 38 ścieżek, 77 metod i 180 klas modeli w 17 061 wierszach. Obie kompilują się bez błędów w RAD Studio 12 dla Win32, przy czym na ścieżce bibliotek nie ma nic poza folderem Source sgcOpenAPI. Jedna jednostka na grupę jest też wygodniejsza w codziennej pracy niż jedna ogromna jednostka, a generujesz tylko te grupy, które faktycznie wywołujesz.
Te same dokumenty są publikowane w repozytorium Kubernetes pod api/openapi-spec/v3/, więc możesz generować z pliku trzymanego w repozytorium zamiast z żywego klastra i utrzymywać wynik pod kontrolą wersji.
Kubernetes zapisuje identyfikatory operacji od razu jako poprawne identyfikatory, więc wygenerowana metoda zachowuje nazwę ze specyfikacji.
uses k8s_core_v1; // właśnie wygenerowana jednostka procedure TfrmK8s.btnPodsClick(Sender: TObject); var oResponse: TsgcOpenAPI_listCoreV1NamespacedPod_Response; oPod: TsgcOpenAPI_io_k8s_api_core_v1_Pod_Class; begin GetOpenAPIClient.Authentication.Token.BearerToken := vToken; GetOpenAPIClient.SetBaseURL('https://10.0.0.1:6443'); // aNamespace, aPretty, potem parametry zapytania w kolejności deklaracji oResponse := GetOpenAPIClient.listCoreV1NamespacedPod('production', '', oapiBoolNull, '', '', 'app=api,tier=backend'); try if oResponse.IsSuccessful then for oPod in oResponse.Successful.Items do memoLog.Lines.Add(Format('%-30s %s %s', [oPod.Metadata.Name, oPod.Status.Phase, oPod.Status.HostIP])) else memoLog.Lines.Add(IntToStr(oResponse.ResponseCode) + ' ' + oResponse.ResponseError); finally oResponse.Free; end; end;
Klasy modeli noszą pełne nazwy Kubernetes, więc pod to TsgcOpenAPI_io_k8s_api_core_v1_Pod_Class z Metadata, Spec i Status, a lista to TsgcOpenAPI_io_k8s_api_core_v1_PodList_Class z typowanym Items. Logiczny parametr zapytania, który Kubernetes deklaruje jako opcjonalny, staje się TsgcOpenAPIBoolean, a jego wartość oapiBoolNull oznacza, że parametr zostaje pominięty w adresie URL, zamiast zostać wysłany jako false.
Tam, gdzie Kubernetes opisuje ciało żądania nazwanym schematem, a zwykle tak robi, wygenerowana metoda przyjmuje typowaną klasę zamiast łańcucha znaków.
uses k8s_apps_v1; var oRead: TsgcOpenAPI_readAppsV1NamespacedDeploymentScale_Response; oWrite: TsgcOpenAPI_replaceAppsV1NamespacedDeploymentScale_Response; begin oRead := GetOpenAPIClient.readAppsV1NamespacedDeploymentScale( 'api', 'production'); try if not oRead.IsSuccessful then raise Exception.Create(oRead.ResponseError); oRead.Successful.Spec.Replicas := 5; oWrite := GetOpenAPIClient.replaceAppsV1NamespacedDeploymentScale( 'api', 'production', oRead.Successful); try memoLog.Lines.Add(IntToStr(oWrite.ResponseCode)); finally oWrite.Free; end; finally oRead.Free; end; end;
W całej powierzchni Kubernetes podział jest niemal równy, mniej więcej połowa ciał żądań przychodzi jako typowana klasa, na przykład TsgcOpenAPI_io_k8s_api_autoscaling_v1_Scale_Class, a mniej więcej połowa jako łańcuch znaków, zależnie od tego, czy dokument nazywa schemat.
Jednostka odzwierciedla dokument, na który wskażesz, więc pokrycie to dokładnie ta grupa i wersja, którą wygenerowałeś.
apis/apps/v1 dla Deployments, StatefulSets, DaemonSets i ReplicaSets. apis/batch/v1 dla Jobs i CronJobs. api/v1 dla Pods i ReplicationControllers.
api/v1 dla Services, Endpoints, ConfigMaps i Secrets. apis/networking.k8s.io/v1 dla Ingress i NetworkPolicy. apis/discovery.k8s.io/v1 dla EndpointSlices.
apis/storage.k8s.io/v1, apis/rbac.authorization.k8s.io/v1, apis/policy/v1 i apis/admissionregistration.k8s.io/v1, każdy we własnym dokumencie i każdy we własnej jednostce.
Klaster z zainstalowanymi CRD udostępnia je pod ich własnymi ścieżkami grup, więc indeks pod /openapi/v3 wymienia je obok grup wbudowanych i generują się tak samo.
ObjectMeta, PodSpec, PodStatus, Container, typy warunków, typy list. Sama grupa core daje ich 293.
Opisy pól Kubernetes przechodzą jako komentarze Pascala nad każdą metodą i właściwością, co w dużej mierze tłumaczy długość tych jednostek.
Dwa z nich dotyczą wyłącznie zagregowanego dokumentu Swagger 2.0 i są powodem, dla którego ta strona każe generować osobno dla każdej grupy.
Kubernetes deklaruje namespace i pretty raz na elemencie ścieżki i odwołuje się do nich przez $ref. Wygenerowane z /openapi/v2, te dwa nigdy nie docierają do metody, więc listCoreV1NamespacedPod przychodzi bez argumentu aNamespace, a adres URL zachowuje swój znacznik {namespace}. Wygenerowane z dokumentu /openapi/v3 dla tej samej grupy, argument jest na miejscu. Używaj dokumentów v3.
apis/apiextensions.k8s.io/v1 opisuje JSONSchemaProps.enum jako tablicę schematu, który nie deklaruje żadnego typu, więc generator emituje TArray<>, a kompilator to odrzuca. To dwa wiersze w jednostce. Pomiń tę grupę albo wygeneruj dokument zagregowany, przekazując te 14 operacji także do -x i -p, co usuwa klasę i cała jednostka wtedy się buduje.
602 ścieżki, 1202 metody i jednostka licząca około 197 000 wierszy i 13 MB. Czyta się i generuje w mniej niż sekundę, ale edytor IDE działa wolno przy pliku tej wielkości. Jednostki na grupę to ułamek tego, 42 705 wierszy dla grupy core i 17 061 dla apps.
Większość klastrów używa samopodpisanego CA, więc uzgadnianie TLS zawodzi, dopóki nie powiesz, czemu ufać. Wygenerowany klient udostępnia OnSSLVerifyPeer, OnSSLGetHandler i OnSSLAfterCreateHandler, i to tam instalujesz pakiet CA klastra ze swojego kubeconfig.
watch=true oraz log kontenera z follow=true to długotrwałe odpowiedzi porcjowane. Wygenerowana metoda jest zwykłym żądaniem, które wraca po zakończeniu odpowiedzi, więc żywy watch budujesz na TsgcHTTP1Client, a nie dostajesz go strumieniowo od wygenerowanego klienta.
Są ograniczone czasowo od Kubernetes 1.21. Odczytaj ponownie /var/run/secrets/kubernetes.io/serviceaccount/token z wnętrza klastra albo wywołaj API TokenRequest z zewnątrz i przypisz Authentication.Token.BearerToken jeszcze raz. Klient trzyma to, co ostatnio mu dałeś.
Jak czytnik obsługuje rzeczywiste specyfikacje i co zapisuje w Warnings, kiedy czegoś nie może uwzględnić.
Towarzyszący wpis, który wprowadza wygenerowanego klienta i czytnik, na którym jest zbudowany.
Czytaj wpis →Notatki wydania dla bieżącej wersji, z opcjami generatora i zmianami w czytniku.
Czytaj wpis →