레퍼런스 문서 퀵스타트 가이드

이 문서에서는 update-imported-docs.py 스크립트를 사용하여 쿠버네티스 레퍼런스 문서를 생성하는 방법에 대해 설명한다. 이 스크립트는 특정 쿠버네티스 릴리스 버전에 대해 빌드 설정을 자동으로 수행하고 레퍼런스 문서를 생성한다.

시작하기 전에

필요 사항:

• 리눅스 또는 macOS 로 구동되는 개발 환경이 필요하다.

• 다음의 도구들이 설치되어 있어야 한다.

  • Python v3.7.x
  • Git
  • Golang version 1.13+
  • Pip (PyYAML 설치에 필요함)
  • PyYAML v5.1.2
  • make
  • gcc compiler/linker
  • Docker (kubectl 명령어 레퍼런스 업데이트에만 필요함)

• 위에 나열된 도구들 (예: Go 바이너리나 python) 을 사용할 수 있도록 PATH 환경 변수를 알맞게 설정해야 한다.

• GitHub 저장소로 풀 리퀘스트를 생성하는 방법을 알고 있어야 한다. 이를 위해 kubernetes/website 저장소를 개인 계정으로 포크해야 한다. 더 자세한 내용은 로컬 포크에서 작업하기를 참조한다.

website 저장소 클론하기

개인 계정에 있는 포크 버전의 website 저장소가 GitHub에 있는 kubernetes/website 저장소(main 브랜치)의 최신 상태와 일치하는지 확인한 뒤, 개인 계정에 있는 포크 버전의 website 저장소를 로컬 개발 환경으로 클론한다.

mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git

아래에서 사용될 '베이스 디렉터리'를 숙지해야 한다. 예를 들어 위에 안내된 대로 저장소를 클론했다면, 베이스 디렉터리는 github.com/website 가 된다. 이제 이 문서의 나머지 부분에서 <web-base> 라는 구문이 나오면 이 부분에 당신의 베이스 디렉터리를 대입하면 된다.

update-imported-docs 스크립트 개요

update-imported-docs.py 스크립트는 <web-base>/update-imported-docs/ 디렉터리에 존재한다.

이 스크립트는 다음 레퍼런스를 생성한다.

• 구성요소 및 도구 레퍼런스 페이지
• kubectl 명령어 레퍼런스
• 쿠버네티스 API 레퍼런스

update-imported-docs.py 스크립트는 쿠버네티스 소스코드로부터 레퍼런스 문서를 생성한다. 스크립트가 실행되면 개발 머신의 /tmp 디렉터리 아래에 임시 디렉터리를 생성하고, 이 임시 디렉터리 아래에 레퍼런스 문서 생성에 필요한 kubernetes/kubernetes 저장소와 kubernetes-sigs/reference-docs 저장소를 클론하며, GOPATH 환경 변수를 이 임시 디렉터리로 지정한다. 또한 이 스크립트는 다음의 환경 변수를 설정한다.

• K8S_RELEASE
• K8S_ROOT
• K8S_WEBROOT

스크립트가 정상적으로 실행되려면 인자 2개를 전달해야 한다.

• 환경설정 YAML 파일 (reference.yml)
• 쿠버네티스 릴리스 버전 (예: 1.17)

환경설정 파일은 generate-command 라는 필드를 포함하는데, 이 필드에는 kubernetes-sigs/reference-docs/Makefile 에 있는 Make 타겟들을 활용하여 빌드하는 일련의 과정이 명시되어 있다. K8S_RELEASE 환경 변수는 릴리스 버전을 결정한다.

update-imported-docs.py 스크립트는 다음의 과정을 수행한다.

1. 환경설정 파일에 있는 관련 저장소를 클론한다. 레퍼런스 문서 생성을 위해 기본적으로는 kubernetes-sigs/reference-docs 저장소를 클론하도록 되어 있다.
2. 클론한 안에서, 문서 생성에 필요한 사항을 준비하기 위한 명령어를 실행한 뒤, HTML 파일과 마크다운 파일을 생성한다.
3. 생성된 HTML 파일과 마크다운 파일을 환경설정 파일에 명시된 규칙에 따라 <web-base> 로 복사한다.
4. kubectl.md 에 있는 kubectl 명령어 링크들이 kubectl 명령어 레퍼런스 페이지의 올바른 섹션으로 연결되도록 업데이트한다.

생성된 파일이 <web-base> 아래에 복사되었으면, kubernetes/website 저장소로 풀 리퀘스트를 생성 할 수 있다.

환경설정 파일 형식

