Wkład w kod źródłowy Kubernetesa

Ta strona pokazuje, jak wnieść wkład do projektu kubernetes/kubernetes. Możesz naprawiać błędy znalezione w dokumentacji API Kubernetesa lub w treściach dla komponentów Kubernetesa, takich jak kubeadm, kube-apiserver i kube-controller-manager.

Jeśli zamiast tego chcesz wygenerować ponownie materiały źródłowe dla API Kubernetesa lub komponentów kube-* z kodu źródłowego, zapoznaj się z następującymi instrukcjami:

• Generowanie materiałów źródłowych dla API Kubernetesa
• Generowanie materiałów źródłowych dla komponentów i narzędzi Kubernetesa

Zanim zaczniesz

• Musisz mieć zainstalowane następujące narzędzia:

  • Git
  • Golang wersja 1.13+
  • Docker
  • etcd
  • make
  • kompilator/linker gcc

• Twoja zmienna środowiskowa GOPATH musi być ustawiona, a lokalizacja etcd musi znajdować się w zmiennej środowiskowej PATH.

• Musisz wiedzieć, jak utworzyć pull requesta do repozytorium GitHub. Zwykle obejmuje to utworzenie forka tego repozytorium. Aby uzyskać więcej informacji, zobacz Tworzenie pull requesta oraz Standardowy proces fork i pull request w GitHub.

Ogólny zarys

Materiały źródłowe dla API Kubernetesa oraz komponentów kube-*, takich jak kube-apiserver, kube-controller-manager, są automatycznie generowane z kodu źródłowego w głównym repozytorium Kubernetes.

Kiedy zauważysz błędy w wygenerowanej dokumentacji, możesz rozważyć stworzenie poprawki, aby naprawić je w projekcie źródłowym.

Sklonuj repozytorium Kubernetesa

Jeśli nie posiadasz jeszcze repozytorium kubernetes/kubernetes, pobierz je teraz:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Określ katalog bazowy swojej kopii repozytorium kubernetes/kubernetes. Na przykład, jeśli wykonywano wcześniejszy krok w celu pobrania tego repozytorium, to twój katalog bazowy to $GOPATH/src/github.com/kubernetes/kubernetes. Pozostałe kroki odnoszą się do twojego katalogu bazowego jako <k8s-base>.

Określ katalog główny swojego klonu repozytorium kubernetes-sigs/reference-docs. Na przykład, jeśli wykonałeś wcześniejszy krok, aby pobrać repozytorium, twój katalog główny to $GOPATH/src/github.com/kubernetes-sigs/reference-docs. Pozostałe kroki odnoszą się do twojego katalogu głównego jako <rdocs-base>.

Edytowanie kodu źródłowego Kubernetesa

Dokumentacja materiałów źródłowych API Kubernetesa jest automatycznie generowana z specyfikacji OpenAPI, która jest tworzona na podstawie kodu źródłowego Kubernetesa. Jeśli chcesz zmienić dokumentację materiałów źródłowych API, pierwszym krokiem jest zmiana w kodzie źródłowym Kubernetesa.

Dokumentacja dla komponentów kube-* jest także generowana z oryginalnego kodu źródłowego. Musisz zmienić kod związany z komponentem, który chcesz naprawić, aby naprawić generowaną dokumentację.

Wprowadź zmiany do kodu źródłowego w repozytorium głównym

Oto przykład edytowania komentarza w kodzie źródłowym Kubernetesa.

W swoim lokalnym repozytorium kubernetes/kubernetes, przełącz się na domyślną gałąź i upewnij się, że jest aktualna:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

Przypuśćmy, że ten plik źródłowy w tej domyślnej gałęzi zawiera literówkę "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

W swoim lokalnym środowisku otwórz plik types.go i zmień "atmost" na "at most".

Zweryfikuj, czy zmieniłeś plik:

git status

Wynik pokazuje, że znajdujesz się na gałęzi głównej, a plik źródłowy types.go został zmodyfikowany:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Zatwierdź swój edytowany plik

Uruchom git add i git commit, aby zatwierdzić zmiany, które do tej pory wprowadziłeś. W kolejnym kroku wykonasz drugi commit. Ważne jest, aby utrzymać zmiany rozdzielone na dwa commity.

Generowanie specyfikacji OpenAPI i powiązanych plików

