To wielostronicowy widok tej sekcji do wydrukowania. Kliknij aby wydrukować.

Wróć do zwykłego widoku tej strony.

Aktualizacja materiałów źródłowych

Tematy w tej sekcji opisują, jak aktualizować (czyli ponownie wygenerować) materiały źródłowe (ang. reference documentation) Kubernetesa.

Aby zbudować materiały źródłowe, zapoznaj się z następującym przewodnikiem:

1 - 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:

Zanim zaczniesz

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.

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.33, a Ty chcesz wprowadzić swoją zmianę również do gałęzi release-1.32.

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.32. 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.32, kolejnym krokiem jest uruchomienie tych skryptów w gałęzi release-1.32 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.32.

W tym momencie zarówno gałąź master, jak i gałąź release-1.32 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.32 niekoniecznie są takie same jak wygenerowane pliki w gałęzi master. Wygenerowane pliki w gałęzi release-1.32 zawierają elementy API wyłącznie z Kubernetesa 1.32. Wygenerowane pliki w gałęzi master mogą zawierać elementy API, które nie znajdują się w 1.32, ale są w trakcie rozwoju dla 1.33.

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?

2 - Generowanie materiałów źródłowych dla polecenia kubectl

Ta strona pokazuje, jak wygenerować materiały źródłowe polecenia kubectl.

Zanim zaczniesz

Wymagania:

  • Potrzebujesz maszyny z systemem operacyjnym Linux lub macOS.

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

    • Python w wersji 3.7.x+
    • Git - Dokumentacja opisuje, jak zainstalować i rozpocząć pracę z systemem kontroli wersji Git.
    • Golang wersja 1.13+
    • Pip używany do instalacji PyYAML
    • PyYAML w wersji 5.1.2
    • make
    • gcc compiler/linker
    • Docker (Wymagany tylko do odniesień do poleceń kubectl)

  • Twoja zmienna środowiskowa PATH musi zawierać wymagane narzędzia do budowania, takie jak binaria Go i python.

  • Musisz wiedzieć, jak utworzyć pull requesta do repozytorium na GitHubie. Wymaga to utworzenia własnego forka repozytorium. Aby uzyskać więcej informacji, zobacz Praca z lokalnej kopii.

Skonfiguruj lokalne repozytoria

Utwórz lokalną przestrzeń roboczą i ustaw swoje GOPATH:

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Utwórz lokalną kopię następujących repozytoriów:

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs

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

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Zrób klon repozytorium kubernetes/kubernetes jako k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

Usuń pakiet spf13 z $GOPATH/src/k8s.io/kubernetes/vendor/github.com:

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

Repozytorium kubernetes/kubernetes dostarcza kod źródłowy kubectl oraz kustomize.

  • Określ katalog bazowy twojej kopii repozytorium kubernetes/kubernetes. Na przykład, jeśli postępowałeś zgodnie z poprzednim krokiem, aby pobrać repozytorium, twój katalog bazowy to $GOPATH/src/k8s.io/kubernetes. Kolejne kroki odwołują się do twojego katalogu bazowego jako <k8s-base>.

  • Określ katalog bazowy klonu Twojego repozytorium kubernetes/website. Na przykład, jeśli wykonałeś poprzedni krok, aby pobrać repozytorium, Twoim katalogiem bazowym jest $GOPATH/src/github.com/<your-username>/website. Kolejne kroki odnoszą się do Twojego katalogu bazowego jako <web-base>.

  • Określ katalog główny dla Twojej kopii repozytorium kubernetes-sigs/reference-docs. Na przykład, jeśli postępowałeś zgodnie z poprzednim krokiem, aby uzyskać repozytorium, Twoim katalogiem głównym będzie $GOPATH/src/github.com/kubernetes-sigs/reference-docs. Dalsze kroki odnoszą się do Twojego katalogu głównego jako <rdocs-base>.

W swoim lokalnym repozytorium k8s.io/kubernetes przejdź do interesującej Cię gałęzi i upewnij się, że jest ona aktualna. Na przykład, jeśli chcesz wygenerować dokumentację dla Kubernetesa 1.32.0, możesz użyć tych poleceń:

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

Jeśli nie musisz edytować kodu źródłowego kubectl, postępuj zgodnie z instrukcjami dotyczącymi Ustawiania zmiennych kompilacji.

Edytowanie kodu źródłowego kubectl

Materiały źródłowe polecenia kubectl są automatycznie generowana z kodu źródłowego kubectl. Jeśli chcesz zmienić materiały źródłowe, pierwszym krokiem jest zmiana jednego lub więcej komentarzy w kodzie źródłowym kubectl. Wprowadź zmianę w swoim lokalnym repozytorium kubernetes/kubernetes, a następnie zgłoś pull requesta do gałęzi master na github.com/kubernetes/kubernetes.

PR 56673 jest przykładem pull requesta, który poprawia literówkę w kodzie źródłowym kubectl.

Monitoruj swój pull request (PR) i odpowiadaj na komentarze recenzentów. Kontynuuj monitorowanie swojego PR, aż zostanie scalony z docelową gałęzią w repozytorium kubernetes/kubernetes.