각 환경설정 파일은 레퍼런스 생성을 위해 필요한 여러 저장소의 정보를 담을 수 있다. 필요한 경우, 환경설정 파일을 직접 수정하여 사용할 수도 있다. 또는, 다른 그룹의 문서를 임포트하기 위해 새로운 환경설정 파일을 작성할 수도 있다. 다음은 환경설정 YAML 파일의 예시이다.

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

이 도구에 의해 처리될 단일 페이지 마크다운 문서는 문서 스타일 가이드의 내용을 만족해야 한다.

reference.yml 환경설정 파일 다루기

<web-base>/update-imported-docs/reference.yml 환경설정 파일을 열어 수정할 수 있다. 레퍼런스 문서 생성을 위해 명령어들이 어떻게 사용되고 있는지 파악하지 못했다면, generate-command 필드의 내용은 수정하지 말아야 한다. 대부분의 경우 reference.yml 을 직접 수정해야 할 필요는 없다. 때때로, 업스트림 소스코드 업데이트 때문에 이 환경설정 파일을 수정해야 할 수도 있다. (예: Golang 버전 의존성, 써드파티 라이브러리 변경 등) 만약 스크립트 사용 시 빌드 문제가 있다면, 쿠버네티스 슬랙의 #sig-docs 채널에서 SIG-Docs 팀에 문의하면 된다.

reference.yml 환경설정 파일에서, files 필드는 src 와 dst 필드를 포함한다. src 필드에는 kubernetes-sigs/reference-docs 디렉터리 아래에 있는 생성된 마크다운 파일의 위치를 명시하고, dst 필드에는 이 파일을 kubernetes/website 디렉터리 아래의 어느 위치로 복사할지를 명시한다. 예시는 다음과 같다.

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

만약 하나의 src 디렉터리에서 하나의 dst 디렉터리로 많은 파일이 복사되어야 한다면, src 필드에 와일드카드를 사용할 수 있다. 이 경우, dst 필드에는 단일 파일의 경로가 아니라 디렉터리의 경로를 명시해야 한다. 예시는 다음과 같다.

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

update-imported-docs 도구 실행하기

다음과 같이 update-imported-docs.py 도구를 실행할 수 있다.

cd <web-base>/update-imported-docs
./update-imported-docs.py <configuration-file.yml> <release-version>

예를 들면 다음과 같다.

./update-imported-docs reference.yml 1.17

링크 업데이트하기

release.yml 환경설정 파일은 상대경로 링크를 수정하는 방법을 포함하고 있다. 임포트하는 파일 안에 있는 상대경로 링크를 수정하려면, gen-absolute-links 필드를 true 로 명시한다. 이에 대한 예시는 release.yml 에서 볼 수 있다.

kubernetes/website 의 변경사항을 커밋하기

다음의 명령을 실행하여, 스크립트에 의해 생성된 뒤 <web-base> 아래에 복사된 파일의 목록을 볼 수 있다.

cd <web-base>
git status

위의 명령을 실행하면 새로 추가된 파일과 수정된 파일의 목록을 볼 수 있다. 아래의 결과 예시는 업스트림 소스코드의 변경사항에 따라 다르게 나타날 수 있다.

생성된 구성요소 도구 레퍼런스

content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

생성된 kubectl 명령어 레퍼런스

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
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/css/font-awesome.min.css

생성된 쿠버네티스 API 레퍼런스 와 파일

static/docs/reference/generated/kubernetes-api/v1.28/index.html
static/docs/reference/generated/kubernetes-api/v1.28/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.28/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.28/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.28/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.28/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.28/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.28/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.28/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.28/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.28/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.28/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.28/fonts/fontawesome-webfont.woff2

git add 와 git commit 명령을 실행하여 추가/변경된 파일을 커밋한다.

풀 리퀘스트 만들기

kubernetes/website 저장소에 풀 리퀘스트를 등록한다. 등록한 풀 리퀘스트를 모니터하고, 리뷰 커멘트가 달리면 그에 대해 대응을 한다. 풀 리퀘스트가 머지될 때 까지 계속 모니터한다.

풀 리퀘스트가 머지된 뒤 몇 분이 지나면, 변경사항을 쿠버네티스 문서 홈페이지에서 확인할 수 있다.

다음 내용

수동으로 빌드 저장소를 설정하고 빌드 타겟을 실행하여 개별 레퍼런스 문서를 생성하려면, 다음의 가이드를 참고한다.

• 쿠버네티스 구성요소와 도구에 대한 레퍼런스 문서 생성하기
• kubectl 명령어에 대한 레퍼런스 문서 생성하기
• 쿠버네티스 API에 대한 레퍼런스 문서 생성하기