Przejdź do <k8s-base> i uruchom te skrypty:

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Uruchom git status, aby zobaczyć, co zostało wygenerowane.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

Sprawdź zawartość pliku api/openapi-spec/swagger.json, aby upewnić się, że literówka została poprawiona. Na przykład, możesz uruchomić git diff -a api/openapi-spec/swagger.json. Jest to ważne, ponieważ swagger.json jest wejściem do drugiego etapu procesu generowania materiałów źródłowych.

Uruchom git add i git commit, aby zatwierdzić swoje zmiany. Teraz masz dwa commity: jeden, który zawiera edytowany plik types.go, oraz drugi, który zawiera wygenerowaną specyfikację OpenAPI i powiązane pliki. Zachowaj te dwa commity oddzielnie. To znaczy, nie łącz tych commitów.

Prześlij swoje zmiany jako pull request do gałęzi master w repozytorium kubernetes/kubernetes. Monitoruj swój pull request (PR) i odpowiadaj na uwagi recenzentów w miarę potrzeby. Kontynuuj monitorowanie swojego PR, aż zostanie ono scalone.

PR 57758 jest przykładem pull requesta, który naprawia literówkę w kodzie źródłowym Kubernetesa.

Zrób cherry pick swojego commita do gałęzi wydania

W poprzednim rozdziale edytowałeś plik w głównej gałęzi (master branch) i uruchomiłeś skrypty, aby wygenerować specyfikację OpenAPI oraz powiązane pliki. Następnie przesłałeś swoje zmiany w PR (ang. pull request) do głównej gałęzi repozytorium kubernetes/kubernetes. Teraz załóżmy, że chcesz wprowadzić swoją zmianę także do gałęzi wydania (release branch). Na przykład, załóżmy, że główna gałąź jest używana do opracowywania wersji Kubernetesa 1.34, a Ty chcesz wprowadzić swoją zmianę również do gałęzi release-1.33.

Przypomnij sobie, że twój pull request zawiera dwa commity: jeden dla edycji types.go i jeden dla plików wygenerowanych przez skrypty. Następnym krokiem jest zaproponowanie cherry pick twojego pierwszego commita do gałęzi release-1.33. Chodzi o to, aby cherry pickować commit, który edytował types.go, ale nie commit, który zawiera wyniki uruchomienia skryptów. Instrukcje znajdziesz w Propose a Cherry Pick.

Kiedy masz w toku swój pull request dla zastosowania cherry picka ze swoim jednym commitem do gałęzi release-1.33, kolejnym krokiem jest uruchomienie tych skryptów w gałęzi release-1.33 w swoim lokalnym środowisku.

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Teraz dodaj commit do swojego pull requesta związanego z cherry pickiem, który zawiera niedawno wygenerowaną specyfikację OpenAPI i powiązane pliki. Monitoruj swojego pull requesta, aż zostanie scalony z gałęzią release-1.33.

W tym momencie zarówno gałąź master, jak i gałąź release-1.33 mają zaktualizowany plik types.go oraz zestaw wygenerowanych plików, które odzwierciedlają zmiany wprowadzone do types.go. Należy zauważyć, że wygenerowana specyfikacja OpenAPI i inne wygenerowane pliki w gałęzi release-1.33 niekoniecznie są takie same jak wygenerowane pliki w gałęzi master. Wygenerowane pliki w gałęzi release-1.33 zawierają elementy API wyłącznie z Kubernetesa 1.33. Wygenerowane pliki w gałęzi master mogą zawierać elementy API, które nie znajdują się w 1.33, ale są w trakcie rozwoju dla 1.34.

Generowanie opublikowanych materiałów źródłowych

Poprzednia sekcja pokazała, jak edytować plik źródłowy, a następnie generować kilka plików, w tym api/openapi-spec/swagger.json w repozytorium kubernetes/kubernetes. Plik swagger.json to plik definicji OpenAPI używany do generowania materiałów źródłowych API.

Jesteś teraz gotowy do zapoznania się z przewodnikiem generowania materiałów źródłowych dla API Kubernetesa , aby wygenerować opublikowane materiały źródłowe API Kubernetesa.

Co dalej?

• Generowanie materiałów źródłowych dla API Kubernetesa
• Generowanie materiałów źródłowych dla komponentów i narzędzi Kubernetesa
• Generowanie materiałów źródłowych dla poleceń kubectl