Zrób cherry pick do gałęzi wydania

Twoja zmiana znajduje się teraz w głównej gałęzi, która jest używana do rozwoju następnego wydania Kubernetesa. Jeśli chcesz, aby twoja zmiana pojawiła się w wersji dokumentacji Kubernetesa, która została już wydana, musisz zaproponować włączenie twojej zmiany do gałęzi wydania.

Na przykład, załóżmy, że gałąź master jest używana do rozwijania Kubernetes 1.33 i chcesz przenieść swoją zmianę do gałęzi release-1.32. Aby uzyskać instrukcje, jak to zrobić, zobacz Proponowanie Cherry Pick.

Monitoruj swój cherry pick pull request, aż zostanie scalone z gałęzią wydania.

Ustaw zmienne budowania

Przejdź do <rdocs-base>. W swoim wierszu poleceń ustaw następujące zmienne środowiskowe.

  • Ustaw K8S_ROOT na <k8s-base>.
  • Ustaw K8S_WEBROOT na <web-base>.
  • Ustaw K8S_RELEASE na wersję dokumentacji, którą chcesz zbudować. Na przykład, jeśli chcesz zbudować dokumentację dla Kubernetesa 1.32, ustaw K8S_RELEASE na 1.32.

Na przykład:

export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.32

Tworzenie katalogu wersjonowanego

Uruchomienie budowania (ang. build target) createversiondirs tworzy katalog z wersjonowaniem i kopiuje pliki konfiguracyjne kubectl dotyczące materiałów źródłowych do tego katalogu. Nazwa katalogu z wersjonowaniem jest zgodna z wzorcem v<major>_<minor>.

W katalogu <rdocs-base>, uruchom następujący cel budowania:

cd <rdocs-base>
make createversiondirs

Sprawdź tag wydania w k8s.io/kubernetes

W swoim lokalnym repozytorium <k8s-base>, przejdź do gałęzi, która zawiera wersję Kubernetesa, którą chcesz udokumentować. Na przykład, jeśli chcesz wygenerować dokumentację dla Kubernetesa 1.32.0, przejdź do tagu v1.32. Upewnij się, że Twoja lokalna gałąź jest aktualna.

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

Uruchom kod generowania dokumentacji

W lokalnym katalogu <rdocs-base>, uruchom cel budowania (ang. build target) copycli. Komenda działa z uprawnieniami root:

cd <rdocs-base>
make copycli

Polecenie copycli czyści tymczasowy katalog kompilacji, generuje pliki poleceń kubectl i kopiuje zbiorczą stronę HTML materiałów źródłowych poleceń kubectl oraz zasoby do <web-base>.

Zlokalizuj wygenerowane pliki

Zweryfikuj, czy te dwa pliki zostały wygenerowane:

[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Zlokalizuj skopiowane pliki

Zweryfikuj, czy wszystkie wygenerowane pliki zostały skopiowane do Twojego <web-base>:

cd <web-base>
git status

Wynik powinien zawierać zmodyfikowane pliki:

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

Wynik może również zawierać:

static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css

Lokalne testowanie dokumentacji

Zbuduj dokumentację Kubernetes w lokalnym <web-base>.

cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve

Zobacz podgląd lokalny.

Dodaj i zatwierdź zmiany w kubernetes/website

Uruchom git add i git commit, aby zatwierdzić pliki.

Utwórz pull requesta

Utwórz pull requesta do repozytorium kubernetes/website. Monitoruj swój pull request i odpowiadaj na komentarze z przeglądu. Kontynuuj monitorowanie swojego pull requesta aż do momentu jego włączenia do głównej gałęzi kodu.

Kilka minut po włączeniu twojego pull requesta, zaktualizowane tematy materiałów źródłowych będą widoczne w opublikowanej dokumentacji.

Co dalej?

3 - Generowanie materiałów źródłowych dla komponentów i narzedzi Kubernetesa

Ta strona pokazuje, jak zbudować strony materiałów źródłowych komponentów i narzędzi Kubernetesa.

Zanim zaczniesz

Rozpocznij od sekcji wymagania wstępne w przewodniku "szybki start materiałów źródłowych"

Postępuj zgodnie z Szybki start, aby wygenerować strony materiałów źródłowych dla komponentów i narzędzi Kubernetesa.

Co dalej?

4 -

Wymagania:

  • Potrzebujesz maszyny z systemem operacyjnym Linux lub macOS.

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

    • Python w wersji 3.7.x+
    • Git - Dokumentacja opisuje, jak zainstalować i rozpocząć pracę z systemem kontroli wersji Git.
    • Golang wersja 1.13+
    • Pip używany do instalacji PyYAML
    • PyYAML w wersji 5.1.2
    • make
    • gcc compiler/linker
    • Docker (Wymagany tylko do odniesień do poleceń kubectl)

  • Twoja zmienna środowiskowa PATH musi zawierać wymagane narzędzia do budowania, takie jak binaria Go i python.

  • Musisz wiedzieć, jak utworzyć pull requesta do repozytorium na GitHubie. Wymaga to utworzenia własnego forka repozytorium. Aby uzyskać więcej informacji, zobacz Praca z lokalnej kopii.