레퍼런스 문서 퀵스타트 가이드
이 문서에서는 update-imported-docs.py 스크립트를 사용하여
쿠버네티스 레퍼런스 문서를 생성하는 방법에 대해 설명한다.
이 스크립트는 특정 쿠버네티스 릴리스 버전에 대해 빌드 설정을 자동으로 수행하고 레퍼런스 문서를 생성한다.
시작하기 전에
필요 사항:
리눅스 또는 macOS 로 구동되는 개발 환경이 필요하다.
다음의 도구들이 설치되어 있어야 한다.
위에 나열된 도구들 (예:
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_RELEASEK8S_ROOTK8S_WEBROOT
스크립트가 정상적으로 실행되려면 인자 2개를 전달해야 한다.
- 환경설정 YAML 파일 (
reference.yml) - 쿠버네티스 릴리스 버전 (예:
1.17)
환경설정 파일은 generate-command 라는 필드를 포함하는데,
이 필드에는
kubernetes-sigs/reference-docs/Makefile 에 있는 Make 타겟들을 활용하여 빌드하는 일련의 과정이 명시되어 있다.
K8S_RELEASE 환경 변수는 릴리스 버전을 결정한다.
update-imported-docs.py 스크립트는 다음의 과정을 수행한다.
- 환경설정 파일에 있는 관련 저장소를 클론한다.
레퍼런스 문서 생성을 위해
기본적으로는
kubernetes-sigs/reference-docs저장소를 클론하도록 되어 있다. - 클론한 안에서, 문서 생성에 필요한 사항을 준비하기 위한 명령어를 실행한 뒤, HTML 파일과 마크다운 파일을 생성한다.
- 생성된 HTML 파일과 마크다운 파일을
환경설정 파일에 명시된 규칙에 따라
<web-base>로 복사한다. 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 팀에 문의하면 된다.
generate-command 는 특정 저장소로부터 문서를 만들기 위한
명령어나 스크립트를 실행하기 위해 사용할 수 있는 선택적 필드이다.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.29/index.html
static/docs/reference/generated/kubernetes-api/v1.29/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.29/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.29/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.29/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.29/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.29/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.29/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.woff2
git add 와 git commit 명령을 실행하여 추가/변경된 파일을 커밋한다.
풀 리퀘스트 만들기
kubernetes/website 저장소에 풀 리퀘스트를 등록한다.
등록한 풀 리퀘스트를 모니터하고, 리뷰 커멘트가 달리면 그에 대해 대응을 한다.
풀 리퀘스트가 머지될 때 까지 계속 모니터한다.
풀 리퀘스트가 머지된 뒤 몇 분이 지나면, 변경사항을 쿠버네티스 문서 홈페이지에서 확인할 수 있다.
다음 내용
수동으로 빌드 저장소를 설정하고 빌드 타겟을 실행하여 개별 레퍼런스 문서를 생성하려면, 다음의 가이드를 참고한다.