diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 7507d6d..817b85f 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -37,6 +37,10 @@ jobs:
- name: Build docs (sphinx, English -> /en/)
run: tox -e docs-en
+ - name: Check external links (non-blocking)
+ run: tox -e linkcheck
+ continue-on-error: true
+
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 20877ee..ef02073 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -88,13 +88,53 @@ reStructuredText conventions
Documentation style guide
==========================
-* **Translated documents**: Convey the meaning of the source (English) text
- accurately while prioritizing natural Korean prose. When a technical term
- first appears, write it as ``한글(English)``.
-* **Proper nouns / project names**: Keep the original spelling for names such
- as OpenStack, Kubernetes, Nova, and Neutron.
-* **Commands / code**: Specify the appropriate language for ``code-block``
+Korean prose conventions
+------------------------
+
+Korean is the source language of this repository, so these rules keep the
+pages consistent and keep the gettext catalog stable.
+
+* **Sentence endings**: use the polite ``합니다`` style
+ ("Neutron 은 ... 서비스입니다"), not the plain ``한다`` style. The only
+ exception is ``doc/source/glossary.rst``, where dictionary-style ``한다``
+ definitions are used throughout.
+* **Spacing around particles**: put a space between a Latin word and the
+ Korean particle that follows it — ``Neutron 은``, ``Pod 가``, ``VM 의``,
+ ``openstack-helm 으로``. Particles after a bare number stay attached
+ (``폭이 2로``), and particles after a closing parenthesis stay attached
+ (``제어 평면(control plane)이라고``).
+* **First use of a term**: write it as ``한글(English, ABBR)`` — for example
+ ``특별 관심 그룹(Special Interest Group, SIG)`` or
+ ``역할 기반 접근 제어(role-based access control, RBAC)``. Use the
+ abbreviation alone afterwards.
+* **Proper nouns / project names**: keep the original spelling for names such
+ as OpenStack, Kubernetes, Nova, and Neutron. Write the project name as
+ ``openstack-helm`` in lower case, and spell ``Kubernetes`` out rather than
+ abbreviating it to ``K8s``.
+* **Preferred terms**: ``Pod`` (not 파드), ``VM`` (not 가상 머신 after the
+ first use), ``Octavia`` (not 옥타비아). When in doubt, follow the headword
+ used in ``doc/source/glossary.rst`` and link the first mention with
+ ``:term:``.
+
+Markup and links
+----------------
+
+* **Commands / code**: specify the appropriate language for ``code-block``
directives (``console``, ``yaml``, ``bash``, etc.).
+* Use inline literals (``` ``like this`` ```) only for code, paths, commands
+ and identifiers. To emphasize a phrase, use ``**bold**`` instead.
+* Prefer ``` ``literal`` ``` over the ``:code:`` role for inline code.
+* Write ordered lists with ``#.`` so the numbering stays automatic.
+* Point external links at their final URL, not at one that redirects
+ (``https://docs.openstack.org/magnum/latest/``, not
+ ``https://docs.openstack.org/magnum/``). ``tox -e linkcheck`` reports both
+ broken links and redirects.
+
+Translated documents
+--------------------
+
+Convey the meaning of the source text accurately while prioritizing natural
+prose, and record the source document and its version.
For detailed rST/Sphinx conventions, see the ``doc/source/documentation/``
section.
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 2ed74c0..780d16d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -17,7 +17,6 @@
# -- 일반 설정 ---------------------------------------------------------------
extensions = [
- 'sphinx.ext.intersphinx',
'sphinx.ext.todo',
]
@@ -49,9 +48,19 @@
html_title = 'OpenStack & Kubernetes 한글 문서화 프로젝트'
-# -- intersphinx 설정 --------------------------------------------------------
-# 외부 공식 문서로의 교차 참조. 네트워크가 없는 환경에서도 빌드가
-# 실패하지 않도록 타임아웃을 짧게 둡니다.
+# -- 링크 검사 (linkcheck) ---------------------------------------------------
+# ``tox -e linkcheck`` 로 외부 링크의 유효성을 확인합니다.
+# 리다이렉트는 문서에서 최종 URL 로 바로 적는 것을 원칙으로 합니다.
-intersphinx_mapping = {}
-intersphinx_timeout = 5
+# 봇 접근을 차단해 403 을 돌려주지만 사람은 정상적으로 볼 수 있는 링크.
+linkcheck_ignore = [
+ r'https://www\.netapp\.com/learn/.*',
+]
+
+# 링크 검사 시 동시 요청 수와 재시도 (CI 에서의 산발적 실패를 줄입니다).
+linkcheck_workers = 5
+linkcheck_timeout = 15
+linkcheck_retries = 2
+
+# 외부 공식 문서로의 교차 참조가 필요해지면 ``sphinx.ext.intersphinx`` 를
+# extensions 에 추가하고 여기에 intersphinx_mapping 을 정의하세요.
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 0491fd8..30b0154 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -1,6 +1,6 @@
-======
+====
기여
-======
+====
이 프로젝트에 기여하는 방법을 안내합니다. 기여는 크게 문서화와 번역·국제화로
나뉘며, 각각의 도구와 관례는 하위 문서에서 다룹니다.
diff --git a/doc/source/documentation/kubernetes-doc-conventions.rst b/doc/source/documentation/kubernetes-doc-conventions.rst
index 364a097..eb5c66a 100644
--- a/doc/source/documentation/kubernetes-doc-conventions.rst
+++ b/doc/source/documentation/kubernetes-doc-conventions.rst
@@ -1,6 +1,6 @@
-=========================
+====================
Kubernetes 문서 관례
-=========================
+====================
Kubernetes 공식 문서는 OpenStack 과 달리 `Hugo `_ 와
Markdown 기반입니다. 본 프로젝트는 rST/Sphinx 로 작성하지만, Kubernetes
@@ -15,7 +15,7 @@ Markdown 기반입니다. 본 프로젝트는 rST/Sphinx 로 작성하지만, Ku
핵심 출처
=========
-* Kubernetes Documentation (website) — https://kubernetes.io/docs/
+* Kubernetes Documentation (website) — https://kubernetes.io/docs/home/
* Contribute to Kubernetes docs —
https://kubernetes.io/docs/contribute/
diff --git a/doc/source/documentation/openstack-doc-conventions.rst b/doc/source/documentation/openstack-doc-conventions.rst
index a4a23df..ff96845 100644
--- a/doc/source/documentation/openstack-doc-conventions.rst
+++ b/doc/source/documentation/openstack-doc-conventions.rst
@@ -1,6 +1,6 @@
-========================
+===================
OpenStack 문서 관례
-========================
+===================
OpenStack 은 문서 기여에 대한 체계적인 가이드를 제공합니다. 본 프로젝트는
이 관례를 학습 모델로 삼습니다.
diff --git a/doc/source/documentation/review-guidelines.rst b/doc/source/documentation/review-guidelines.rst
index 99b86a3..f03078a 100644
--- a/doc/source/documentation/review-guidelines.rst
+++ b/doc/source/documentation/review-guidelines.rst
@@ -16,9 +16,15 @@
* [ ] 로컬에서 ``tox -e docs`` 빌드가 통과하는가
* [ ] ``tox -e pep8`` (doc8) 린트가 통과하는가
+* [ ] ``tox -e linkcheck`` 에서 깨진 링크·리다이렉트가 없는가
* [ ] 새 문서를 상위 ``toctree`` 에 등록했는가
+* [ ] 새 문서로 들어오는 ``:doc:`` 링크를 관련 문서에 하나 이상 넣었는가
* [ ] 교차 참조(``:doc:``)와 외부 링크가 유효한가
-* [ ] 용어를 :doc:`../glossary` 와 일관되게 사용했는가
+* [ ] 문장을 합니다체로 썼는가 (용어집은 예외)
+* [ ] 로마자 뒤 조사를 띄어 썼는가 (``Neutron 은``, ``Pod 가``)
+* [ ] 용어를 :doc:`../glossary` 와 일관되게 쓰고, 첫 등장에 ``:term:`` 을
+ 걸었는가
+* [ ] 용어 첫 등장을 ``한글(English, ABBR)`` 형식으로 적었는가
* [ ] 번역 문서라면 원문 출처와 버전을 명시했는가
@@ -30,6 +36,7 @@
* **명확성** — 입문자가 이해할 수 있는가
* **구조** — 적절한 섹션/제목 레벨을 사용했는가
* **일관성** — 용어·표기·스타일이 프로젝트 관례를 따르는가
+ (``CONTRIBUTING.rst`` 의 Documentation style guide 참고)
* **빌드** — GitHub Actions 문서 빌드가 통과했는가
diff --git a/doc/source/documentation/rst-sphinx-basics.rst b/doc/source/documentation/rst-sphinx-basics.rst
index c4533d0..5d5291b 100644
--- a/doc/source/documentation/rst-sphinx-basics.rst
+++ b/doc/source/documentation/rst-sphinx-basics.rst
@@ -1,10 +1,10 @@
-====================
+=================
rST / Sphinx 기초
-====================
+=================
-본 프로젝트는 reStructuredText(rST)와 `Sphinx `_
-로 문서를 작성합니다. 이 문서는 처음 기여하는 분을 위한 최소한의 기초를
-정리합니다.
+본 프로젝트는 reStructuredText(rST)와
+`Sphinx `_ 로 문서를 작성합니다.
+이 문서는 처음 기여하는 분을 위한 최소한의 기초를 정리합니다.
왜 rST/Sphinx 인가
diff --git a/doc/source/foundations/bridging-concepts.rst b/doc/source/foundations/bridging-concepts.rst
index 653bc3c..c2dfcc0 100644
--- a/doc/source/foundations/bridging-concepts.rst
+++ b/doc/source/foundations/bridging-concepts.rst
@@ -1,6 +1,6 @@
-==========================================
+======================================
OpenStack ↔ Kubernetes 연동 인터페이스
-==========================================
+======================================
가상화 기초·OpenStack·Kubernetes 세 레이어를 이해했다면, 다음은 두 기술을
실제로 잇는 표준 인터페이스입니다. 각 개념의 상세는 통합 패턴·네트워킹·
@@ -15,7 +15,7 @@ OpenStack ↔ Kubernetes 연동 인터페이스
연동 표준 인터페이스
-========================
+====================
Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점입니다. 각
인터페이스가 OpenStack 의 무엇과 이어지는지가 핵심입니다.
@@ -32,7 +32,8 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점
- :doc:`../openstack-on-kubernetes/cni-and-neutron`
* - CSI
- 퍼시스턴트 스토리지 ↔ Cinder
- - :doc:`../kubernetes-on-openstack/cinder-csi`
+ - :doc:`kubernetes-csi` (개념),
+ :doc:`../kubernetes-on-openstack/cinder-csi` (연동)
* - CCM
- LoadBalancer·노드 수명주기 ↔ OpenStack
- :doc:`../kubernetes-on-openstack/cloud-provider-openstack`
@@ -50,7 +51,7 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점
.. _bridging-concepts-provisioning:
배포·프로비저닝
-========================
+===============
두 기술을 결합하는 방법으로, 방향에 따라 나뉩니다.
@@ -62,22 +63,22 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점
- 한 줄 정의
- 상세
* - openstack-helm
- - OpenStack 을 K8s 에 배포 (OpenStack → K8s)
+ - OpenStack 을 Kubernetes 에 배포 (OpenStack → Kubernetes)
- :doc:`../openstack-on-kubernetes/openstack-helm`
* - Magnum
- - OpenStack 이 K8s 클러스터를 생성 (K8s → OpenStack)
+ - OpenStack 이 Kubernetes 클러스터를 생성 (Kubernetes → OpenStack)
- :doc:`../kubernetes-on-openstack/magnum`
* - Cluster API (CAPO)
- - 선언적으로 K8s 클러스터 프로비저닝 (K8s → OpenStack)
+ - 선언적으로 Kubernetes 클러스터 프로비저닝 (Kubernetes → OpenStack)
- :doc:`../kubernetes-on-openstack/cluster-api`
.. _bridging-concepts-baremetal:
베어메탈 (물리 서버)
-========================
+====================
-멀티노드 운영은 결국 물리 서버로 내려갑니다. 여기서 K8s 의 Metal3 와
+멀티노드 운영은 결국 물리 서버로 내려갑니다. 여기서 Kubernetes 의 Metal3 와
OpenStack 의 Ironic 이 만나는데, Metal3(CRD)가 내부적으로 Ironic 을 호출하는
구조라 두 스택의 베어메탈 관리가 한 지점으로 수렴합니다.
@@ -92,15 +93,16 @@ OpenStack 의 Ironic 이 만나는데, Metal3(CRD)가 내부적으로 Ironic 을
- OpenStack 의 베어메탈 프로비저닝 서비스
- 전용 문서 예정
* - Metal3
- - K8s(CRD)로 베어메탈 관리 — 내부적으로 Ironic 사용
+ - Kubernetes(CRD)로 베어메탈 관리 — 내부적으로 Ironic 사용
- 전용 문서 예정
공용 스토리지
-========================
+=============
-두 스택이 같은 스토리지 백엔드(Ceph)를 공유하는 수렴 지점입니다. K8s 측은
-Rook 오퍼레이터로, OpenStack 측은 Cinder·Glance 등이 같은 Ceph 를 바라봅니다.
+두 스택이 같은 스토리지 백엔드(:term:`Ceph`)를 공유하는 수렴 지점입니다.
+Kubernetes 측은 :term:`Rook` 오퍼레이터로, OpenStack 측은 Cinder·Glance 등이
+같은 Ceph 를 바라봅니다.
.. list-table::
:header-rows: 1
@@ -110,7 +112,7 @@ Rook 오퍼레이터로, OpenStack 측은 Cinder·Glance 등이 같은 Ceph 를
- 한 줄 정의
- 상세
* - Ceph / Rook
- - OpenStack·K8s 공용 스토리지 백엔드 (Rook = K8s 오퍼레이터)
+ - OpenStack·Kubernetes 공용 스토리지 백엔드 (Rook = Kubernetes 오퍼레이터)
- :doc:`../storage/ceph`
.. todo::
diff --git a/doc/source/foundations/helm.rst b/doc/source/foundations/helm.rst
index e2acf7d..ebc1cf7 100644
--- a/doc/source/foundations/helm.rst
+++ b/doc/source/foundations/helm.rst
@@ -1,17 +1,17 @@
-===============
+==============
Helm 핵심 개념
-===============
+==============
-OpenStack 을 Kubernetes 위에 올릴 때 반복해서 등장하는 전제 도구입니다. Helm
-은 K8s 애플리케이션의 패키징·배포를 선언적으로 다룹니다. 도구 자체의 상세는
-공식 문서로 링크하고, 여기서는 "이 개념이 OpenStack·K8s 결합에서 무엇에
-쓰이는가"에 초점을 둡니다.
+OpenStack 을 Kubernetes 위에 올릴 때 반복해서 등장하는 전제 도구입니다.
+Helm 은 Kubernetes 애플리케이션의 패키징·배포를 선언적으로 다룹니다. 도구
+자체의 상세는 공식 문서로 링크하고, 여기서는 "이 개념이 OpenStack·Kubernetes
+결합에서 무엇에 쓰이는가"에 초점을 둡니다.
.. note::
기여자 작업용 골격입니다. 도구 사용법을 재설명하지 말고, 각 개념이
- OpenStack·K8s 결합의 어디에 쓰이는지(왜 알아야 하는지)를 한 줄로 유지하세요.
- 상세는 공식 문서와 해당 섹션으로.
+ OpenStack·Kubernetes 결합의 어디에 쓰이는지(왜 알아야 하는지)를 한 줄로
+ 유지하세요. 상세는 공식 문서와 해당 섹션으로.
핵심 구성요소
@@ -19,7 +19,7 @@ OpenStack 을 Kubernetes 위에 올릴 때 반복해서 등장하는 전제 도
.. todo::
- * Chart / Values / Release → K8s 애플리케이션을 패키징·배포하는 단위
+ * Chart / Values / Release → Kubernetes 애플리케이션을 패키징·배포하는 단위
* Values 오버라이드 → 환경별 설정 주입 (openstack-helm 배포의 핵심 조작점)
@@ -28,8 +28,8 @@ OpenStack 을 Kubernetes 위에 올릴 때 반복해서 등장하는 전제 도
.. todo::
- * openstack-helm 의 기반 → OpenStack 을 K8s 에 올리는 여러 방식의 전제 도구
- (:doc:`../openstack-on-kubernetes/openstack-helm`)
+ * openstack-helm 의 기반 → OpenStack 을 Kubernetes 에 올리는 여러 방식의
+ 전제 도구 (:doc:`../openstack-on-kubernetes/openstack-helm`)
* Rook 등 오퍼레이터 설치에도 Helm Chart 사용 (:doc:`../storage/ceph`)
diff --git a/doc/source/foundations/index.rst b/doc/source/foundations/index.rst
index fa20574..a94014f 100644
--- a/doc/source/foundations/index.rst
+++ b/doc/source/foundations/index.rst
@@ -1,6 +1,6 @@
-==========
+=========
기초 개념
-==========
+=========
실습에 앞서 이해해 두면 좋은 개념 레이어를 정리합니다. 가상화 기초에서
시작해 OpenStack 핵심 개념과 그 네트워킹·스토리지 서비스, Kubernetes 핵심
diff --git a/doc/source/foundations/kubernetes-csi.rst b/doc/source/foundations/kubernetes-csi.rst
index 0176cfb..bf1f03c 100644
--- a/doc/source/foundations/kubernetes-csi.rst
+++ b/doc/source/foundations/kubernetes-csi.rst
@@ -2,52 +2,56 @@
CSI 기본 개념
=============
+:term:`CSI` 는 컨테이너 오케스트레이터에 외부 스토리지를 연결하기 위한 표준
+인터페이스입니다. 이 문서는 인터페이스 자체의 개념을 다루며, OpenStack 의
+블록 스토리지를 실제로 연결하는 방법은
+:doc:`../kubernetes-on-openstack/cinder-csi` 에서 다룹니다.
+
CSI 도입 배경
=============
-쿠버네티스는 컨테이너화된 애플리케이션을 확장, 관리할 수 있지만 데이터를
-영속적으로 관리하는 측면에서 한계가 존재한다.
+Kubernetes 는 컨테이너화된 애플리케이션을 확장하고 관리할 수 있지만, 데이터를
+영속적으로 관리하는 측면에서는 한계가 있습니다.
-Kubernetes의 Pod를 재시작할 때 파드 내부에 축적되어 있는 데이터 정보는
-유실된다.
-이러한 문제를 해결하기 위해 PV를 HostPath로 사용하여 노드의 로컬
-디스크로 저장할 수 있으나, 파드가 다른 노드로 재배포될 경우 데이터를 공유하여
-활용할 수 없다.
+:term:`Pod` 를 재시작하면 Pod 내부에 쌓여 있던 데이터는 유실됩니다.
+이를 피하려고 :term:`PV / PVC` 의 PV 를 HostPath 로 잡아 노드의 로컬 디스크에
+저장할 수도 있지만, Pod 가 다른 노드로 재배포되면 그 데이터를 다시 사용할 수
+없습니다.
-쿠버네티스는 이러한 문제를 해결하기 위해 컨테이너 간 스토리지를 이용할 수
-있는 인터페이스를 구현했다.
-즉, 파드가 어느 노드에 재배포가 되더라도 동일한
-데이터를 참조하여 활용할 수 있게 된다.
+Kubernetes 는 이 문제를 해결하기 위해 외부 스토리지를 연결하는 표준
+인터페이스를 도입했습니다. 이 인터페이스를 사용하면 Pod 가 어느 노드에
+재배포되더라도 같은 데이터를 계속 참조할 수 있습니다.
CSI 개념
========
`Kubernetes CSI 공식 개발 문서 `_ 에
-의하면 CSI는 컨테이너화된 워크로드에 임의의 블록 및 파일 스토리지 시스템을
-노출하기 위한 표준을 의미한다.
+따르면 CSI 는 컨테이너화된 워크로드에 임의의 블록 및 파일 스토리지 시스템을
+노출하기 위한 표준입니다.
-이름에서부터 인터페이스가 나와 있으므로, 클라이언트는 형식화된 포맷으로
-요청을 수행하게 되며, 구현부에 따라 서로 다른 기능을 실행시킬 수 있다.
-즉,벤더는 이 표준을 구현한 드라이버(플러그인)를 제작하여 배포하면 되고,
-관리자는 Kubernetes 릴리스와 무관하게 독립적으로 배포, 업데이트하여
-원하는 벤더의 스토리지를 활용할 수 있게 된다.
+이름 그대로 인터페이스이므로, 클라이언트는 정해진 형식으로 요청을 보내고
+구현체에 따라 서로 다른 동작이 실행됩니다. 즉 벤더는 이 표준을 구현한
+드라이버(플러그인)를 만들어 배포하고, 관리자는 Kubernetes 릴리스와 무관하게
+드라이버를 독립적으로 배포·업데이트하여 원하는 벤더의 스토리지를 사용할 수
+있습니다.
-파드가 어느 노드로 재배포되더라도 CSI 드라이버가 해당 노드에 외부 스토리지
-볼륨을 다시 부착(attach)해주므로, 동일한 데이터를 계속 참조할 수 있다.
+Pod 가 어느 노드로 재배포되더라도 CSI 드라이버가 해당 노드에 외부 스토리지
+볼륨을 다시 부착(attach)하므로, 같은 데이터를 계속 참조할 수 있습니다.
세부 구조
=========
-CSI는 3개의 컴포넌트가 필요하다.
+CSI 드라이버는 역할이 다른 두 종류의 플러그인으로 배포되고, 노드 쪽에서는
+kubelet 이 이 플러그인을 호출합니다.
-* Controller side: kube-apiserver를 통해 볼륨 생성, 삭제, 부착과
- 같은 제어를 담당한다.
- 보통 Deployment 나 StatefulSet으로 운영된다.
-* Node side: 실제 마운트(mount)와 마운트 해제(unmount) 혹은 kubelet 연동을
- 수행한다.
- DaemonSet으로 노드별로 배포된다.
-* Kubelet: kubelet을 통해 UNIX 도메인 소켓(socket)을 통해 CSI 노드의 서비스를
- 수행한다.
+* **컨트롤러 플러그인(controller plugin)** — kube-apiserver 를 통해 볼륨
+ 생성·삭제·부착 같은 제어를 담당합니다. 보통 :term:`Deployment` 나
+ :term:`StatefulSet` 으로 운영됩니다.
+* **노드 플러그인(node plugin)** — 실제 마운트(mount)와 마운트
+ 해제(unmount)를 수행합니다. 모든 노드에서 동작해야 하므로
+ :term:`DaemonSet` 으로 배포됩니다.
+* **kubelet** — CSI 컴포넌트는 아니지만, 각 노드에서 UNIX 도메인
+ 소켓(socket)을 통해 노드 플러그인을 호출하는 주체입니다.
.. code-block:: console
@@ -58,17 +62,21 @@ CSI는 3개의 컴포넌트가 필요하다.
작동 원리
=========
-1. 사용자가 PVC를 생성하면 Kubernetes가 StorageClass를 보고 어떤 CSI
- 드라이버를 쓸지 결정한다.
-2. Controller 쪽 CSI가 스토리지 시스템에 볼륨 생성을 요청해 실제 볼륨을 만든다.
-3. Kubernetes는 만들어진 결과를 PV로 표현하고, PVC와 바인딩한다.
-4. Pod가 스케줄되면 필요한 경우 controller가 노드에 attach를 수행한다.
-5. 노드에서는 CSI node plugin이 파일시스템을 준비하고 Pod 경로에 마운트한다.
+#. 사용자가 PVC 를 생성하면 Kubernetes 가 :term:`StorageClass` 를 보고 어떤
+ CSI 드라이버를 쓸지 결정합니다.
+#. 컨트롤러 플러그인이 스토리지 시스템에 볼륨 생성을 요청해 실제 볼륨을
+ 만듭니다.
+#. Kubernetes 는 만들어진 결과를 PV 로 표현하고 PVC 와 바인딩합니다.
+#. Pod 가 스케줄되면 필요한 경우 컨트롤러 플러그인이 노드에 볼륨을
+ 부착합니다.
+#. 노드 플러그인이 파일시스템을 준비하고 Pod 경로에 마운트합니다.
더 읽을거리
===========
+* Kubernetes CSI: https://kubernetes-csi.github.io/docs/
* CSI 동작 원리:
https://www.netapp.com/learn/cvo-blg-kubernetes-csi-basics-of-csi-volumes-and-how-to-build-a-csi-driver/
-* Kubernetes CSI: https://kubernetes-csi.github.io/docs/
+* :doc:`../kubernetes-on-openstack/cinder-csi` — Cinder 볼륨을 CSI 로
+ 소비하는 관점
diff --git a/doc/source/foundations/kubernetes-fundamentals.rst b/doc/source/foundations/kubernetes-fundamentals.rst
index b29c0f7..a7eb35a 100644
--- a/doc/source/foundations/kubernetes-fundamentals.rst
+++ b/doc/source/foundations/kubernetes-fundamentals.rst
@@ -1,17 +1,17 @@
-=====================
+====================
Kubernetes 핵심 개념
-=====================
+====================
-통합 패턴(:doc:`../integration-patterns`)에서 OpenStack 을 K8s 위에 올릴 때, 각
-OpenStack 컴포넌트가 어떤 K8s 리소스로 동작하는지를 미리 짚습니다. K8s 개념
-자체의 상세는 공식 문서로 링크하고, 여기서는 "이 리소스가 OpenStack 의 무엇에
-쓰이는가"에 초점을 둡니다.
+통합 패턴(:doc:`../integration-patterns`)에서 OpenStack 을 Kubernetes 위에
+올릴 때, 각 OpenStack 컴포넌트가 어떤 Kubernetes 리소스로 동작하는지를 미리
+짚습니다. Kubernetes 개념 자체의 상세는 공식 문서로 링크하고, 여기서는
+"이 리소스가 OpenStack 의 무엇에 쓰이는가"에 초점을 둡니다.
.. note::
- 기여자 작업용 골격입니다. K8s 개념을 재설명하지 말고, 각 리소스가 OpenStack
- 컴포넌트에 어떻게 대응되는지(왜 알아야 하는지)를 한 줄로 유지하세요. 상세는
- 공식 문서와 통합 패턴 섹션으로.
+ 기여자 작업용 골격입니다. Kubernetes 개념을 재설명하지 말고, 각 리소스가
+ OpenStack 컴포넌트에 어떻게 대응되는지(왜 알아야 하는지)를 한 줄로
+ 유지하세요. 상세는 공식 문서와 통합 패턴 섹션으로.
Workloads
@@ -50,24 +50,24 @@ Workloads
선언적 관리와 CRD
=================
-Kubernetes에서는 원하는 상태(desired state)를 리소스에 선언하고,
+Kubernetes 에서는 원하는 상태(desired state)를 리소스에 선언하고,
컨트롤러(Controller)가 현재 상태(current state)와 비교하여 두 상태가
일치하도록 지속적으로 조정(reconciliation)합니다.
-OpenStack과 Kubernetes를 연동하는 일부 프로젝트에서는 이러한 선언적 관리
-방식을 사용하여 OpenStack API로 관리되는 인프라의 원하는 상태를 Kubernetes
+OpenStack 과 Kubernetes 를 연동하는 일부 프로젝트에서는 이러한 선언적 관리
+방식을 사용하여 OpenStack API 로 관리되는 인프라의 원하는 상태를 Kubernetes
리소스로 표현합니다.
이때 사용자 정의 리소스 정의(CustomResourceDefinition, :term:`CRD`)는
Kubernetes 기본 리소스로 표현하기 어려운 OpenStack 연동 대상을 새로운
리소스 종류로 정의하는 데 사용됩니다.
-사용자는 CRD를 통해 추가된 사용자 정의 리소스(Custom Resource)에 원하는
+사용자는 CRD 를 통해 추가된 사용자 정의 리소스(Custom Resource)에 원하는
상태를 선언합니다.
이 연동 구조에서 컨트롤러나 :term:`오퍼레이터(Operator) ` 는
-사용자 정의 리소스를 감시하고, OpenStack API를 호출하여 선언된 상태가 실제
+사용자 정의 리소스를 감시하고, OpenStack API 를 호출하여 선언된 상태가 실제
인프라에 반영되도록 조정합니다.
-CRD 자체가 OpenStack API를 호출하는 것이 아니라, 해당 리소스의 수명주기
+CRD 자체가 OpenStack API 를 호출하는 것이 아니라, 해당 리소스의 수명주기
관리 로직을 가진 컨트롤러나 오퍼레이터가 상태 조정을 수행합니다.
.. code-block:: text
@@ -83,17 +83,17 @@ CRD 자체가 OpenStack API를 호출하는 것이 아니라, 해당 리소스
이 패턴을 OpenStack 연동에 적용한 대표 사례는 다음과 같습니다.
전체 연동 구조에서는 다음 영역에 해당합니다.
-* **Magnum과 Cluster API(CAPI)·Cluster API Provider OpenStack(CAPO)** —
+* **Magnum 과 Cluster API(CAPI)·Cluster API Provider OpenStack(CAPO)** —
:ref:`배포·프로비저닝 `
-* **Metal3와 Ironic** —
+* **Metal3 와 Ironic** —
:ref:`베어메탈 (물리 서버) `
Magnum CAPI 드라이버와 CAPO
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Magnum의 CAPI 기반 드라이버는 CAPI와 CAPO의 사용자 정의 리소스를 생성하고,
-CAPO 컨트롤러는 OpenStack API를 호출하여 Nova·Neutron 등의
+Magnum 의 CAPI 기반 드라이버는 CAPI 와 CAPO 의 사용자 정의 리소스를 생성하고,
+CAPO 컨트롤러는 OpenStack API 를 호출하여 Nova·Neutron 등의
인프라를 조정합니다.
.. code-block:: text
@@ -104,8 +104,8 @@ CAPO 컨트롤러는 OpenStack API를 호출하여 Nova·Neutron 등의
-> OpenStack API(Nova·Neutron 등)
-> Kubernetes 클러스터 인프라
-이 대응 관계를 알면 Magnum API로 받은 클러스터 생성 요청이 CAPI 리소스로
-변환되는 단계와 CAPO가 실제 OpenStack 인프라를 조정하는 역할을 구분할 수
+이 대응 관계를 알면 Magnum API 로 받은 클러스터 생성 요청이 CAPI 리소스로
+변환되는 단계와 CAPO 가 실제 OpenStack 인프라를 조정하는 역할을 구분할 수
있습니다.
자세한 내용은 :doc:`../kubernetes-on-openstack/magnum` 과
@@ -114,22 +114,22 @@ CAPO 컨트롤러는 OpenStack API를 호출하여 Nova·Neutron 등의
.. _kubernetes-fundamentals-metal3-ironic:
-Metal3와 Ironic
+Metal3 와 Ironic
~~~~~~~~~~~~~~~~
-:term:`Metal3` 는 ``BareMetalHost`` 리소스를 CRD로 제공합니다.
+:term:`Metal3` 는 ``BareMetalHost`` 리소스를 CRD 로 제공합니다.
``BareMetalHost`` 는 OpenStack :term:`Ironic` 이 관리하는 물리 서버의
원하는 상태를 표현합니다.
-Metal3의 Bare Metal Operator(BMO)는 Kubernetes 컨트롤러로서
-``BareMetalHost`` 를 감시하고 Ironic API를 호출하여 물리 서버의 검사와
+Metal3 의 Bare Metal Operator(BMO)는 Kubernetes 컨트롤러로서
+``BareMetalHost`` 를 감시하고 Ironic API 를 호출하여 물리 서버의 검사와
프로비저닝을 조정합니다.
.. code-block:: text
BareMetalHost -> BMO -> Ironic API -> 물리 서버
-이 대응 관계를 알면 Kubernetes에 선언된 물리 서버의 상태와 Ironic이
+이 대응 관계를 알면 Kubernetes 에 선언된 물리 서버의 상태와 Ironic 이
수행하는 실제 하드웨어 작업의 경계를 구분할 수 있습니다.
더 읽을거리
diff --git a/doc/source/foundations/openstack-fundamentals.rst b/doc/source/foundations/openstack-fundamentals.rst
index 7fb528b..8e9d6ef 100644
--- a/doc/source/foundations/openstack-fundamentals.rst
+++ b/doc/source/foundations/openstack-fundamentals.rst
@@ -1,12 +1,12 @@
-====================
+===================
OpenStack 주요 특징
-====================
+===================
주요 서비스
-=============
+===========
-OpenStack의 주요 서비스는 다음의 표와 같다.
+OpenStack 의 주요 서비스는 다음의 표와 같습니다.
.. list-table::
:header-rows: 1
@@ -16,7 +16,7 @@ OpenStack의 주요 서비스는 다음의 표와 같다.
* - 서비스
- 역할
* - **Keystone(키스톤)** — 인증 서비스
- - OpenStack의 모든 서비스 중앙 인증, 사용자 자격 증명, 역할 기반
+ - OpenStack 의 모든 서비스 중앙 인증, 사용자 자격 증명, 역할 기반
접근 제어(role-based access control, RBAC) 및
서비스 카탈로그(service catalog) 관리 담당
* - **Nova(노바)** — 컴퓨팅 서비스
@@ -35,42 +35,42 @@ OpenStack의 주요 서비스는 다음의 표와 같다.
연결, 스냅샷 관리 담당
* - **Swift(스위프트)** — 오브젝트 스토리지 서비스
- 이미지, 백업 등 대규모 비정형 데이터를 오브젝트 단위로 분산 저장하고
- REST API로 제공
+ REST API 로 제공
* - **Glance(글랜스)** — 이미지 서비스
- - VM에 사용될 디스크 이미지 및 메타데이터(metadata) 등록, 검색,
+ - VM 에 사용될 디스크 이미지 및 메타데이터(metadata) 등록, 검색,
카탈로그화 및 배포 담당
* - **Horizon(호라이즌)** — 웹 대시보드
- 사용자와 관리자가 클라우드 자원을 시각적으로 관리할 수 있는
그래픽 사용자 인터페이스(graphical user interface, GUI) 대시보드
-OpenStack의 서비스 구조와 컨테이너 배포
-=======================================
+OpenStack 의 서비스 구조와 컨테이너 배포
+========================================
-앞에서 소개한 Nova, Neutron, Cinder와 같은 OpenStack 서비스는 각각
-단일 프로세스로 실행되지 않는다.
+앞에서 소개한 Nova, Neutron, Cinder 와 같은 OpenStack 서비스는 각각
+단일 프로세스로 실행되지 않습니다.
각 서비스는 외부 요청을 받는 API 프로세스와 스케줄러(scheduler),
컨덕터(conductor), 컴퓨트(compute), 에이전트(agent) 등 내부 작업을
-담당하는 여러 프로세스로 구성된다.
+담당하는 여러 프로세스로 구성됩니다.
이들 프로세스는 데이터베이스와 메시지 브로커(message broker) 같은
-공용 인프라를 사용한다.
+공용 인프라를 사용합니다.
API 접근과 서비스 간 통신
-----------------------------
+-------------------------
-사용자나 클라이언트가 OpenStack 서비스 API를 호출하려면 먼저 인증하고
-API 엔드포인트(endpoint)를 확인해야 한다.
-Keystone은 공통 인증을 처리하고 토큰과 서비스 카탈로그를 제공한다.
+사용자나 클라이언트가 OpenStack 서비스 API 를 호출하려면 먼저 인증하고
+API 엔드포인트(endpoint)를 확인해야 합니다.
+Keystone 은 공통 인증을 처리하고 토큰과 서비스 카탈로그를 제공합니다.
사용자나 클라이언트는 카탈로그에 등록된 Nova, Neutron, Cinder 등의
-API 엔드포인트를 확인한 뒤 각 서비스의 API를 직접 호출한다.
+API 엔드포인트를 확인한 뒤 각 서비스의 API 를 직접 호출합니다.
-OpenStack 서비스 간 기능 호출도 주로 각 서비스가 제공하는 HTTP API를
-통해 이루어진다.
+OpenStack 서비스 간 기능 호출도 주로 각 서비스가 제공하는 HTTP API 를
+통해 이루어집니다.
같은 서비스에 속한 분산 프로세스 사이에서는 ``oslo.messaging`` 기반
-원격 프로시저 호출(remote procedure call, RPC)과 알림을 사용한다.
-리소스 메타데이터와 제어 상태는 일반적으로 SQL 데이터베이스에 저장된다.
+원격 프로시저 호출(remote procedure call, RPC)과 알림을 사용합니다.
+리소스 메타데이터와 제어 상태는 일반적으로 SQL 데이터베이스에 저장됩니다.
-다음은 이러한 구조를 단순화한 것이다.
+다음은 이러한 구조를 단순화한 것입니다.
.. code-block:: text
@@ -92,35 +92,35 @@ OpenStack 서비스 간 기능 호출도 주로 각 서비스가 제공하는 HT
Scheduler · Conductor
Compute · Agent 등
-이 그림은 일반적인 구조를 단순화한 것이다.
-서비스마다 세부 구성과 통신 방식은 다를 수 있다.
+이 그림은 일반적인 구조를 단순화한 것입니다.
+서비스마다 세부 구성과 통신 방식은 다를 수 있습니다.
컨테이너 배포
-----------------
+-------------
-앞에서 살펴본 것처럼 OpenStack은 역할별 프로세스가 분리되어 있고,
+앞에서 살펴본 것처럼 OpenStack 은 역할별 프로세스가 분리되어 있고,
각 프로세스는 API, 메시지 큐, 데이터베이스와 같은 명시적인 인터페이스를
-통해 연결된다.
+통해 연결됩니다.
이 구조에서는 서비스 사이의 경계를 바꾸지 않고 각 프로세스의 실행 환경을
-별도로 패키징할 수 있다.
+별도로 패키징할 수 있습니다.
패키지 기반 배포에서는 OpenStack 데몬과 의존 라이브러리를 각 호스트의
-운영체제에 설치하고 ``systemd`` 서비스로 관리한다.
+운영체제에 설치하고 ``systemd`` 서비스로 관리합니다.
컨테이너 기반 배포에서는 OpenStack 데몬과 데몬 실행에 필요한 사용자 공간
-의존성을 컨테이너 이미지로 묶는다.
+의존성을 컨테이너 이미지로 묶습니다.
운영자는 동일한 이미지를 여러 노드에 배포해 호스트별 패키지 상태에 대한
-의존성을 줄이고 일관된 실행 환경을 구성할 수 있다.
+의존성을 줄이고 일관된 실행 환경을 구성할 수 있습니다.
-컨테이너화는 OpenStack의 서비스 구조를 새로 만드는 것이 아니라 기존의
-역할 구분과 통신 구조를 유지하면서 실행 환경을 표준화하는 방법이다.
-이러한 특성 때문에 OpenStack의 서비스 구조는 컨테이너 기반 배포와 잘 맞는다.
+컨테이너화는 OpenStack 의 서비스 구조를 새로 만드는 것이 아니라 기존의
+역할 구분과 통신 구조를 유지하면서 실행 환경을 표준화하는 방법입니다.
+이러한 특성 때문에 OpenStack 의 서비스 구조는 컨테이너 기반 배포와 잘 맞습니다.
구성 요소별 배포 고려사항
-------------------------
컨테이너 이미지는 실행 환경을 표준화하지만 구성 요소의 실행 위치,
-호스트 접근, 데이터 영속성에 대한 요구사항까지 없애지는 않는다.
-따라서 각 구성 요소의 역할과 의존성에 맞게 배포 방식을 설계해야 한다.
+호스트 접근, 데이터 영속성에 대한 요구사항까지 없애지는 않습니다.
+따라서 각 구성 요소의 역할과 의존성에 맞게 배포 방식을 설계해야 합니다.
.. list-table::
:header-rows: 1
@@ -132,44 +132,44 @@ OpenStack 서비스 간 기능 호출도 주로 각 서비스가 제공하는 HT
* - 중앙 제어 평면 프로세스
- ``nova-api``, ``nova-scheduler``,
``nova-conductor``, ``neutron-server``
- - 중앙 제어 노드에 여러 인스턴스로 배치할 수 있다.
- 데이터베이스, 메시지 브로커 및 다른 서비스의 API와
- 연결되어야 한다.
+ - 중앙 제어 노드에 여러 인스턴스로 배치할 수 있습니다.
+ 데이터베이스, 메시지 브로커 및 다른 서비스의 API 와
+ 연결되어야 합니다.
* - 호스트 종속 프로세스
- ``nova-compute``, Neutron 네트워크 에이전트
- 자신이 관리하는 하이퍼바이저(hypervisor), Open vSwitch, 네트워크
- 인터페이스 등이 있는 노드에서 실행되어야 한다.
- 컨테이너로 실행하더라도 임의의 노드로 이동할 수 없다.
+ 인터페이스 등이 있는 노드에서 실행되어야 합니다.
+ 컨테이너로 실행하더라도 임의의 노드로 이동할 수 없습니다.
* - 상태 저장 지원 인프라
- MariaDB, RabbitMQ
- 컨테이너의 실행뿐 아니라 영속 스토리지, 복제, 쿼럼(quorum),
- 백업과 복구를 함께 설계해야 한다.
+ 백업과 복구를 함께 설계해야 합니다.
예를 들어 ``nova-compute`` 프로세스는 자신이 관리하는 하이퍼바이저가 있는
-컴퓨트 노드에서 실행되어야 한다.
+컴퓨트 노드에서 실행되어야 합니다.
Neutron 에이전트 역시 해당 노드의 Open vSwitch, 네트워크 인터페이스,
-커널 네트워크 기능에 접근해야 한다.
-Kubernetes 위에 배포하더라도 이러한 노드 종속성은 유지된다.
+커널 네트워크 기능에 접근해야 합니다.
+Kubernetes 위에 배포하더라도 이러한 노드 종속성은 유지됩니다.
-MariaDB와 RabbitMQ도 컨테이너로 실행할 수 있다.
+MariaDB 와 RabbitMQ 도 컨테이너로 실행할 수 있습니다.
그러나 컨테이너를 다시 생성하는 것만으로 데이터베이스나 메시지 브로커
클러스터가 복구되는 것은 아니다.
-컨테이너 런타임이나 Kubernetes는 프로세스를 다시 실행할 수 있지만,
-데이터 일관성과 클러스터 복구는 각 시스템의 운영 방식에 따라 관리해야 한다.
+컨테이너 런타임이나 Kubernetes 는 프로세스를 다시 실행할 수 있지만,
+데이터 일관성과 클러스터 복구는 각 시스템의 운영 방식에 따라 관리해야 합니다.
따라서 배포 도구는 구성 요소마다 다른 호스트 종속성과 데이터 관리 요구사항을
-반영해야 한다.
+반영해야 합니다.
OpenStack 배포 방식
-============================
+===================
-앞 절에서는 OpenStack의 서비스 구조가 컨테이너 배포와 잘 맞는 이유를
-설명했다.
+앞 절에서는 OpenStack 의 서비스 구조가 컨테이너 배포와 잘 맞는 이유를
+설명했습니다.
실제 환경에서는 목적과 운영 기반에 따라 서로 다른 배포 방식과 도구를
-선택한다.
-여기서는 DevStack, Kolla-Ansible, openstack-helm의 주요 용도와
-실행·관리 기반을 간단히 살펴본다.
+선택합니다.
+여기서는 DevStack, Kolla-Ansible, openstack-helm 의 주요 용도와
+실행·관리 기반을 간단히 살펴봅니다.
배포 방식 비교
@@ -187,55 +187,55 @@ OpenStack 배포 방식
- 셸 스크립트(shell script)
- 개발과 학습을 위한 빠른 OpenStack 배포
* - Kolla-Ansible
- - Docker 또는 Podman과 Ansible
+ - Docker 또는 Podman 과 Ansible
- Kubernetes 없이 컨테이너화된 OpenStack 운영
* - openstack-helm
- - Kubernetes와 Helm
- - Helm chart를 이용한 선언적(declarative) OpenStack 배포
+ - Kubernetes 와 Helm
+ - Helm chart 를 이용한 선언적(declarative) OpenStack 배포
방식별 특징
-----------
DevStack
- 개발과 테스트 환경에 OpenStack을 빠르게 구성하기 위한 스크립트 모음이다.
- 학습과 기능 검증에는 유용하지만 프로덕션 운영을 목적으로 하지 않는다.
+ 개발과 테스트 환경에 OpenStack 을 빠르게 구성하기 위한 스크립트 모음입니다.
+ 학습과 기능 검증에는 유용하지만 프로덕션 운영을 목적으로 하지 않습니다.
Kolla-Ansible
- Kolla가 제공하는 OpenStack 서비스 컨테이너 이미지를 Docker 또는 Podman으로
- 실행하고 Ansible playbook으로 배포·설정한다.
- Kubernetes 없이 컨테이너화된 OpenStack을 운영할 때 사용할 수 있다.
+ Kolla 가 제공하는 OpenStack 서비스 컨테이너 이미지를 Docker 또는 Podman 으로
+ 실행하고 Ansible playbook 으로 배포·설정합니다.
+ Kubernetes 없이 컨테이너화된 OpenStack 을 운영할 때 사용할 수 있습니다.
openstack-helm
- OpenStack 서비스를 Helm chart로 패키징하여 Kubernetes 위에 배포한다.
- Kubernetes의 선언적 리소스 관리와 복구·롤아웃(rollout) 기능을
- OpenStack 운영에 활용한다.
+ OpenStack 서비스를 Helm chart 로 패키징하여 Kubernetes 위에 배포합니다.
+ Kubernetes 의 선언적 리소스 관리와 복구·롤아웃(rollout) 기능을
+ OpenStack 운영에 활용합니다.
-이 프로젝트는 openstack-helm을 중심으로 Kubernetes 위에 OpenStack을 배포하고
-운영하는 방법을 다룬다.
+이 프로젝트는 openstack-helm 을 중심으로 Kubernetes 위에 OpenStack 을 배포하고
+운영하는 방법을 다룹니다.
관련 배포 방식과 프로젝트는
-:doc:`../openstack-on-kubernetes/approaches` 에서 살펴본다.
-Kolla-Ansible과
-openstack-helm의 상세 차이는 :doc:`../openstack-on-kubernetes/comparison` 에서
-다룬다.
+:doc:`../openstack-on-kubernetes/approaches` 에서 살펴봅니다.
+Kolla-Ansible 과
+openstack-helm 의 상세 차이는 :doc:`../openstack-on-kubernetes/comparison` 에서
+다룹니다.
실습 전 기본 명령
=================
-아래 예시는 리소스를 변경하지 않는 조회 명령이다.
+아래 예시는 리소스를 변경하지 않는 조회 명령입니다.
명령을 실행하기 전에
-OpenStackClient를 설치하고 ``openrc`` 파일이나 ``clouds.yaml`` 파일로
-인증 정보를 설정해야 한다.
+OpenStackClient 를 설치하고 ``openrc`` 파일이나 ``clouds.yaml`` 파일로
+인증 정보를 설정해야 합니다.
-서비스 카탈로그를 조회하여 현재 인증 정보와 API 접근이 정상인지 확인한다.
+서비스 카탈로그를 조회하여 현재 인증 정보와 API 접근이 정상인지 확인합니다.
.. code-block:: console
$ openstack catalog list
컴퓨팅에 필요한 이미지와 플레이버(flavor), 현재 프로젝트의 인스턴스를
-조회한다.
+조회합니다.
.. code-block:: console
@@ -243,7 +243,7 @@ OpenStackClient를 설치하고 ``openrc`` 파일이나 ``clouds.yaml`` 파일
$ openstack flavor list
$ openstack server list
-네트워크와 서브넷, 라우터를 조회한다.
+네트워크와 서브넷, 라우터를 조회합니다.
.. code-block:: console
@@ -251,16 +251,16 @@ OpenStackClient를 설치하고 ``openrc`` 파일이나 ``clouds.yaml`` 파일
$ openstack subnet list
$ openstack router list
-Cinder와 Swift가 배포된 환경에서는 블록 볼륨과 오브젝트 스토리지 컨테이너를
-조회할 수 있다.
+Cinder 와 Swift 가 배포된 환경에서는 블록 볼륨과 오브젝트 스토리지 컨테이너를
+조회할 수 있습니다.
.. code-block:: console
$ openstack volume list
$ openstack container list
-목록에서 확인한 리소스의 이름이나 ID를 ``show`` 명령에 전달하면 상세 정보를
-확인할 수 있다.
+목록에서 확인한 리소스의 이름이나 ID 를 ``show`` 명령에 전달하면 상세 정보를
+확인할 수 있습니다.
.. code-block:: console
@@ -270,7 +270,7 @@ Cinder와 Swift가 배포된 환경에서는 블록 볼륨과 오브젝트 스
$ openstack volume show
인스턴스에 연결된 네트워크 포트와 볼륨, Swift 컨테이너에 저장된 오브젝트도
-조회할 수 있다.
+조회할 수 있습니다.
.. code-block:: console
@@ -279,7 +279,7 @@ Cinder와 Swift가 배포된 환경에서는 블록 볼륨과 오브젝트 스
$ openstack object list
자동화나 후처리가 필요하면 ``-f`` 로 출력 형식을, ``-c`` 로 출력할 열을
-선택한다.
+선택합니다.
.. code-block:: console
@@ -287,8 +287,8 @@ Cinder와 Swift가 배포된 환경에서는 블록 볼륨과 오브젝트 스
$ openstack server list -f json
$ openstack server list -f value -c ID -c Name
-````, ```` 와 같은 값은 실제 리소스의 이름이나 ID로 바꿔
-실행한다.
+````, ```` 와 같은 값은 실제 리소스의 이름이나 ID 로 바꿔
+실행합니다.
더 읽을거리
diff --git a/doc/source/foundations/openstack.rst b/doc/source/foundations/openstack.rst
index 2285c90..54850ba 100644
--- a/doc/source/foundations/openstack.rst
+++ b/doc/source/foundations/openstack.rst
@@ -1,9 +1,9 @@
-====================
+===================
OpenStack 핵심 개념
-====================
+===================
OpenStack 의 주요 특징과, 그 위에서 동작하는 네트워킹·스토리지 서비스를 묶어
-다룹니다. K8s 를 아는 독자가 OpenStack 을 이해하는 데 필요한 기초입니다.
+다룹니다. Kubernetes 를 아는 독자가 OpenStack 을 이해하는 데 필요한 기초입니다.
.. note::
diff --git a/doc/source/foundations/vm-vs-container.rst b/doc/source/foundations/vm-vs-container.rst
index 94589e4..48f7379 100644
--- a/doc/source/foundations/vm-vs-container.rst
+++ b/doc/source/foundations/vm-vs-container.rst
@@ -1,6 +1,6 @@
-===============================
+===========================
가상화 기초: VM vs 컨테이너
-===============================
+===========================
.. note::
diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst
index 62a2263..fcaa5ee 100644
--- a/doc/source/glossary.rst
+++ b/doc/source/glossary.rst
@@ -9,13 +9,27 @@
.. rubric:: 색인
-:ref:`C ` · :ref:`D ` · :ref:`G ` ·
-:ref:`H ` · :ref:`I ` · :ref:`K ` ·
-:ref:`M ` · :ref:`N ` · :ref:`O ` ·
-:ref:`P ` · :ref:`R ` · :ref:`S ` ·
+:ref:`A ` · :ref:`C ` · :ref:`D ` ·
+:ref:`G ` · :ref:`H ` · :ref:`I ` ·
+:ref:`K ` · :ref:`L ` · :ref:`M ` ·
+:ref:`N ` · :ref:`O ` · :ref:`P ` ·
+:ref:`Q ` · :ref:`R ` · :ref:`S ` ·
:ref:`V ` · :ref:`W `
+.. _glossary-a:
+
+.. rubric:: A
+
+.. glossary::
+ :sorted:
+
+ amphora
+ Octavia 가 로드밸런서마다 띄우는 전용 가상 머신. 내부에서 HAProxy 가
+ 실제 트래픽 분산을 처리한다. OVN 프로바이더 드라이버를 쓰면 이 VM 없이
+ OVN 의 로드 밸런싱 기능을 사용한다.
+
+
.. _glossary-c:
.. rubric:: C
@@ -61,6 +75,15 @@
가리키는 구분. Nova 가 관리하는 VM 은 Kubernetes 밖의 데이터 평면에
남는다.
+ cgroup
+ control group. 리눅스 커널이 프로세스 그룹의 CPU·메모리 등 자원 사용을
+ 제한하고 집계하는 기능. Kubernetes 는 Pod 를 ``kubepods`` 계층에,
+ libvirt 는 VM 을 ``machine`` 계층에 배치한다.
+
+ Calico
+ Kubernetes 의 대표적인 CNI 구현체. 본 프로젝트 실습 환경의 Pod
+ 네트워크를 구성한다.
+
.. _glossary-d:
@@ -114,6 +137,9 @@
Horizontal Pod Autoscaler. 부하에 따라 Pod 수를 자동으로 조절하는
Kubernetes 오토스케일링 기능.
+ Horizon
+ OpenStack 의 웹 대시보드 서비스.
+
.. _glossary-i:
@@ -157,6 +183,31 @@
컨테이너화된 애플리케이션을 자동으로 배포·스케일링·관리하는 오픈소스
프로젝트. CNCF 의 핵심 프로젝트.
+ kOps
+ Kubernetes 클러스터의 수명주기를 관리하는 도구. 클러스터 상태
+ 저장소(state store)로 Swift 같은 오브젝트 스토리지를 쓸 수 있다.
+
+ Kubespray
+ Ansible 로 Kubernetes 클러스터를 배포하는 프로젝트. OpenStack VM 위에
+ 클러스터를 직접 구성할 때 쓰인다.
+
+ KVM
+ Kernel-based Virtual Machine. 리눅스 커널의 하이퍼바이저 모듈.
+ Intel VT-x, AMD-V 같은 CPU 가상화 기능을 사용해 게스트 코드를 직접
+ 실행한다. Nova 의 libvirt 드라이버가 이를 사용한다.
+
+
+.. _glossary-l:
+
+.. rubric:: L
+
+.. glossary::
+ :sorted:
+
+ libvirt
+ 하이퍼바이저를 다루는 공통 관리 계층. Nova 는 libvirt 를 통해 KVM/QEMU
+ VM 을 만들고 제어한다. 데몬은 ``libvirtd`` 다.
+
.. _glossary-m:
@@ -178,6 +229,11 @@
베어메탈·온프레미스 Kubernetes 에서 ``LoadBalancer`` 타입 Service 에
외부 IP 를 제공하는 구현체.
+ ML2
+ Modular Layer 2. Neutron 의 코어 플러그인으로, 메커니즘 드라이버를 통해
+ OVS·OVN·SR-IOV 같은 백엔드를 선택한다. ``ML2/OVS``, ``ML2/OVN`` 처럼
+ 조합으로 표기한다.
+
.. _glossary-n:
@@ -237,6 +293,22 @@
PersistentVolume / PersistentVolumeClaim. 각각 실제 스토리지 자원과 그
자원에 대한 사용 요청. CSI 드라이버(예: Cinder CSI)로 연결된다.
+ Placement
+ 컴퓨트 자원의 인벤토리와 할당을 추적하는 OpenStack 서비스.
+ nova-scheduler 가 배치 후보를 고를 때 조회한다.
+
+
+.. _glossary-q:
+
+.. rubric:: Q
+
+.. glossary::
+ :sorted:
+
+ QEMU
+ VM 을 실행하는 사용자 공간 프로세스. vCPU 마다 호스트 스레드를 만들고,
+ KVM 이 처리하지 않는 I/O 를 에뮬레이션한다.
+
.. _glossary-r:
@@ -291,6 +363,11 @@
가상 머신(Virtual Machine). 하이퍼바이저 위에서 게스트 OS 커널까지 통째로
격리해 실행한다. OpenStack 에서는 Nova 가 관리한다.
+ VXLAN
+ Virtual Extensible LAN. L3 네트워크 위에 L2 세그먼트를 터널로 실어
+ 나르는 오버레이 기술. Neutron 테넌트 네트워크가 노드 사이를 넘을 때
+ 쓰인다.
+
.. _glossary-w:
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b30f4f2..2d35532 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,6 +1,6 @@
-================================================
+============================================
OpenStack & Kubernetes 운영 문서화 및 국제화
-================================================
+============================================
본 프로젝트는 인프라를 위한 두 대표 글로벌 오픈소스 프로젝트인
**Kubernetes(쿠버네티스)** 와 **OpenStack(오픈스택)** 을 설치·운영하는 방법 및
diff --git a/doc/source/integration-patterns.rst b/doc/source/integration-patterns.rst
index 29dcf05..3727cef 100644
--- a/doc/source/integration-patterns.rst
+++ b/doc/source/integration-patterns.rst
@@ -1,6 +1,6 @@
-==========
+=========
통합 패턴
-==========
+=========
OpenStack 과 Kubernetes 를 결합하는 두 가지 방향을 다룹니다. OpenStack 컨트롤
플레인을 Kubernetes 위에 올리는 방향과, 반대로 Kubernetes 클러스터를 OpenStack
diff --git a/doc/source/introduction/history-and-sigs.rst b/doc/source/introduction/history-and-sigs.rst
index 3f526bf..8f8738b 100644
--- a/doc/source/introduction/history-and-sigs.rst
+++ b/doc/source/introduction/history-and-sigs.rst
@@ -4,7 +4,8 @@
OpenStack 과 Kubernetes 의 통합은 어느 날 갑자기 등장한 것이 아니라, 두
커뮤니티가 오랜 기간 협력하며 형성해 온 흐름입니다. 이 절에서는 그 역사를
-SIG(Special Interest Group, 특별 관심 그룹) 활동을 중심으로 살펴보고, 현재의
+특별 관심 그룹(Special Interest Group, SIG) 활동을 중심으로 살펴보고,
+현재의
통합 지형이 어떻게 정리되었는지 정리합니다.
.. note::
@@ -45,6 +46,10 @@ Open Infrastructure Foundation 의 컨테이너 백서
시나리오)로 부르는 구조의 원형입니다.
+이 흐름을 따라 직접 실습하고 문서화·번역에 기여하는 순서는
+:doc:`learning-path` 에 정리되어 있습니다.
+
+
참고 자료
=========
diff --git a/doc/source/introduction/index.rst b/doc/source/introduction/index.rst
index 60636bf..f096271 100644
--- a/doc/source/introduction/index.rst
+++ b/doc/source/introduction/index.rst
@@ -1,9 +1,10 @@
-======
+====
소개
-======
+====
이 장에서는 OpenStack 과 Kubernetes 가 무엇이며 왜 함께 쓰이는지 소개합니다.
-두 커뮤니티가 통합을 위해 이어 온 SIG(Special Interest Group) 활동의 역사와
+두 커뮤니티가 통합을 위해 이어 온 특별 관심 그룹(Special Interest Group,
+SIG) 활동의 역사와
현재, 그리고 본 프로젝트가 권장하는 학습 경로도 함께 다룹니다.
.. toctree::
diff --git a/doc/source/introduction/learning-path.rst b/doc/source/introduction/learning-path.rst
index f05ee22..deb974c 100644
--- a/doc/source/introduction/learning-path.rst
+++ b/doc/source/introduction/learning-path.rst
@@ -1,6 +1,6 @@
-==========
+=========
학습 경로
-==========
+=========
아래 학습 경로는 두 오픈소스 기술을 직접 경험한 뒤 문서화·번역에 기여하기
위한 권장 순서입니다. 사전 지식 수준에 따라 조정할 수 있습니다.
@@ -11,6 +11,11 @@
#. **개념 이해** — :doc:`why-openstack-and-kubernetes` 와
:doc:`history-and-sigs` 를 읽고 두 기술이 함께 쓰이는 맥락을 파악합니다.
+#. **기초 개념 정리** — :doc:`../foundations/index` 에서 가상화 기초,
+ :doc:`../foundations/openstack-fundamentals`,
+ :doc:`../foundations/kubernetes-fundamentals`,
+ :doc:`../foundations/helm` 을 훑고, 두 기술을 잇는 표준 인터페이스는
+ :doc:`../foundations/bridging-concepts` 로 지도를 잡습니다.
#. **문서화 도구 준비** — :doc:`../documentation/rst-sphinx-basics` 를 따라
rST/Sphinx 와 ``tox`` 빌드 환경을 익힙니다.
#. **실습 환경 구성** — :doc:`../labs/index` 의 가이드를 따라 로컬 또는
diff --git a/doc/source/introduction/why-openstack-and-kubernetes.rst b/doc/source/introduction/why-openstack-and-kubernetes.rst
index 7e28915..df6e5df 100644
--- a/doc/source/introduction/why-openstack-and-kubernetes.rst
+++ b/doc/source/introduction/why-openstack-and-kubernetes.rst
@@ -1,6 +1,6 @@
-=====================================
+===============================
왜 OpenStack 과 Kubernetes 인가
-=====================================
+===============================
클라우드 인프라의 두 축
=======================
@@ -10,8 +10,8 @@
OpenStack Foundation)의 핵심 프로젝트입니다.
**Kubernetes** 는 컨테이너화된 애플리케이션을 자동으로 배포·스케일링·관리하는
-오픈소스 프로젝트로, CNCF(클라우드 네이티브 컴퓨팅 재단, Cloud Native
-Computing Foundation)의 핵심 프로젝트입니다.
+오픈소스 프로젝트로, 클라우드 네이티브 컴퓨팅 재단(Cloud Native Computing
+Foundation, CNCF)의 핵심 프로젝트입니다.
두 프로젝트를 지원하는 재단 모두 Linux Foundation 과 협력하여 클라우드
인프라 및 클라우드 네이티브 기술을 발전시키고 있으며, 전 세계 수많은 기업이
@@ -30,10 +30,11 @@ OpenStack on Kubernetes
OpenStack 의 각 서비스(Nova, Neutron, Keystone, Glance, Swift 등)를
컨테이너로 패키징하여 Kubernetes 위에서 운영하는 방식입니다.
-* `openstack-helm `_ 을 이용한
- Helm 기반 배포
-* `Kolla / Kolla-Ansible `_ 을
- 이용한 컨테이너 기반 배포
+* `openstack-helm `_
+ 을 이용한 Helm 기반 배포
+* `Kolla / Kolla-Ansible
+ `_ 을 이용한 컨테이너
+ 기반 배포
국내외 클라우드 사업자들이 OpenStack 컨트롤 플레인 현대화를 위해 이 구조를
적극 채택하고 있습니다. GitOps(FluxCD, ArgoCD)와 결합하면 Day-2 운영
@@ -48,7 +49,8 @@ Kubernetes on OpenStack
OpenStack 의 VM 인프라 위에 Kubernetes 클러스터를 프로비저닝·운영하는
방식입니다.
-* `Magnum `_ 을 통한 K8s-as-a-Service 제공
+* `Magnum `_ 을 통한
+ Kubernetes-as-a-Service 제공
* `cloud-provider-openstack
`_ 을 통한 Cinder
볼륨·Octavia 로드밸런서·Neutron 네트워크의 Kubernetes 통합
@@ -104,7 +106,7 @@ openstack-helm 을 처음 접하는 개발자라면 Kubernetes, Helm, OpenStack
본 프로젝트의 접근 방식
=======================
-본 프로젝트는 이 간극을 메우고자 OpenStack과 Kubernetes 운영 환경에 대해
+본 프로젝트는 이 간극을 메우고자 OpenStack 과 Kubernetes 운영 환경에 대해
이해 및 실습, 문서화를 진행합니다. 또한, 관련 OpenStack/Kubernetes 문서를
한글화하는 방법에 대해 설명합니다.
diff --git a/doc/source/kubernetes-on-openstack/cinder-csi.rst b/doc/source/kubernetes-on-openstack/cinder-csi.rst
index 7866360..74ad01b 100644
--- a/doc/source/kubernetes-on-openstack/cinder-csi.rst
+++ b/doc/source/kubernetes-on-openstack/cinder-csi.rst
@@ -2,8 +2,10 @@
Cinder CSI
==========
-Cinder CSI 드라이버는 OpenStack 의 블록 스토리지(Cinder)를 Kubernetes 의
-PersistentVolume 으로 제공합니다.
+Cinder CSI 드라이버는 OpenStack 의 블록 스토리지(:term:`Cinder`)를
+Kubernetes 의 PersistentVolume 으로 제공합니다. :term:`CSI` 인터페이스
+자체의 개념은 :doc:`../foundations/kubernetes-csi` 에서 다루므로, 이 문서는
+Cinder 를 연결하는 관점에 집중합니다.
.. note::
@@ -25,7 +27,7 @@ PersistentVolume 으로 제공합니다.
#. CSI 드라이버 배포
#. ``StorageClass`` 정의 (Cinder 백엔드 지정)
#. ``PersistentVolumeClaim`` 생성
-#. 파드에서 볼륨 마운트
+#. Pod 에서 볼륨 마운트
관련 문서
diff --git a/doc/source/kubernetes-on-openstack/cloud-provider-openstack.rst b/doc/source/kubernetes-on-openstack/cloud-provider-openstack.rst
index ad39021..dd4fb1e 100644
--- a/doc/source/kubernetes-on-openstack/cloud-provider-openstack.rst
+++ b/doc/source/kubernetes-on-openstack/cloud-provider-openstack.rst
@@ -1,6 +1,6 @@
-========================================
+==============================
cloud-provider-openstack (CCM)
-========================================
+==============================
`cloud-provider-openstack
`_ 는 Kubernetes 의
diff --git a/doc/source/kubernetes-on-openstack/cluster-api.rst b/doc/source/kubernetes-on-openstack/cluster-api.rst
index e8c9f70..272268c 100644
--- a/doc/source/kubernetes-on-openstack/cluster-api.rst
+++ b/doc/source/kubernetes-on-openstack/cluster-api.rst
@@ -1,16 +1,18 @@
-============================
+==================
Cluster API (CAPO)
-============================
+==================
-Cluster API(CAPI)는 Kubernetes 클러스터 자체를 K8s 스타일 API(CRD)로 선언적으로
-프로비저닝·관리하는 프로젝트입니다. CAPO(Cluster API Provider OpenStack)는 그
-OpenStack 프로바이더로, OpenStack(Nova/Neutron 등) 위에 K8s 클러스터를 만듭니다.
+Cluster API(CAPI)는 Kubernetes 클러스터 자체를 Kubernetes 스타일
+API(:term:`CRD`)로 선언적으로 프로비저닝·관리하는 프로젝트입니다.
+CAPO(Cluster API Provider OpenStack)는 그 OpenStack 프로바이더로,
+OpenStack(Nova/Neutron 등) 위에 Kubernetes 클러스터를 만듭니다.
.. note::
기여자 작업용 골격입니다. 실습 경험과 공식 문서를 바탕으로 보강해 주세요.
- Magnum 과 함께 "K8s on OpenStack" 클러스터 프로비저닝의 대표 방식입니다.
+ Magnum 과 함께 "Kubernetes on OpenStack" 클러스터 프로비저닝의 대표
+ 방식입니다.
개요
@@ -28,7 +30,7 @@ OpenStack 프로바이더로, OpenStack(Nova/Neutron 등) 위에 K8s 클러스
Magnum 과의 비교
================
-* Magnum — OpenStack API/서비스로 K8s 클러스터 제공 (:doc:`magnum`)
+* Magnum — OpenStack API/서비스로 Kubernetes 클러스터 제공 (:doc:`magnum`)
* CAPO — Kubernetes 네이티브 API(CRD)로 선언적 프로비저닝
.. todo::
diff --git a/doc/source/kubernetes-on-openstack/concepts.rst b/doc/source/kubernetes-on-openstack/concepts.rst
index 0ae9f07..e6268ef 100644
--- a/doc/source/kubernetes-on-openstack/concepts.rst
+++ b/doc/source/kubernetes-on-openstack/concepts.rst
@@ -13,11 +13,13 @@ OpenStack 위에 Kubernetes 클러스터를 올리기 전에 알아 두면 좋
배포 경로
=========
-* **Magnum** — OpenStack 이 제공하는 K8s-as-a-Service
+* **Magnum** — OpenStack 이 제공하는 Kubernetes-as-a-Service
(:doc:`magnum`)
-* **Kubespray** — Ansible 기반 범용 Kubernetes 배포 도구
-* **kOps** — 클러스터 수명주기 관리 도구 (state store 로 Swift 활용 가능)
+* :term:`Kubespray` — Ansible 기반 범용 Kubernetes 배포 도구
+* :term:`kOps` — 클러스터 수명주기 관리 도구. 클러스터 상태 저장소로
+ :doc:`../storage/swift` 를 활용할 수 있습니다
* **Cluster API (CAPI)** — 선언적 클러스터 수명주기 관리
+ (:doc:`cluster-api`)
OpenStack 과의 통합 지점
diff --git a/doc/source/kubernetes-on-openstack/magnum.rst b/doc/source/kubernetes-on-openstack/magnum.rst
index d5108db..359fed7 100644
--- a/doc/source/kubernetes-on-openstack/magnum.rst
+++ b/doc/source/kubernetes-on-openstack/magnum.rst
@@ -2,9 +2,9 @@
Magnum
======
-`Magnum `_ 은 OpenStack 에서 컨테이너
-오케스트레이션 엔진(주로 Kubernetes)을 Container-as-a-Service 형태로 제공하는
-프로젝트입니다.
+`Magnum `_ 은 OpenStack 에서
+컨테이너 오케스트레이션 엔진(주로 Kubernetes)을 Container-as-a-Service
+형태로 제공하는 프로젝트입니다.
.. note::
@@ -38,4 +38,4 @@ Magnum
참고
====
-* Magnum 공식 문서 — https://docs.openstack.org/magnum/
+* Magnum 공식 문서 — https://docs.openstack.org/magnum/latest/
diff --git a/doc/source/kubernetes-on-openstack/octavia-load-balancer.rst b/doc/source/kubernetes-on-openstack/octavia-load-balancer.rst
index b30d87a..85abf84 100644
--- a/doc/source/kubernetes-on-openstack/octavia-load-balancer.rst
+++ b/doc/source/kubernetes-on-openstack/octavia-load-balancer.rst
@@ -1,6 +1,6 @@
-==========================
+==================
Octavia 로드밸런서
-==========================
+==================
OpenStack 의 로드밸런싱 서비스인 Octavia 는 Kubernetes 의
``Service type=LoadBalancer`` 요청을 처리하여 외부 트래픽을 분산합니다.
@@ -25,7 +25,7 @@ OpenStack 의 로드밸런싱 서비스인 Octavia 는 Kubernetes 의
* Octavia 와 (구) Neutron-LBaaS 의 차이
* 어노테이션을 통한 세부 설정 (헬스 모니터, 프로토콜 등)
-* 옥타비아 amphora 와 OVN 프로바이더 차이
+* Octavia 의 amphora 와 OVN 프로바이더 차이
관련 문서
diff --git a/doc/source/labs/index.rst b/doc/source/labs/index.rst
index f30afd9..f7768d8 100644
--- a/doc/source/labs/index.rst
+++ b/doc/source/labs/index.rst
@@ -1,6 +1,6 @@
-======
+====
실습
-======
+====
이 장은 단계별 실습 가이드를 모읍니다. 직접 환경을 구축·운영하며 두 기술을
체득하는 것을 목표로 합니다.
diff --git a/doc/source/labs/kubernetes-on-openstack-lab.rst b/doc/source/labs/kubernetes-on-openstack-lab.rst
index 8a94847..be8475e 100644
--- a/doc/source/labs/kubernetes-on-openstack-lab.rst
+++ b/doc/source/labs/kubernetes-on-openstack-lab.rst
@@ -1,6 +1,6 @@
-===================================
+=============================
실습: Kubernetes on OpenStack
-===================================
+=============================
OpenStack 위에 Kubernetes 클러스터를 프로비저닝하는 실습입니다.
@@ -22,6 +22,9 @@ OpenStack 위에 Kubernetes 클러스터를 프로비저닝하는 실습입니
배포 경로 선택
==============
+각 경로의 개념과 선택 기준은 :doc:`../kubernetes-on-openstack/concepts` 에
+정리되어 있습니다.
+
* **Magnum** — OpenStack 이 제공하는 관리형 클러스터
(:doc:`../kubernetes-on-openstack/magnum`)
* **Kubespray** — Ansible 기반 직접 배포
diff --git a/doc/source/labs/openstack-helm-lab.rst b/doc/source/labs/openstack-helm-lab.rst
index b69648b..c38aabd 100644
--- a/doc/source/labs/openstack-helm-lab.rst
+++ b/doc/source/labs/openstack-helm-lab.rst
@@ -1,9 +1,9 @@
-=================================
+====================
실습: openstack-helm
-=================================
+====================
openstack-helm 으로 Kubernetes 위에 OpenStack 을 배포하는 실습입니다. 순서는
-OpenStack-Helm 공식 설치 흐름(Before starting → Kubernetes → Kubernetes
+openstack-helm 공식 설치 흐름(Before starting → Kubernetes → Kubernetes
전제조건 → Deploy OpenStack)을 따릅니다.
.. note::
@@ -27,8 +27,8 @@ OpenStack-Helm 공식 설치 흐름(Before starting → Kubernetes → Kubernete
1. Kubernetes 배포
==================
-동작 중인 Kubernetes 클러스터를 준비합니다. OSH 는 Ansible 롤 기반 부트스트랩을
-권장합니다.
+동작 중인 Kubernetes 클러스터를 준비합니다. openstack-helm 은 Ansible 롤
+기반 부트스트랩을 권장합니다.
* roles 저장소 clone
* Ansible 설치 및 roles lookup 경로 설정
diff --git a/doc/source/networking/index.rst b/doc/source/networking/index.rst
index b1f1087..c1d3c47 100644
--- a/doc/source/networking/index.rst
+++ b/doc/source/networking/index.rst
@@ -1,10 +1,10 @@
-==========
+========
네트워킹
-==========
+========
OpenStack 이 제공하는 네트워킹 서비스를 다룹니다. 가상 네트워킹(Neutron)과 SDN
백엔드(OVN/OVS), 로드 밸런싱(Octavia)이 대상입니다. 두 기술을 결합할 때의
-K8s-측 네트워킹(CNI 공존, Gateway API, MetalLB 등)은 통합 패턴 섹션에서
+Kubernetes 측 네트워킹(CNI 공존, Gateway API, MetalLB 등)은 통합 패턴 섹션에서
다룹니다.
.. note::
diff --git a/doc/source/networking/load-balancing.rst b/doc/source/networking/load-balancing.rst
index beec067..1f6eb13 100644
--- a/doc/source/networking/load-balancing.rst
+++ b/doc/source/networking/load-balancing.rst
@@ -1,6 +1,6 @@
-========================
+=====================
로드 밸런싱 (Octavia)
-========================
+=====================
Octavia 는 OpenStack 의 로드 밸런싱(LBaaS) 서비스입니다. 이 문서는 서비스
자체의 개념을 다루며, Kubernetes ``Service`` 의 백엔드로 쓰는 관점은
@@ -52,7 +52,7 @@ Octavia 는 로드밸런서, 리스너, 풀, 멤버, 헬스 모니터라는 다
amphora 드라이버와 OVN Octavia 드라이버
-========================================
+=======================================
Octavia 는 로드밸런서를 실제로 어떻게 구현할지 여러 드라이버(provider)로
선택할 수 있습니다. 그중 가장 널리 쓰이는 두 드라이버는 구조가 크게
@@ -66,7 +66,7 @@ Octavia 는 로드밸런서를 실제로 어떻게 구현할지 여러 드라이
- amphora 드라이버
- OVN Octavia 드라이버
* - 구현 방식
- - 로드밸런서마다 전용 가상 머신(amphora)을 생성하고, 그 안에서
+ - 로드밸런서마다 전용 가상 머신(:term:`amphora`)을 생성하고, 그 안에서
HAProxy 가 실제 분산을 처리합니다.
- 별도 VM 없이 OVN(Open Virtual Network)의 로드 밸런싱 기능을
그대로 활용합니다.
diff --git a/doc/source/networking/neutron-basics.rst b/doc/source/networking/neutron-basics.rst
index d09c8d7..49a5cba 100644
--- a/doc/source/networking/neutron-basics.rst
+++ b/doc/source/networking/neutron-basics.rst
@@ -1,9 +1,11 @@
-====================
+============
Neutron 기초
-====================
+============
-Neutron 은 OpenStack 의 가상 네트워킹(SDN) 서비스입니다. 실습 전에 잡아 두면
-좋은 핵심 구성요소와 개념을 정리합니다.
+:term:`Neutron` 은 OpenStack 의 가상 네트워킹(:term:`SDN`) 서비스입니다.
+실습 전에 잡아 두면 좋은 핵심 구성요소와 개념을 정리합니다. 백엔드 구현체는
+:doc:`ovn-ovs`, Kubernetes 네트워크와의 공존은
+:doc:`../openstack-on-kubernetes/cni-and-neutron` 에서 다룹니다.
.. note::
diff --git a/doc/source/networking/ovn-ovs.rst b/doc/source/networking/ovn-ovs.rst
index 407f217..0863942 100644
--- a/doc/source/networking/ovn-ovs.rst
+++ b/doc/source/networking/ovn-ovs.rst
@@ -1,29 +1,30 @@
-====================
+=========
OVN / OVS
-====================
+=========
-OVN(Open Virtual Network)과 OVS(Open vSwitch)는 OpenStack Neutron에서
-사용되는 대표적인 네트워크 기술입니다. OVS는 호스트에서 실제 네트워크
-패킷을 전달하는 가상 스위치 역할을 하며, OVN은 OVS를 데이터 평면으로
-사용하여 논리적인 네트워크를 구성하고 관리합니다.
+:term:`OVN` (Open Virtual Network)과 :term:`OVS` (Open vSwitch)는 OpenStack
+:term:`Neutron` 에서 사용되는 대표적인 네트워크 기술입니다. OVS 는 호스트에서
+실제 네트워크 패킷을 전달하는 가상 스위치 역할을 하며, OVN 은 OVS 를 데이터
+평면으로 사용하여 논리적인 네트워크를 구성하고 관리합니다.
-최근 OpenStack 배포에서는 Neutron의 네트워크 백엔드로 ML2/OVN 구성이
-널리 사용되고 있습니다.
+최근 OpenStack 배포에서는 Neutron 의 네트워크 백엔드로 :term:`ML2` /OVN 구성이
+널리 사용되고 있습니다. Neutron 의 기본 구성요소는
+:doc:`neutron-basics` 에서 먼저 확인하세요.
-OVS와 OVN의 관계
-----------------
+OVS 와 OVN 의 관계
+==================
-OVS는 호스트 단에서 동작하는 가상 스위치입니다.
-VM의 가상 NIC, 물리 NIC, 터널 인터페이스 등을 연결하고 실제 패킷을
+OVS 는 호스트 단에서 동작하는 가상 스위치입니다.
+VM 의 가상 NIC, 물리 NIC, 터널 인터페이스 등을 연결하고 실제 패킷을
전달하는 데이터 평면(Data Plane) 역할을 담당합니다.
-OVN은 OVS를 데이터 평면으로 사용하면서
+OVN 은 OVS 를 데이터 평면으로 사용하면서
논리적인 네트워크를 정의하고 관리하는 네트워크 제어 계층(Control Plane)
역할을 합니다. 논리 스위치, 논리 라우터, ACL 등의 네트워크
기능을 논리적인 객체로 표현할 수 있습니다.
-OVN과 OVS는 다음과 같이 역할을
+OVN 과 OVS 는 다음과 같이 역할을
나누어 사용합니다.
.. code-block:: text
@@ -49,14 +50,14 @@ OVN과 OVS는 다음과 같이 역할을
* **OVS**: 호스트 단의 가상 스위치(데이터 평면)
* **OVN**: OVS 위에 논리 네트워크(라우팅/L2/L3)를 얹는 컨트롤 평면
-* **ML2/OVN**: Neutron과 OVN을 연결
-* **ovn-controller**: OVN의 네트워크 상태를 호스트의 OVS에 반영
+* **ML2/OVN**: Neutron 과 OVN 을 연결
+* **ovn-controller**: OVN 의 네트워크 상태를 호스트의 OVS 에 반영
OVN 도입에 따른 Neutron Agent 구조 단순화
------------------------------------------
+=========================================
-기존 ML2/OVS 구조에서는 네트워크 기능별로 여러 Neutron Agent가
+기존 ML2/OVS 구조에서는 네트워크 기능별로 여러 Neutron Agent 가
사용되었습니다.
.. code-block:: text
@@ -72,13 +73,13 @@ OVN 도입에 따른 Neutron Agent 구조 단순화
v
OVS
-OVS Agent는 OVS 브리지와 Flow를 관리하고, L3 Agent와 DHCP Agent는
+OVS Agent 는 OVS 브리지와 Flow 를 관리하고, L3 Agent 와 DHCP Agent 는
각각 라우팅과 DHCP 기능을 담당합니다.
-네트워크 기능별로 Agent가 구성되기 때문에 여러 Agent의 상태와
+네트워크 기능별로 Agent 가 구성되기 때문에 여러 Agent 의 상태와
통신을 함께 관리해야 합니다.
-ML2/OVN에서는 OVN이 논리 네트워크 모델을 통해 주요 네트워크 기능을
+ML2/OVN 에서는 OVN 이 논리 네트워크 모델을 통해 주요 네트워크 기능을
처리하므로 구조가 다음과 같이 단순화됩니다.
.. code-block:: text
@@ -96,23 +97,23 @@ ML2/OVN에서는 OVN이 논리 네트워크 모델을 통해 주요 네트워크
v
OVS
-OVN은 논리적인 네트워크 객체로 관리하고, :code:`ovn-controller` 프로세스가
+OVN 은 논리적인 네트워크 객체로 관리하고, ``ovn-controller`` 프로세스가
이를 각 호스트의 OVS 데이터 평면에 반영합니다.
-이에 따라 기존의 OVS Agent, L3 Agent, DHCP Agent가 담당하던
-주요 네트워크 기능을 OVN으로 통합할 수 있으며, Neutron의
+이에 따라 기존의 OVS Agent, L3 Agent, DHCP Agent 가 담당하던
+주요 네트워크 기능을 OVN 으로 통합할 수 있으며, Neutron 의
Agent 중심 구조가 단순해집니다.
.. note::
- OVN을 사용한다고 해서 모든 Neutron Agent가 사라지는 것은 아닙니다.
- 일부 기능에서는 여전히 Neutron Agent가 사용될 수 있습니다.
- 따라서 OVN은 기존 Agent를 완전히 제거한다기보다, 핵심 네트워크
- 기능을 OVN으로 이동하여 Agent 구조를 단순화한 것입니다.
+ OVN 을 사용한다고 해서 모든 Neutron Agent 가 사라지는 것은 아닙니다.
+ 일부 기능에서는 여전히 Neutron Agent 가 사용될 수 있습니다.
+ 따라서 OVN 은 기존 Agent 를 완전히 제거한다기보다, 핵심 네트워크
+ 기능을 OVN 으로 이동하여 Agent 구조를 단순화한 것입니다.
더 읽을거리
------------
+===========
* `OVN Features
`_
@@ -128,3 +129,6 @@ Agent 중심 구조가 단순해집니다.
* `Neutron OVN Design
`_
+
+* :doc:`../openstack-on-kubernetes/cni-and-neutron` — Kubernetes 의 CNI 와
+ Neutron 백엔드가 한 노드에서 공존하는 구조
diff --git a/doc/source/openstack-on-kubernetes/approaches.rst b/doc/source/openstack-on-kubernetes/approaches.rst
index 7ee49f4..f20ce29 100644
--- a/doc/source/openstack-on-kubernetes/approaches.rst
+++ b/doc/source/openstack-on-kubernetes/approaches.rst
@@ -1,10 +1,11 @@
-======================
+====================
배포 방식과 프로젝트
-======================
+====================
OpenStack 을 Kubernetes 위에 올리는 방법은 하나가 아닙니다. 여기서는 대표적인
프로젝트·접근을 훑고, 그중 이 섹션이 중심으로 삼는 openstack-helm 이 어디에
-서 있는지 짚습니다.
+서 있는지 짚습니다. DevStack·Kolla-Ansible 을 포함한 배포 방식 전반의 비교는
+:doc:`../foundations/openstack-fundamentals` 에서 먼저 살펴볼 수 있습니다.
.. note::
diff --git a/doc/source/openstack-on-kubernetes/cni-and-neutron.rst b/doc/source/openstack-on-kubernetes/cni-and-neutron.rst
index 343be65..a7ed426 100644
--- a/doc/source/openstack-on-kubernetes/cni-and-neutron.rst
+++ b/doc/source/openstack-on-kubernetes/cni-and-neutron.rst
@@ -1,67 +1,68 @@
-========================
+======================
CNI 와 Neutron 의 공존
-========================
+======================
.. note::
OpenStack on Kubernetes 에서는 OpenStack 서비스가 Kubernetes 위에서
- 실행되는 동시에, 그 서비스가 생성한 가상 머신에는 OpenStack 네트워크가
- 제공된다.
+ 실행되는 동시에, 그 서비스가 생성한 VM 에는 OpenStack 네트워크가
+ 제공됩니다.
이 문서는 이때 컨테이너 네트워크 인터페이스(:term:`CNI`)와 OpenStack
네트워킹 서비스(:term:`Neutron`)가 각각 무엇을 담당하며 어떤 방식으로
- 공존하는지 설명한다.
+ 공존하는지 설명합니다.
두 스택이 공존하는 이유
=======================
-OpenStack-Helm 은 Keystone, Nova, Neutron, Glance 등의 애플리케이션 프로그래밍
+openstack-helm 은 Keystone, Nova, Neutron, Glance 등의 애플리케이션 프로그래밍
인터페이스(API)와 서버 구성 요소를
-Kubernetes 파드로 배포한다.
-이 파드들과 RabbitMQ, 데이터베이스 같은 백엔드
-서비스가 통신하려면 Kubernetes 의 파드 네트워크가 필요하다.
+Kubernetes Pod 로 배포합니다.
+이 Pod 들과 RabbitMQ, 데이터베이스 같은 백엔드
+서비스가 통신하려면 Kubernetes 의 Pod 네트워크가 필요합니다.
-한편 OpenStack 사용자가 생성한 Nova 가상 머신은 Kubernetes 파드가 아니다.
-가상 머신의 네트워크, 서브넷, 포트, 라우터, 보안 그룹 및 플로팅 IP 는
-OpenStack Networking 서비스인 Neutron 이 관리한다.
+한편 OpenStack 사용자가 생성한 Nova 의 가상 머신(virtual machine, VM)은
+Kubernetes Pod 가 아닙니다.
+VM 의 네트워크, 서브넷, 포트, 라우터, 보안 그룹 및 플로팅 IP 는
+OpenStack Networking 서비스인 Neutron 이 관리합니다.
따라서 하나의 OpenStack on Kubernetes 환경에는 다음 두 네트워크가 동시에
-존재한다.
+존재합니다.
-* **Kubernetes 계층:** CNI 가 OpenStack 서비스 파드와 백엔드 파드의 통신을
- 담당한다.
-* **OpenStack 계층:** Neutron 이 Nova 가상 머신과 테넌트 네트워크의 통신을
- 담당한다.
+* **Kubernetes 계층:** CNI 가 OpenStack 서비스 Pod 와 백엔드 Pod 의 통신을
+ 담당합니다.
+* **OpenStack 계층:** Neutron 이 Nova VM 과 테넌트 네트워크의 통신을
+ 담당합니다.
.. code-block:: text
Kubernetes 가 설치된 물리 노드
├─ Kubernetes 계층
- │ └─ OpenStack 서비스 파드 ─ CNI 기반 파드 네트워크
+ │ └─ OpenStack 서비스 Pod ─ CNI 기반 Pod 네트워크
└─ OpenStack 계층
- └─ Nova 가상 머신 ─────── Neutron 네트워크
+ └─ Nova VM ───────────── Neutron 네트워크
│
공통 물리 네트워크
두 네트워크는 같은 물리 노드와 물리 네트워크를 사용할 수 있지만 서로 다른
-대상을 담당한다.
-CNI 는 파드를 연결하고, Neutron 은 가상 머신을 연결한다.
+대상을 담당합니다.
+CNI 는 Pod 를 연결하고, Neutron 은 VM 을 연결합니다.
-OpenStack 서비스 간의 네트워크 생성·변경 요청은 CNI 기반 파드 네트워크를 통해
-Neutron 에 전달될 수 있다.
-그러나 가상 머신의 실제 사용자 패킷이 OpenStack 서비스 파드를 거치는 것은
-아니다.
+OpenStack 서비스 간의 네트워크 생성·변경 요청은 CNI 기반 Pod 네트워크를 통해
+Neutron 에 전달될 수 있습니다.
+그러나 VM 의 실제 사용자 패킷이 OpenStack 서비스 Pod 를 거치는 것은
+아닙니다.
OpenStack 의 API 및 네트워크
-관리 서비스가 원하는 네트워크 상태를 만들면, 이후 가상 머신의 통신은
-Neutron 이 구성한 별도의 경로에서 처리된다.
+관리 서비스가 원하는 네트워크 상태를 만들면, 이후 VM 의 통신은
+Neutron 이 구성한 별도의 경로에서 처리됩니다.
-OpenStack API 접근과 가상 머신 접근의 차이
--------------------------------------------
+OpenStack API 접근과 VM 접근의 차이
+------------------------------------------
외부에서 OpenStack 환경으로 들어오는 요청은 목적지에 따라 OpenStack API 에
-대한 관리 요청과 가상 머신 애플리케이션에 대한 사용자 트래픽으로 구분할 수
-있다.
+대한 관리 요청과 VM 애플리케이션에 대한 사용자 트래픽으로 구분할 수
+있습니다.
.. list-table::
:header-rows: 1
@@ -69,35 +70,35 @@ OpenStack API 접근과 가상 머신 접근의 차이
* - 구분
- OpenStack API 접근
- - 가상 머신 애플리케이션 접근
+ - VM 애플리케이션 접근
* - 목적
- - 가상 머신 생성·조회·삭제
- - 가상 머신에서 실행되는 서비스 사용
+ - VM 생성·조회·삭제
+ - VM 에서 실행되는 서비스 사용
* - 목적지
- - ``nova-api`` 파드
- - Nova 가 관리하는 가상 머신
+ - ``nova-api`` Pod
+ - Nova 가 관리하는 VM
* - 대표 경로
- - 인그레스·로드밸런서 → Kubernetes 서비스 → API 파드
- - 프로바이더 네트워크 → ``br-ex`` → 플로팅 IP → 가상 머신
+ - 인그레스·로드밸런서 → Kubernetes 서비스 → API Pod
+ - 프로바이더 네트워크 → ``br-ex`` → 플로팅 IP → VM
* - 담당 영역
- Kubernetes 와 OpenStack 제어 서비스
- - Neutron 이 구성한 가상 머신 패킷 경로
+ - Neutron 이 구성한 VM 패킷 경로
첫 번째 경로는 OpenStack 자원을 생성하거나 조회하기 위한 관리 요청이고, 두
-번째 경로는 가상 머신에서 실행되는 애플리케이션의 데이터를 주고받는 경로이다.
-목적지가 다르기 때문에 필요한 노출 방식과 보안 정책도 다르다.
+번째 경로는 VM 에서 실행되는 애플리케이션의 데이터를 주고받는 경로입니다.
+목적지가 다르기 때문에 필요한 노출 방식과 보안 정책도 다릅니다.
.. code-block:: text
OpenStack 사용자
- └─ 인그레스·로드밸런서 ─ nova-api 서비스 ─ nova-api 파드
+ └─ 인그레스·로드밸런서 ─ nova-api 서비스 ─ nova-api Pod
- 가상 머신 서비스 사용자
- └─ 프로바이더 네트워크 ─ br-ex ─ Neutron 라우터·플로팅 IP ─ 가상 머신
+ VM 서비스 사용자
+ └─ 프로바이더 네트워크 ─ br-ex ─ Neutron 라우터·플로팅 IP ─ VM
통신 사례로 보는 계층 구분
----------------------------
+--------------------------
.. list-table::
:header-rows: 1
@@ -106,37 +107,37 @@ OpenStack API 접근과 가상 머신 접근의 차이
* - 통신 사례
- 담당 계층
- 개념적인 경로
- * - OpenStack API 파드가 다른 서비스 파드에 요청
+ * - OpenStack API Pod 가 다른 서비스 Pod 에 요청
- Kubernetes 계층
- - 송신 파드 → CNI 기반 파드 네트워크 → 대상 파드
- * - 같은 노드의 가상 머신 간 통신
+ - 송신 Pod → CNI 기반 Pod 네트워크 → 대상 Pod
+ * - 같은 노드의 VM 간 통신
- Neutron
- - 송신 가상 머신 → 노드의 가상 네트워크 → 수신 가상 머신
- * - 서로 다른 노드의 가상 머신 간 통신
+ - 송신 VM → 노드의 가상 네트워크 → 수신 VM
+ * - 서로 다른 노드의 VM 간 통신
- Neutron
- - 송신 가상 머신 → 송신 노드 → 물리 네트워크 → 수신 노드 → 수신 가상 머신
+ - 송신 VM → 송신 노드 → 물리 네트워크 → 수신 노드 → 수신 VM
* - 플로팅 IP 를 통한 외부 접근
- Neutron
- - 외부 네트워크 → Neutron 라우팅·주소 변환 → 대상 가상 머신
+ - 외부 네트워크 → Neutron 라우팅·주소 변환 → 대상 VM
-같은 물리 네트워크 위에서 두 종류의 통신이 흐르더라도 정책 경계는 분리된다.
-파드 통신 정책은 Kubernetes 계층에서, 가상 머신의 보안 그룹과 라우팅 정책은
-Neutron 계층에서 적용된다.
-따라서 "파드 통신은 정상인데 가상 머신 통신만
+같은 물리 네트워크 위에서 두 종류의 통신이 흐르더라도 정책 경계는 분리됩니다.
+Pod 통신 정책은 Kubernetes 계층에서, VM 의 보안 그룹과 라우팅 정책은
+Neutron 계층에서 적용됩니다.
+따라서 "Pod 통신은 정상인데 VM 통신만
실패하는" 상황이 발생할 수 있으며, 운영자는 먼저 어느 계층의 문제인지
-구분해야 한다.
+구분해야 합니다.
-OpenStack-Helm 과 네트워크 구현체의 관계
-=========================================
+openstack-helm 과 네트워크 구현체의 관계
+========================================
-OpenStack-Helm 은 특정 CNI 나 Neutron 네트워크 백엔드를 하나로 고정하지
-않는다.
+openstack-helm 은 특정 CNI 나 Neutron 네트워크 백엔드를 하나로 고정하지
+않습니다.
OpenStack 서비스를 Kubernetes 에 배포하고, 선택한 네트워크
-구현체를 Helm 설정값으로 구성할 수 있도록 제공한다.
+구현체를 Helm 설정값으로 구성할 수 있도록 제공합니다.
Neutron 백엔드에는 Open vSwitch(:term:`OVS`)나 Open Virtual Network(:term:`OVN`)
-기반 기술이 사용될 수 있다.
+기반 기술이 사용될 수 있습니다.
.. list-table::
:header-rows: 1
@@ -144,7 +145,7 @@ Neutron 백엔드에는 Open vSwitch(:term:`OVS`)나 Open Virtual Network(:term:
* - 구분
- 예시
- * - CNI 표준을 사용하는 파드 네트워크 구현체
+ * - CNI 표준을 사용하는 Pod 네트워크 구현체
- Calico, Cilium, Flannel, ovn-kubernetes
* - Neutron 네트워크 백엔드
- ML2/OVS, ML2/OVN, SR-IOV
@@ -152,102 +153,102 @@ Neutron 백엔드에는 Open vSwitch(:term:`OVS`)나 Open Virtual Network(:term:
- Calico 와 Neutron ML2/OVS
따라서 OpenStack on Kubernetes 의 네트워크 구조를 이해하려면
-OpenStack-Helm 자체만 보는 것이 아니라 Kubernetes 에 적용된 CNI 플러그인과
-Neutron 에 적용된 네트워크 백엔드의 조합을 함께 확인해야 한다.
+openstack-helm 자체만 보는 것이 아니라 Kubernetes 에 적용된 CNI 플러그인과
+Neutron 에 적용된 네트워크 백엔드의 조합을 함께 확인해야 합니다.
이 조합에
따라 두 네트워크를 독립적인 기술 스택으로 운영할 수도 있고, 양쪽에 공통된
-네트워크 기술을 적용해 운영 경험과 도구를 공유할 수도 있다.
+네트워크 기술을 적용해 운영 경험과 도구를 공유할 수도 있습니다.
통합 접근
=========
CNI 와 Neutron 이 공존하는 방식은 크게 각 스택을 독립적으로 운영하는 구성과
-양쪽에서 OVN 계열 기술을 사용하는 구성으로 나누어 볼 수 있다.
+양쪽에서 OVN 계열 기술을 사용하는 구성으로 나누어 볼 수 있습니다.
이는 CNI 와 Neutron 의 책임을 합치는 것이 아니라, 서로 다른 두 네트워크를
-어떤 기술적·운영적 관계로 구성할지에 관한 선택이다.
+어떤 기술적·운영적 관계로 구성할지에 관한 선택입니다.
두 스택을 각각 운영
---------------------
+-------------------
Kubernetes 에는 Calico, Flannel, Cilium 같은 CNI 플러그인을 사용하고,
-OpenStack 가상 머신 네트워크에는 Neutron 의 별도 백엔드를 사용하는
-방식이다.
-CNI 는 파드 네트워크를, Neutron 은 가상 머신 네트워크를 담당한
-채 각각의 제어 영역과 운영 수명주기를 유지한다.
+OpenStack VM 네트워크에는 Neutron 의 별도 백엔드를 사용하는
+방식입니다.
+CNI 는 Pod 네트워크를, Neutron 은 VM 네트워크를 담당한
+채 각각의 제어 영역과 운영 수명주기를 유지합니다.
**장점**
-* **기술 선택과 업그레이드를 독립적으로 수행할 수 있다.** 한쪽의
- 구현체를 교체하거나 버전을 올릴 때 다른 쪽을 동시에 변경할 필요가 없다.
-* **각 생태계에서 널리 검증된 구성을 선택할 수 있다.** 조직의 정책,
+* **기술 선택과 업그레이드를 독립적으로 수행할 수 있습니다.** 한쪽의
+ 구현체를 교체하거나 버전을 올릴 때 다른 쪽을 동시에 변경할 필요가 없습니다.
+* **각 생태계에서 널리 검증된 구성을 선택할 수 있습니다.** 조직의 정책,
성능 요구 및 운영 경험에 맞는 CNI 와 Neutron 백엔드를 각각 선택할 수
- 있다.
-* **장애 범위를 구분하기 쉽다.** 서비스 파드 통신 장애는 CNI 와
- Kubernetes 서비스를, 가상 머신 통신 장애는 Neutron 포트·라우터·보안
- 그룹을 우선 조사할 수 있다.
-* **변경의 영향 범위를 제한할 수 있다.** 한쪽 네트워크의 변경이나 장애가
+ 있습니다.
+* **장애 범위를 구분하기 쉽습니다.** 서비스 Pod 통신 장애는 CNI 와
+ Kubernetes 서비스를, VM 통신 장애는 Neutron 포트·라우터·보안
+ 그룹을 우선 조사할 수 있습니다.
+* **변경의 영향 범위를 제한할 수 있습니다.** 한쪽 네트워크의 변경이나 장애가
다른 쪽 데이터 평면에 직접 전파되지 않아 단계적인 검증과 롤백 계획을 세우기
- 쉽다.
+ 쉽습니다.
**고려 사항**
-* **주소 계획을 이중으로 관리해야 한다.** 파드 주소 대역과 Neutron 테넌트
- 네트워크 대역이 겹치지 않도록 구축 단계에서 주소 범위를 정해야 한다.
-* **정책이 서로 다른 위치에서 적용된다.** 파드 접근 제어는 Kubernetes
- 네트워크 정책으로, 가상 머신 접근 제어는 Neutron 보안 그룹으로 관리한다.
-* **관측 및 장애 대응 도구가 나뉜다.** Kubernetes 의 파드·서비스·CNI
- 도구와 OpenStack 의 network·port·router 도구를 모두 사용해야 한다.
-* **공통 물리 네트워크의 자원을 함께 사용한다.** 같은 노드 NIC 와 물리
+* **주소 계획을 이중으로 관리해야 합니다.** Pod 주소 대역과 Neutron 테넌트
+ 네트워크 대역이 겹치지 않도록 구축 단계에서 주소 범위를 정해야 합니다.
+* **정책이 서로 다른 위치에서 적용됩니다.** Pod 접근 제어는 Kubernetes
+ 네트워크 정책으로, VM 접근 제어는 Neutron 보안 그룹으로 관리합니다.
+* **관측 및 장애 대응 도구가 나뉩니다.** Kubernetes 의 Pod·서비스·CNI
+ 도구와 OpenStack 의 network·port·router 도구를 모두 사용해야 합니다.
+* **공통 물리 네트워크의 자원을 함께 사용합니다.** 같은 노드 NIC 와 물리
네트워크를 사용한다면 최대 전송 단위(MTU), 대역폭, 주소 경로를 함께 고려해야
- 한다.
+ 합니다.
OVN 계열 기술을 양쪽에서 사용
--------------------------------
+-----------------------------
Kubernetes CNI 로 ovn-kubernetes 를 선택하고 Neutron 도 :term:`OVN` 기반
-백엔드를 사용하면 파드 네트워크와 가상 머신 네트워크가 모두 :term:`OVS`·OVN
-계열 기술을 사용한다.
+백엔드를 사용하면 Pod 네트워크와 VM 네트워크가 모두 :term:`OVS`·OVN
+계열 기술을 사용합니다.
.. code-block:: text
- OVN-Kubernetes ─ 파드 네트워크 ─┐
- ├─ 공통 기술 기반: OVN·OVS
- Neutron + OVN ─ 가상 머신 네트워크 ┘
+ OVN-Kubernetes ─ Pod 네트워크 ─┐
+ ├─ 공통 기술 기반: OVN·OVS
+ Neutron + OVN ─ VM 네트워크 ────┘
이 접근의 핵심은 두 계층에서 공통된 네트워크 기술을 사용해 운영 지식과 도구를
-재사용하는 것이다.
-다만 ovn-kubernetes 는 Kubernetes 의 파드, 서비스,
+재사용하는 것입니다.
+다만 ovn-kubernetes 는 Kubernetes 의 Pod, 서비스,
네트워크 정책을, Neutron 은 OpenStack 의 network, port, router, 보안 그룹을
-각각 관리한다.
+각각 관리합니다.
같은 기술을 선택해도 두 네트워크나 제어 영역이 자동으로 하나가 되는 것은
-아니다.
+아닙니다.
데이터베이스와 제어 영역까지 공유하려면 호환성,
-주소 관리, 정책 소유권과 장애 영향 범위를 별도로 설계하고 검증해야 한다.
+주소 관리, 정책 소유권과 장애 영향 범위를 별도로 설계하고 검증해야 합니다.
**장점**
-* **공통된 기술 모델과 운영 경험을 재사용할 수 있다.** 양쪽 모두 OVN 의
+* **공통된 기술 모델과 운영 경험을 재사용할 수 있습니다.** 양쪽 모두 OVN 의
논리 네트워크와 OVS 데이터 평면을 기반으로 하므로 관측 체계를 일관되게
- 가져갈 수 있다.
-* **호스트의 네트워크 기술 구성을 일관되게 가져갈 수 있다.** 기존의
+ 가져갈 수 있습니다.
+* **호스트의 네트워크 기술 구성을 일관되게 가져갈 수 있습니다.** 기존의
OVN·OVS 모니터링, 성능 튜닝 또는 하드웨어 가속 경험을 양쪽에 활용할 수
- 있다.
-* **향후 연계 가능성을 검토하기 쉽다.** 파드와 가상 머신 연결, 공통 물리
+ 있습니다.
+* **향후 연계 가능성을 검토하기 쉽습니다.** Pod 와 VM 연결, 공통 물리
네트워크 연계 같은 고급 통합을 설계할 때 공통 개념과 도구를 활용할 수
- 있다.
+ 있습니다.
**고려 사항**
-* **버전과 업그레이드 호환성을 확인해야 한다.** ovn-kubernetes 와
- Neutron 이 요구하는 OVN·OVS 버전 범위가 다를 수 있다.
-* **정책과 주소 관리의 소유권은 여전히 분리된다.** Kubernetes 네트워크
- 정책과 Neutron 보안 그룹은 서로 다른 API 와 리소스이다.
-* **공통 기술 장애가 넓은 영향을 줄 수 있다.** OVN·OVS 운영 구성이나
+* **버전과 업그레이드 호환성을 확인해야 합니다.** ovn-kubernetes 와
+ Neutron 이 요구하는 OVN·OVS 버전 범위가 다를 수 있습니다.
+* **정책과 주소 관리의 소유권은 여전히 분리됩니다.** Kubernetes 네트워크
+ 정책과 Neutron 보안 그룹은 서로 다른 API 와 리소스입니다.
+* **공통 기술 장애가 넓은 영향을 줄 수 있습니다.** OVN·OVS 운영 구성이나
호스트 자원에 공통 문제가 생기면 두 네트워크가 동시에 영향을 받을 수 있어
- 장애 격리와 롤백 계획이 필요하다.
+ 장애 격리와 롤백 계획이 필요합니다.
접근 방식 비교
@@ -277,48 +278,48 @@ Kubernetes CNI 로 ovn-kubernetes 를 선택하고 Neutron 도 :term:`OVN` 기
- 기술은 일관되지만 통합 수준이 높을수록 결합도 증가
어느 방식을 선택하더라도 CNI 와 Neutron 이 담당하는 대상 자체는 달라지지
-않는다.
+않습니다.
중요한 것은 두 네트워크를 무조건 하나로 합치는 것이 아니라 운영
-환경에 맞게 책임 범위와 장애 경계를 명확하게 설계하는 것이다.
+환경에 맞게 책임 범위와 장애 경계를 명확하게 설계하는 것입니다.
-실제 네트워크 구성과 가상 머신 패킷 경로
-===========================================
+실제 네트워크 구성과 VM 패킷 경로
+========================================
-사용자가 가상 머신을 생성할 때 네트워크가 어떻게 구성되고, 구성이 끝난 뒤
+사용자가 VM 을 생성할 때 네트워크가 어떻게 구성되고, 구성이 끝난 뒤
실제 패킷이 어떤 경로로 이동하는지 구분해 보자.
이는 앞에서 설명한 두 네트워크에 새로운 네트워크를 하나 더 추가하는 것이
-아니다.
+아닙니다.
같은 OpenStack 환경을 네트워크 설정을 만드는 과정과
-만들어진 설정에 따라 패킷을 전달하는 과정으로 나누어 보는 것이다.
+만들어진 설정에 따라 패킷을 전달하는 과정으로 나누어 보는 것입니다.
네트워크 구성 과정과 패킷 이동 과정
-------------------------------------
+-----------------------------------
-* **네트워크를 구성하는 과정:** 가상 머신이 사용할 네트워크, 포트, IP, 보안
- 그룹과 전달 경로를 만든다.
- 이를 제어 평면(control plane)이라고 한다.
+* **네트워크를 구성하는 과정:** VM 이 사용할 네트워크, 포트, IP, 보안
+ 그룹과 전달 경로를 만듭니다.
+ 이를 제어 평면(control plane)이라고 합니다.
* **실제 패킷이 이동하는 과정:** 구성된 가상 네트워크 장치(TAP), OVS 와
- 라우터를 따라 가상 머신의
- 패킷이 이동한다.
- 이를 데이터 평면(data plane)이라고 한다.
+ 라우터를 따라 VM 의
+ 패킷이 이동합니다.
+ 이를 데이터 평면(data plane)이라고 합니다.
도로에 비유하면 네트워크 구성은 도로와 신호 체계를 만드는 작업이고, 패킷
-이동은 완성된 도로 위로 자동차가 이동하는 것에 해당한다.
+이동은 완성된 도로 위로 자동차가 이동하는 것에 해당합니다.
.. code-block:: text
- 네트워크·포트·정책 정의 → TAP·OVS·라우터 구성 → 가상 머신 패킷 전달
+ 네트워크·포트·정책 정의 → TAP·OVS·라우터 구성 → VM 패킷 전달
두 용어는 특정 장비나 별도의 물리 네트워크 이름이 아니라 기능을 구분하는
-표현이다.
-다음 질문으로 쉽게 구분할 수 있다.
+표현입니다.
+다음 질문으로 쉽게 구분할 수 있습니다.
.. pull-quote::
지금 전달되는 내용이 네트워크를 만들거나 변경하기 위한 명령인가, 아니면
- 가상 머신 애플리케이션이 주고받는 실제 데이터인가?
+ VM 애플리케이션이 주고받는 실제 데이터인가?
.. list-table::
:header-rows: 1
@@ -329,29 +330,29 @@ Kubernetes CNI 로 ovn-kubernetes 를 선택하고 Neutron 도 :term:`OVN` 기
- 실제 패킷이 이동하는 과정
* - 목적
- 네트워크와 전달 규칙 생성
- - 가상 머신의 실제 통신 전달
+ - VM 의 실제 통신 전달
* - 전달 내용
- API 요청, 포트·라우터·정책 정보
- 이더넷 프레임, IP·TCP·UDP 패킷
* - 주요 구성 요소
- Nova API, Neutron Server, 데이터베이스, 메시지 큐, 에이전트
- - 가상 머신 가상 네트워크 인터페이스(vNIC), TAP, OVS,
+ - VM 가상 네트워크 인터페이스(vNIC), TAP, OVS,
Virtual Extensible LAN(VXLAN), 라우터, 물리 네트워크 인터페이스 카드(NIC)
* - 동작 시점
- 생성·변경·삭제 시
- - 가상 머신 통신이 발생할 때마다
+ - VM 통신이 발생할 때마다
* - 대표 장애
- - 가상 머신 생성 실패, 포트가 DOWN
- - 가상 머신은 ACTIVE 지만 ping 이나 외부 접속 실패
+ - VM 생성 실패, 포트가 DOWN
+ - VM 은 ACTIVE 지만 ping 이나 외부 접속 실패
장애 증상으로 담당 계층 구분하기
-=================================
+================================
CNI 와 Neutron 은 같은 노드와 물리 네트워크를 공유할 수 있지만 관리 대상과
-정책 경계는 분리된다.
-통신 장애가 발생하면 먼저 파드와 가상 머신 중 어느
-대상에서 문제가 발생했는지 구분해야 한다.
+정책 경계는 분리됩니다.
+통신 장애가 발생하면 먼저 Pod 와 VM 중 어느
+대상에서 문제가 발생했는지 구분해야 합니다.
.. list-table::
:header-rows: 1
@@ -360,27 +361,27 @@ CNI 와 Neutron 은 같은 노드와 물리 네트워크를 공유할 수 있지
* - 증상
- 우선 확인할 영역
- 대표 확인 대상
- * - OpenStack API 파드끼리 통신하지 못함
+ * - OpenStack API Pod 끼리 통신하지 못함
- Kubernetes 계층
- - 파드, 서비스, 엔드포인트, Calico, 네트워크 정책
- * - 가상 머신 생성 또는 포트 연결이 완료되지 않음
+ - Pod, 서비스, 엔드포인트, Calico, 네트워크 정책
+ * - VM 생성 또는 포트 연결이 완료되지 않음
- OpenStack 네트워크 구성 과정
- Nova, Neutron Server, 메시지 큐, Neutron 에이전트, 포트 바인딩
- * - 같은 노드의 가상 머신끼리 통신하지 못함
- - 가상 머신의 로컬 패킷 경로
- - TAP, ``br-int``, 보안 그룹, 가상 머신 포트
- * - 다른 노드의 가상 머신끼리만 통신하지 못함
+ * - 같은 노드의 VM끼리 통신하지 못함
+ - VM 의 로컬 패킷 경로
+ - TAP, ``br-int``, 보안 그룹, VM 포트
+ * - 다른 노드의 VM 끼리만 통신하지 못함
- 오버레이 네트워크(overlay)와 언더레이 네트워크(underlay)
- ``br-tun``, VXLAN, 터널 IP, 노드 간 연결, MTU
* - 내부 통신은 되지만 플로팅 IP 접속이 안 됨
- 외부 연결 경로
- ``br-ex``, 라우터, 플로팅 IP, 보안 그룹, 외부 방화벽
-예를 들어 OpenStack API 호출과 파드 통신은 정상인데 가상 머신의 ping 만
+예를 들어 OpenStack API 호출과 Pod 통신은 정상인데 VM 의 ping 만
실패한다면 CNI 보다 Neutron 포트, 보안 그룹과 OVS 경로를 먼저 확인하는 것이
-적절하다.
-반대로 API 파드 사이의 통신부터 실패한다면 가상 머신 데이터
-경로보다 Kubernetes 서비스와 CNI 상태를 먼저 확인해야 한다.
+적절합니다.
+반대로 API Pod 사이의 통신부터 실패한다면 VM 데이터
+경로보다 Kubernetes 서비스와 CNI 상태를 먼저 확인해야 합니다.
더 읽을거리
@@ -390,7 +391,7 @@ CNI 와 Neutron 은 같은 노드와 물리 네트워크를 공유할 수 있지
* :term:`Neutron`
* :term:`OVS`
* :term:`OVN`
-* `OpenStack-Helm 공식 문서 — Networking
+* `openstack-helm 공식 문서 — Networking
`_
* `OpenStack Neutron 공식 문서 — Networking architecture
`_
diff --git a/doc/source/openstack-on-kubernetes/comparison.rst b/doc/source/openstack-on-kubernetes/comparison.rst
index 314eca6..dbcc2da 100644
--- a/doc/source/openstack-on-kubernetes/comparison.rst
+++ b/doc/source/openstack-on-kubernetes/comparison.rst
@@ -1,6 +1,6 @@
-================================
+===============================
Kolla-Ansible vs openstack-helm
-================================
+===============================
두 배포 도구 모두 OpenStack 배포를 자동화하지만, 오케스트레이션 계층이
다릅니다(Kolla-Ansible = Ansible + Docker, openstack-helm = Kubernetes + Helm).
@@ -27,17 +27,18 @@ Kolla-Ansible vs openstack-helm
=============
* self-healing, 롤링 업데이트, 스케일 아웃의 선언성 비교
-* 디버깅 경험(SSH 컨테이너 확인 vs kubectl/기존 K8s tooling)
+* 디버깅 경험(SSH 컨테이너 확인 vs kubectl 등 기존 Kubernetes 도구)
.. todo::
- Prometheus/Grafana 등 기존 K8s 운영 tooling 통합 관점 보강.
+ Prometheus/Grafana 등 기존 Kubernetes 운영 도구 통합 관점 보강.
stateful 워크로드 문제
======================
-* nova-compute, cinder-volume 등 하이퍼바이저/스토리지 바인딩 서비스의 K8s화
+* nova-compute, cinder-volume 등 하이퍼바이저/스토리지 바인딩 서비스를
+ Kubernetes 로 옮기는 문제
* hostPath / DaemonSet 강제 등 Pod 추상화와의 충돌 지점
.. todo::
@@ -50,7 +51,7 @@ stateful 워크로드 문제
.. todo::
- 조직 상황별(기존 K8s 운영 역량 유무 등) 선택 기준 정리.
+ 조직 상황별(기존 Kubernetes 운영 역량 유무 등) 선택 기준 정리.
더 읽을거리
diff --git a/doc/source/openstack-on-kubernetes/concepts.rst b/doc/source/openstack-on-kubernetes/concepts.rst
index 220fd68..9387994 100644
--- a/doc/source/openstack-on-kubernetes/concepts.rst
+++ b/doc/source/openstack-on-kubernetes/concepts.rst
@@ -1,6 +1,6 @@
-==============================
-핵심 개념 (OpenStack on K8s)
-==============================
+===================================
+핵심 개념 (OpenStack on Kubernetes)
+===================================
OpenStack 을 Kubernetes 위에서 운영하기 전에 잡아 두면 좋은 핵심 개념을
모았습니다.
@@ -47,7 +47,7 @@ OpenStack 의 주요 서비스가 Kubernetes 리소스로 어떻게 매핑되는
.. _nova-hypervisor-registration:
Kubernetes 노드의 Nova 하이퍼바이저 등록
-============================================
+========================================
:term:`Nova` 가 VM 을 배치하려면 각 노드가 하이퍼바이저(hypervisor)로
먼저 등록되어 있어야 합니다.
@@ -59,7 +59,7 @@ nova-compute 가 실행되는 Kubernetes 노드 자신입니다.
→ 셀(cell) 매핑 → 스케줄러의 배치 후보
등록 과정
-------------
+---------
nova-compute 가 기동하면서 수행하는 일:
@@ -74,7 +74,7 @@ nova-compute 가 기동하면서 수행하는 일:
호스트명이고, 그 이름이 하이퍼바이저 이름으로 그대로 등록됩니다.
등록 확인
-------------
+---------
.. code-block:: console
@@ -87,13 +87,16 @@ nova-compute 가 기동하면서 수행하는 일:
그대로 표시
셀 매핑 개요
-----------------
+------------
* 등록된 호스트는 셀(cell)에 매핑되어야 스케줄러의 배치 대상이 됨
* 매핑은 ``nova-manage cell_v2 discover_hosts`` 가 수행 — 배포 도구가
주기적 실행을 자동화하는 것이 일반적
* 셀 내부 구조는 이 절의 범위 밖 (후속 문서에서 다룰 수 있음)
+등록을 마친 노드에서 Nova 가 실제로 VM 을 만들고 격리하는 과정은
+:doc:`nova-libvirt-kvm` 에서 이어집니다.
+
배포 방식 비교
==============
diff --git a/doc/source/openstack-on-kubernetes/gateway-api.rst b/doc/source/openstack-on-kubernetes/gateway-api.rst
index 8d1edfe..e74c903 100644
--- a/doc/source/openstack-on-kubernetes/gateway-api.rst
+++ b/doc/source/openstack-on-kubernetes/gateway-api.rst
@@ -1,9 +1,9 @@
-====================
+===========
Gateway API
-====================
+===========
Gateway API 는 Kubernetes 의 트래픽 진입(라우팅) 표준입니다. 기존 Ingress 의
-후속 격으로, OpenStack-Helm 최신 설치에서 서비스 노출 진입점으로 쓰입니다.
+후속 격으로, openstack-helm 최신 설치에서 서비스 노출 진입점으로 쓰입니다.
.. note::
@@ -25,7 +25,7 @@ openstack-helm 에서의 역할
==========================
* OpenStack 서비스 엔드포인트를 외부로 노출하는 진입점
-* K8s 전제조건으로서의 설치 위치 — :doc:`../labs/openstack-helm-lab`
+* Kubernetes 전제조건으로서의 설치 위치 — :doc:`../labs/openstack-helm-lab`
* MetalLB(:doc:`metallb`)와의 관계 — L4(LB) 위의 L7(라우팅)
.. todo::
diff --git a/doc/source/openstack-on-kubernetes/index.rst b/doc/source/openstack-on-kubernetes/index.rst
index f68e962..50490da 100644
--- a/doc/source/openstack-on-kubernetes/index.rst
+++ b/doc/source/openstack-on-kubernetes/index.rst
@@ -8,7 +8,8 @@ OpenStack 의 각 서비스(Nova, Neutron, Keystone, Glance, Swift 등)를 컨
해당합니다.
올리는 방법은 하나가 아니지만(:doc:`approaches`), 이 섹션은 그 기반이 되는
-openstack-helm 을 중심으로 준비부터 운영까지 짚습니다.
+openstack-helm 을 중심으로 준비부터 운영까지 짚습니다. 먼저 잡아 두면 좋은
+개념은 :doc:`concepts` 에 모아 두었습니다.
.. toctree::
:maxdepth: 1
@@ -21,7 +22,7 @@ openstack-helm 을 중심으로 준비부터 운영까지 짚습니다.
.. toctree::
:maxdepth: 1
- :caption: K8s 네트워킹 준비
+ :caption: Kubernetes 네트워킹 준비
openstack-helm-network-outline
cni-and-neutron
diff --git a/doc/source/openstack-on-kubernetes/kolla.rst b/doc/source/openstack-on-kubernetes/kolla.rst
index 48abe20..6c131ef 100644
--- a/doc/source/openstack-on-kubernetes/kolla.rst
+++ b/doc/source/openstack-on-kubernetes/kolla.rst
@@ -1,11 +1,11 @@
-============================
+=======================
Kolla (컨테이너 이미지)
-============================
+=======================
-`Kolla `_ 는 OpenStack 서비스의 프로덕션용
-컨테이너 이미지를 빌드하는 프로젝트입니다. openstack-helm 과 Kolla-Ansible 이
-모두 이 이미지를 사용합니다 — 즉 Kolla 는 "배포 도구" 가 아니라 그 아래의
-"이미지 레이어" 입니다.
+`Kolla `_ 는 OpenStack 서비스의
+프로덕션용 컨테이너 이미지를 빌드하는 프로젝트입니다. openstack-helm 과
+Kolla-Ansible 이 모두 이 이미지를 사용합니다 — 즉 Kolla 는 "배포 도구" 가
+아니라 그 아래의 "이미지 레이어" 입니다.
.. note::
@@ -41,5 +41,6 @@ openstack-helm 과의 관계
참고
====
-* Kolla — https://docs.openstack.org/kolla/
-* Kolla-Ansible(배포 도구, 비교용) — https://docs.openstack.org/kolla-ansible/
+* Kolla — https://docs.openstack.org/kolla/latest/
+* Kolla-Ansible(배포 도구, 비교용) —
+ https://docs.openstack.org/kolla-ansible/latest/
diff --git a/doc/source/openstack-on-kubernetes/metallb.rst b/doc/source/openstack-on-kubernetes/metallb.rst
index c329d7d..2756024 100644
--- a/doc/source/openstack-on-kubernetes/metallb.rst
+++ b/doc/source/openstack-on-kubernetes/metallb.rst
@@ -1,10 +1,10 @@
-================================
+===============================
MetalLB (베어메탈 LoadBalancer)
-================================
+===============================
베어메탈/멀티노드 Kubernetes 에는 클라우드 LB 가 없어 ``LoadBalancer`` 타입
Service 가 외부 IP 를 못 받습니다. MetalLB 가 이 역할을 대신하며, OpenStack 을
-Kubernetes 에 올리는(openstack-helm) 배포의 K8s 전제조건이기도 합니다
+Kubernetes 에 올리는(openstack-helm) 배포의 Kubernetes 전제조건이기도 합니다
(:doc:`../labs/openstack-helm-lab`).
.. note::
@@ -17,7 +17,7 @@ Kubernetes 에 올리는(openstack-helm) 배포의 K8s 전제조건이기도 합
* L2(ARP) 모드 vs BGP 모드
* IP 주소 풀 구성
-* Octavia(OpenStack LBaaS)와의 역할 구분 — 계층이 다름(K8s Service ↔ OpenStack).
+* Octavia(OpenStack LBaaS)와의 역할 구분 — 계층이 다름(Kubernetes Service ↔ OpenStack).
OpenStack 측 로드 밸런싱 서비스는 :doc:`../networking/load-balancing` 참고
.. todo::
diff --git a/doc/source/openstack-on-kubernetes/neutron-helm-chart.rst b/doc/source/openstack-on-kubernetes/neutron-helm-chart.rst
index 4e51c9d..9db1816 100644
--- a/doc/source/openstack-on-kubernetes/neutron-helm-chart.rst
+++ b/doc/source/openstack-on-kubernetes/neutron-helm-chart.rst
@@ -1,11 +1,13 @@
-==================================
+============================
Neutron Helm Chart 구조 파악
-==================================
+============================
`openstack-helm `_ 의 neutron
-chart 는 OpenStack 네트워킹 서비스를 Kubernetes 위에 배포하는 Helm chart 다.
-이 문서는 `차트 디렉터리 `_
-의 파일 구성과 각 항목이 실제 Kubernetes 리소스로 어떻게 구현되는지를 정리한다.
+chart 는 OpenStack 네트워킹 서비스를 Kubernetes 위에 배포하는 Helm
+chart 입니다. 이 문서는
+`차트 디렉터리 `_
+의 파일 구성과 각 항목이 실제 Kubernetes 리소스로 어떻게 구현되는지를
+정리합니다.
차트 최상위 파일
@@ -20,12 +22,12 @@ chart 는 OpenStack 네트워킹 서비스를 Kubernetes 위에 배포하는 Hel
└── templates/ # Kubernetes 리소스 템플릿
**Chart.yaml** 은 차트 이름, 버전(``2026.1.0``), appVersion(``28.0.0``)을 선언하며,
-``helm-toolkit`` 을 라이브러리 의존성으로 등록한다.
+``helm-toolkit`` 을 라이브러리 의존성으로 등록합니다.
helm-toolkit 은 openstack-helm 전체에서 공통 스니펫(snippet)을 제공하는 내부 라이브러리
-차트로, 실제 Kubernetes 리소스를 직접 생성하지는 않는다.
+차트로, 실제 Kubernetes 리소스를 직접 생성하지는 않습니다.
-**values.yaml** 은 배포 시 오버라이드할 수 있는 기본값 전체를 담는다.
-주요 최상위 블록은 아래 표와 같다.
+**values.yaml** 은 배포 시 오버라이드할 수 있는 기본값 전체를 담습니다.
+주요 최상위 블록은 아래 표와 같습니다.
.. list-table::
:header-rows: 1
@@ -50,22 +52,23 @@ helm-toolkit 은 openstack-helm 전체에서 공통 스니펫(snippet)을 제공
templates/ 디렉터리 구성
-=========================
+========================
-templates/ 아래 파일들은 역할에 따라 다음과 같이 묶인다.
+templates/ 아래 파일들은 역할에 따라 다음과 같이 묶입니다.
설정 관련
---------
``bin/`` 디렉터리에는 각 컴포넌트의 기동 스크립트가 ``_*.sh.tpl`` 형식으로
-들어 있다.
+들어 있습니다.
Helm 이 렌더링하면 ``configmap-bin.yaml`` 에 의해
-단일 ConfigMap 으로 묶여 각 Pod 의 ``/tmp/`` 경로에 마운트된다.
+단일 ConfigMap 으로 묶여 각 Pod 의 ``/tmp/`` 경로에 마운트됩니다.
``configmap-etc.yaml`` 은 ``values.yaml`` 의 ``conf`` 블록 값을
-``neutron.conf``, ``ml2_conf.ini``, ``l3_agent.ini`` 등 설정 파일로 렌더링한다.
+``neutron.conf``, ``ml2_conf.ini``, ``l3_agent.ini`` 등 설정 파일로
+렌더링합니다.
특이한 점은 이 템플릿 내부에서 ``endpoints`` 블록을 참조해 DB 접속 URL,
-RabbitMQ transport URL, Keystone auth_url 등을 자동으로 채워 넣는다는 것이다.
+RabbitMQ transport URL, Keystone auth_url 등을 자동으로 채워 넣는다는 점입니다.
.. code-block:: text
@@ -77,7 +80,7 @@ RabbitMQ transport URL, Keystone auth_url 등을 자동으로 채워 넣는다
워크로드 관련
-------------
-컴포넌트의 역할에 따라 Kubernetes 워크로드 타입이 다르게 선택된다.
+컴포넌트의 역할에 따라 Kubernetes 워크로드 타입이 다르게 선택됩니다.
.. list-table::
:header-rows: 1
@@ -124,15 +127,15 @@ RabbitMQ transport URL, Keystone auth_url 등을 자동으로 채워 넣는다
- 고아 네트워크 네임스페이스 정리 크론
``network.backend`` 값에 따라 OVS 관련 또는 OVN 관련 DaemonSet 이
-동적으로 활성화된다.
+동적으로 활성화됩니다.
사용하지 않는 에이전트는 ``manifests`` 토글로
-리소스 자체가 생성되지 않는다.
+리소스 자체가 생성되지 않습니다.
Job 관련
--------
서비스 기동 전 일회성 작업은 Helm Hook(``post-install``, ``post-upgrade``)으로
-등록된 Job 으로 실행된다.
+등록된 Job 으로 실행됩니다.
.. list-table::
:header-rows: 1
@@ -181,10 +184,10 @@ Job 관련
값 → 리소스 반영 흐름 요약
-===========================
+==========================
아래는 ``helm install`` 시 values.yaml 의 값이 실제 Kubernetes 리소스로 이어지는
-흐름이다.
+흐름입니다.
.. code-block:: text
diff --git a/doc/source/openstack-on-kubernetes/nova-libvirt-kvm.rst b/doc/source/openstack-on-kubernetes/nova-libvirt-kvm.rst
index a778b0b..09d39dc 100644
--- a/doc/source/openstack-on-kubernetes/nova-libvirt-kvm.rst
+++ b/doc/source/openstack-on-kubernetes/nova-libvirt-kvm.rst
@@ -1,52 +1,54 @@
.. _nova-libvirt-kvm:
-===============================================
+===========================================
Nova 의 VM 생성과 자원 격리 (libvirt / KVM)
-===============================================
-
-OpenStack on Kubernetes(openstack-helm) 환경에서 Nova 가 인스턴스 생성 요청을 받아
-Kubernetes 생태계와 호스트 커널을 거쳐 실제 QEMU 프로세스를 띄우기까지의 전체 과정을 정리합니다.
+===========================================
+OpenStack on Kubernetes(openstack-helm) 환경에서 :term:`Nova` 가 인스턴스
+생성 요청을 받아 Kubernetes 생태계와 호스트 커널을 거쳐 실제 :term:`QEMU`
+프로세스를 띄우기까지의 전체 과정을 정리합니다. 노드가 하이퍼바이저로
+등록되는 앞 단계는 :ref:`nova-hypervisor-registration` 에서 다룹니다.
Nova 에서 VM 이 만들어지기까지
-===============================
+==============================
요청 경로: nova-api 에서 nova-compute 까지
---------------------------------------------
+------------------------------------------
#. **nova-api** — Keystone 으로 토큰을 검증하고, 자원 한도를 확인한 뒤,
- DB에 가상 머신 생성을 위한 정보를 기록합니다.
+ DB 에 가상 머신 생성을 위한 정보를 기록합니다.
이후 nova-conductor 에게 요청을 전달합니다.
-#. **nova-conductor** — nova-api로부터 받은 요청을 처리합니다.
- nova-scheduler를 호출해 생성 위치를 정하고, DB 프록시(대리인) 역할을 수행하며,
- 최종적으로 선택된 nova-compute에 VM 생성을 지시합니다.
-#. **nova-scheduler + Placement** — nova-scheduler는 Placement에게
+#. **nova-conductor** — nova-api 로부터 받은 요청을 처리합니다.
+ nova-scheduler 를 호출해 생성 위치를 정하고, DB 프록시(대리인) 역할을 수행하며,
+ 최종적으로 선택된 nova-compute 에 VM 생성을 지시합니다.
+#. **nova-scheduler + Placement** — nova-scheduler 는 :term:`Placement` 에게
vCPU/RAM/디스크 등 조건을 만족하는 컴퓨트 노드를 물어 후보
목록을 받고, 그중 필터와 가중치를 적용해 최종 호스트를 고릅니다.
선택이 끝나면 Placement 에 기록(claim)합니다.
-#. **nova-compute** — 선택된 컴퓨트 노드의 nova-compute Pod로 요청이 전달됩니다.
- nova-compute는 Glance에서 이미지를 받아오고, Neutron에 네트워크 포트를,
- Cinder에 볼륨을 요청해 VM을 구성합니다.
-#. **Pod 간 UNIX 소켓 통신** — openstack-helm 환경에서 nova-compute와 libvirt는 각각 별도의
- DaemonSet Pod로 실행됩니다.
- nova-compute는 도메인 XML을 생성한 후,
- 두 Pod가 공유 마운트한 호스트 경로 상의 UNIX 소켓(RPC)을 통해 libvirt Pod 내부의 libvirtd에 전달합니다.
+#. **nova-compute** — 선택된 컴퓨트 노드의 nova-compute Pod 로 요청이 전달됩니다.
+ nova-compute 는 Glance 에서 이미지를 받아오고, Neutron 에 네트워크 포트를,
+ Cinder 에 볼륨을 요청해 VM 을 구성합니다.
+#. **Pod 간 UNIX 소켓 통신** — openstack-helm 환경에서 nova-compute 와 libvirt 는 각각 별도의
+ DaemonSet Pod 로 실행됩니다.
+ nova-compute 는 도메인 XML 을 생성한 후,
+ 두 Pod 가 공유 마운트한 호스트 경로 상의 UNIX 소켓(RPC)을 통해 libvirt Pod 내부의 libvirtd 에 전달합니다.
-libvirt Pod의 호스트 접근 권한 확보
-------------------------------------------------------------------------
+libvirt Pod 의 호스트 접근 권한 확보
+------------------------------------
-컨테이너는 기본적으로 호스트 커널 및 하드웨어 접근이 제한(unprivileged)되어 있으나,
-libvirtd는 KVM 제어와 장치 할당을 위해 호스트 권한이 필요합니다.
+컨테이너는 기본적으로 호스트 커널 및 하드웨어 접근이 제한(unprivileged)되어
+있으나, :term:`libvirt` 의 데몬인 libvirtd 는 :term:`KVM` 제어와 장치 할당을
+위해 호스트 권한이 필요합니다.
-#. **Pod의 Privileged 모드 설정** — libvirt Pod를 privileged 모드로 실행하여,
+#. **Pod 의 Privileged 모드 설정** — libvirt Pod 를 privileged 모드로 실행하여,
호스트의 실제 디렉터리를 직접 마운트하여 제어합니다.
-#. **kubelet cgroup 계층 탈출** - Pod는 기본적으로 kubelet이 관리하는
- cgroup 계층(kubepods) 아래에서 실행됩니다.
- 그러나 libvirtd가 이 안에 갇혀 있으면 자식 프로세스인 QEMU도 Pod의 리소스 제한을 받게 됩니다.
- 이는 VM의 자원 할당에 제약의 원인이 되므로, libvirt Pod는 호스트 권한을 사용하여 이 계층을 벗어나,
- 직접 cgroup을 생성하고 libvirtd의 cgroup을 system.slice 아래로 이동시킵니다.
+#. **kubelet cgroup 계층 탈출** — Pod 는 기본적으로 kubelet 이 관리하는
+ :term:`cgroup` 계층(kubepods) 아래에서 실행됩니다.
+ 그러나 libvirtd 가 이 안에 갇혀 있으면 자식 프로세스인 QEMU 도 Pod 의 리소스 제한을 받게 됩니다.
+ 이는 VM 의 자원 할당에 제약의 원인이 되므로, libvirt Pod 는 호스트 권한을 사용하여 이 계층을 벗어나,
+ 직접 cgroup 을 생성하고 libvirtd 의 cgroup 을 system.slice 아래로 이동시킵니다.
.. code-block:: console
@@ -59,7 +61,7 @@ libvirtd는 KVM 제어와 장치 할당을 위해 호스트 권한이 필요합
#. ``cgcreate`` 로 cgroup 루트 아래에 ``/osh-libvirt`` 를 직접 만듭니다.
#. ``cgexec`` 로 그 cgroup 으로 이동해 kubelet 이 만든 계층을 벗어난 뒤,
``systemd-run --scope --slice=system`` 을 통해 libvirtd 를 호스트 systemd 의
- ``system.slice`` 아래 scope에 새롭게 등록합니다.
+ ``system.slice`` 아래 scope 에 새롭게 등록합니다.
#. 컨테이너의 최초 프로세스는 ``systemd-run`` 으로 남아 libvirtd 를 감시합니다.
libvirtd 가 죽으면 함께 종료되고, Kubernetes 가 Pod 를 다시 띄웁니다.
@@ -68,31 +70,31 @@ libvirtd는 KVM 제어와 장치 할당을 위해 호스트 권한이 필요합
$ cat /proc//cgroup
0::/system.slice/run-rd2beada6c25e4baf90db578cc514c194.scope
-결과적으로 libvirtd는 ``system.slice`` 에 속한 데몬처럼 동작하면서도,
+결과적으로 libvirtd 는 ``system.slice`` 에 속한 데몬처럼 동작하면서도,
수명 주기는 Kubernetes 의 선언적 관리 아래 남습니다.
libvirtd 가 QEMU 프로세스를 생성하는 과정 (Double Fork & Machine Cgroup)
-------------------------------------------------------------------------------------
+------------------------------------------------------------------------
-libvirtd는 nova-compute로부터 받은 도메인 XML(vCPU, 메모리, 가상 디스크, NIC 설정 등)을
-해석해 QEMU를 구성하고 프로세스를 생성합니다.
+libvirtd 는 nova-compute 로부터 받은 도메인 XML(vCPU, 메모리, 가상 디스크, NIC 설정 등)을
+해석해 QEMU 를 구성하고 프로세스를 생성합니다.
-#. Double Fork와 서브리퍼(Subreaper) : libvirtd는 Double fork를 하고
- cgroup을 분리하여 QEMU를 생성합니다.
+#. Double Fork 와 서브리퍼(Subreaper) : libvirtd 는 Double fork 를 하고
+ cgroup 을 분리하여 QEMU 를 생성합니다.
이는 **libvirtd 가 재시작, 크래시해도 실행 중인 VM 이 함께 죽지 않도록** 독립시키기 위해서입니다.
double fork 과정에서 중간 프로세스가 종료되면서 QEMU 는 고아 프로세스가 되고,
가장 가까운 서브리퍼가 부모 프로세스로 매핑되게 됩니다.
-#. Machine cgroup 격리 : libvirtd는 system.slice에 위치하지만,
+#. Machine cgroup 격리 : libvirtd 는 system.slice 에 위치하지만,
생겨난 QEMU 프로세스는 호스트 cgroup 루트 직하의 가상화 전용 구역인 machine 계층으로 이동시킵니다.
- 이를 통해 시스템 데몬들과 VM의 자원을 격리하여 VM이 호스트 시스템에 영향을 주지 않도록 합니다.
+ 이를 통해 시스템 데몬들과 VM 의 자원을 격리하여 VM 이 호스트 시스템에 영향을 주지 않도록 합니다.
#. 보안 레이블 및 네임스페이스 :
- sVirt (SELinux/AppArmor): VM 간 이미지 무단 접근을 차단하기 위해
QEMU 프로세스와 디스크 파일에 고유 MCS 레이블을 부여합니다.
- - Mount Namespace: QEMU의 /dev 경로를 호스트와 분리하여
- 해당 VM에 허용된 가상 장치 파일만 노출합니다.
+ - Mount Namespace: QEMU 의 /dev 경로를 호스트와 분리하여
+ 해당 VM 에 허용된 가상 장치 파일만 노출합니다.
- 권한 축소: root 권한이 아닌 libvirt-qemu 유저/그룹 권한으로 실행 단계를 낮춥니다.
.. code-block:: console
@@ -115,19 +117,19 @@ libvirtd는 nova-compute로부터 받은 도메인 XML(vCPU, 메모리, 가상
위 cgroup 경로는 ``machine.slice`` 가 아니라
cgroup 루트 바로 아래의 ``machine`` 계층으로 관찰됩니다.
- Pod를 privileged 모드로 실행하더라도 기본적으로는 호스트의 systemd의 D-Bus에 접근할 수 없으므로,
- 호스트의 systemd에게 cgroup 등록을 요청할 수 없습니다.
- 따라서 libvirtd 는 직접 cgroupfs를 통해 cgroup의 /machine 계층에 QEMU를 등록합니다.
- 중요한 점은 백엔드가 systemd든 cgroupfs든 관계없이,
- QEMU가 배치되는 cgroup(/machine)은
- kubelet의 자원 추적 범위인 kubepods 계층과 격리되어 있다는 것입니다.
+ Pod 를 privileged 모드로 실행하더라도 기본적으로는 호스트의 systemd 의 D-Bus 에 접근할 수 없으므로,
+ 호스트의 systemd 에게 cgroup 등록을 요청할 수 없습니다.
+ 따라서 libvirtd 는 직접 cgroupfs 를 통해 cgroup 의 /machine 계층에 QEMU 를 등록합니다.
+ 중요한 점은 백엔드가 systemd 든 cgroupfs 든 관계없이,
+ QEMU 가 배치되는 cgroup(/machine)은
+ kubelet 의 자원 추적 범위인 kubepods 계층과 격리되어 있다는 것입니다.
QEMU 와 KVM 의 상호작용
-========================
+=======================
사전 개념 : CPU 동작 모드, 호스트 모드와 게스트 모드
--------------------------------------------------------------
+----------------------------------------------------
게스트 OS 도 스스로를 진짜 OS 로 인식하므로 Ring 0 권한으로 동작해야 하지만,
호스트의 진짜 Ring 0 을 그대로 주면 격리가 파괴됩니다.
@@ -140,10 +142,10 @@ Intel VT-x / AMD-V 는 이를 위해 물리 CPU 에 두 가지 동작 모드를
모드의 Ring 0 에서, 게스트 애플리케이션은 게스트 모드의 Ring 3 에서
동작합니다.
-vCPU의 동작 과정
+vCPU 의 동작 과정
-----------------
-vCPU는 게스트 OS 가 물리 CPU 로 인식하는 가상 CPU 로,
+vCPU 는 게스트 OS 가 물리 CPU 로 인식하는 가상 CPU 로,
실제로는 호스트의 물리 CPU 위에서 게스트 코드를 대신 실행하는 스레드입니다.
QEMU 는 vCPU 하나마다 호스트 스레드를 하나씩 만듭니다.
@@ -169,7 +171,7 @@ vCPU 스레드는 아래 과정을 무한 루프로 반복합니다.
스케줄링합니다.
메모리의 동작 과정
------------------------------
+------------------
QEMU 는 호스트 메모리 공간에서 VM 크기만큼의 메모리를 ``mmap`` 으로 확보합니다.
@@ -181,7 +183,7 @@ QEMU 는 "게스트 물리 주소(GPA) ↔ 호스트 가상(HVA) 주소" 대응
* 게스트 페이지 테이블 : 게스트 가상 주소(GVA) → 게스트 물리 주소(GPA)
* EPT : 게스트 물리 주소(GPA) → 호스트 물리 주소(HPA)
-* EPT 바이올레이션(Violation) : EPT는 초기에 비어있으며,
+* EPT 바이올레이션(Violation) : EPT 는 초기에 비어있으며,
게스트가 메모리에 접근할 때마다 EPT violation (VM-Exit)이 발생하여
KVM 커널이 페이지 매핑을 동적으로 채웁니다.
@@ -193,18 +195,18 @@ QEMU 는 "게스트 물리 주소(GPA) ↔ 호스트 가상(HVA) 주소" 대응
이 단계는 단순 메모리 쓰기이므로 VM-Exit 가 발생하지 않습니다.
* 요청을 모아 둔 후 게스트가 알림용 레지스터에 값을 쓰면 VM-Exit 가 발생합니다.
* KVM 커널이 해당 요청을 받고, I/O 완료 처리 등을 위해
- QEMU의 I/O 스레드로 제어권을 넘겨 처리합니다.
+ QEMU 의 I/O 스레드로 제어권을 넘겨 처리합니다.
* 작업 완료 신호는 게스트에 가상 인터럽트(vIRQ) 형태로 전달됩니다.
격리는 어떻게 이루어지는가
----------------------------
+--------------------------
VM 격리는 두 층위(하드웨어 및 호스트 OS)에서 동시에 작동합니다.
#. **하드웨어 수준의 격리** - 게스트 OS 가 허용되지 않은 메모리
주소나 CPU 특권 레지스터를 건드리는 즉시 물리 CPU 가 명령 실행을 즉시 거부하고
- VM-Exit을 발생시켜 제어권을 KVM 으로 강제 환수합니다.
+ VM-Exit 을 발생시켜 제어권을 KVM 으로 강제 환수합니다.
KVM 과 QEMU 는 정상적인 I/O 요청만 처리하고, 허용되지 않은 접근은 게스트
내부의 에러(Page Fault 등)로 되돌려 호스트를 보호합니다.
@@ -212,7 +214,7 @@ VM 격리는 두 층위(하드웨어 및 호스트 OS)에서 동시에 작동합
QEMU 프로세스는 호스트 OS 차원의 제한을 받습니다.
sVirt, 마운트 네임스페이스, 시스템 콜 제한(Seccomp),
자원 점유 제한(cgroup)을 겹겹이 적용하여 QEMU 프로세스 자체가 탈옥되더라도
- 피해가 호스트 시스템이나 다른 Pod/VM으로 확산되지 않도록 합니다.
+ 피해가 호스트 시스템이나 다른 Pod/VM 으로 확산되지 않도록 합니다.
.. list-table::
:header-rows: 1
@@ -248,11 +250,11 @@ VM 격리는 두 층위(하드웨어 및 호스트 OS)에서 동시에 작동합
가집니다.
-QEMU와 KVM의 동작 확인해 보기
-========================================
+QEMU 와 KVM 의 동작 확인해 보기
+===============================
QEMU 와 KVM 의 연결 확인
----------------------------
+------------------------
QEMU 프로세스가 열고 있는 파일 디스크립터 중 KVM 관련 항목만 봅니다.
@@ -272,8 +274,8 @@ QEMU 프로세스가 열고 있는 파일 디스크립터 중 KVM 관련 항목
* ``anon_inode:kvm-vcpu:0`` — vCPU 단위 제어. ``ioctl(KVM_RUN)`` 이 호출되는
대상이며, vCPU 마다 파일 디스크립터가 따로 있습니다.
-KVM을 통한 CPU 모드 전환 관찰
---------------------------------------------
+KVM 을 통한 CPU 모드 전환 관찰
+------------------------------
커널 트레이서로 실제 VM-Entry/Exit 를 볼 수 있습니다.
@@ -289,7 +291,7 @@ Register)을 읽거나 쓰려 해서 발생한 VM-Exit 입니다.
참고
-=====
+====
* :ref:`nova-hypervisor-registration` — 노드가 하이퍼바이저로 등록되는 과정
* :doc:`../foundations/vm-vs-container` — VM 과 컨테이너의 격리 방식 비교
diff --git a/doc/source/openstack-on-kubernetes/openstack-helm-network-outline.rst b/doc/source/openstack-on-kubernetes/openstack-helm-network-outline.rst
index 4adb78c..671ca8a 100644
--- a/doc/source/openstack-on-kubernetes/openstack-helm-network-outline.rst
+++ b/doc/source/openstack-on-kubernetes/openstack-helm-network-outline.rst
@@ -1,15 +1,16 @@
-================================================
-openstack-helm으로 구축한 환경의 네트워크 구조
-================================================
+===============================================
+openstack-helm 으로 구축한 환경의 네트워크 구조
+===============================================
+
개요
-----
+====
-해당 문서는 ``openstack-on-kubernetes-terraform`` 을 사용하여 처음 OpenStack을
+해당 문서는 ``openstack-on-kubernetes-terraform`` 을 사용하여 처음 OpenStack 을
설치한 사용자가 전체 네트워크 구조의 뼈대를 잡을 수 있도록 돕기 위한 목적으로
작성되었습니다.
`openstack-on-kubernetes-terraform`_ 에 작성된 단계에 따라 OpenStack 서비스를
-Kubernetes로 배포한 환경을 전제하고 있으며,
+Kubernetes 로 배포한 환경을 전제하고 있으며,
``make init → make up → make ready → make osh-deploy → make osh-vm`` 을
완료한 시점을 기준으로 네트워크 구조와 주요 구성 요소의 역할을 설명합니다.
@@ -18,8 +19,10 @@ Kubernetes로 배포한 환경을 전제하고 있으며,
설치 절차보다는 각 네트워크가 어디에 존재하고, 무엇과 연결되며,
어떤 구성 요소가 이를 관리하는지에 집중하여 작성되었습니다.
+CNI 와 Neutron 이 한 노드에서 공존하는 구조는
+:doc:`cni-and-neutron` 에서 개념으로 다룹니다.
-또한 openstack-helm을 통해 구축된 인프라의 전체 네트워크를
+또한 openstack-helm 을 통해 구축된 인프라의 전체 네트워크를
총 다섯 개의 하위 네트워크로 나누어서 구분하였습니다.
.. code-block:: text
@@ -33,7 +36,7 @@ Kubernetes로 배포한 환경을 전제하고 있으며,
└── Neutron Tenant VM Network
전체 네트워크
--------------
+=============
전체 네트워크의 구조를 간략하게 나타내면 다음과 같습니다.
@@ -51,28 +54,28 @@ Kubernetes로 배포한 환경을 전제하고 있으며,
└── Neutron Tenant Network
└── test-vm
-하나의 EC2 Host 안에는 OpenStack 서비스를 실행하는 Kubernetes Network와
-Tenant VM의 패킷을 전달하는 Open vSwitch Data Plane이 함께 구성됩니다.
+하나의 EC2 Host 안에는 OpenStack 서비스를 실행하는 Kubernetes Network 와
+Tenant VM 의 패킷을 전달하는 Open vSwitch Data Plane 이 함께 구성됩니다.
-``OpenStack API를 호출하는 요청`` 은 Kubernetes Service를 통해 Nova,
-Keystone 등의 OpenStack Service Pod로 전달됩니다.
-OpenStack 서비스 사이의 API 요청과 내부 메시지도 Kubernetes Network를
+**OpenStack API 를 호출하는 요청** 은 Kubernetes Service 를 통해 Nova,
+Keystone 등의 OpenStack Service Pod 로 전달됩니다.
+OpenStack 서비스 사이의 API 요청과 내부 메시지도 Kubernetes Network 를
통해 전달됩니다.
-반면 Tenant VM으로 향하거나 Tenant VM에서 나오는 패킷은
-OpenStack API Pod를 통과하지 않습니다.
-Neutron이 정의한 Network와 Port 상태가 Open vSwitch에 반영되면,
-``test-vm`` 이 송수신하는 패킷은 Open vSwitch Data Plane을 통해
+반면 Tenant VM 으로 향하거나 Tenant VM 에서 나오는 패킷은
+OpenStack API Pod 를 통과하지 않습니다.
+Neutron 이 정의한 Network 와 Port 상태가 Open vSwitch 에 반영되면,
+``test-vm`` 이 송수신하는 패킷은 Open vSwitch Data Plane 을 통해
Neutron Tenant Network 내부로 전달됩니다.
AWS Network
------------
+===========
-OpenStack과 Kubernetes가 실행되는 EC2는 ``10.0.0.0/16`` VPC의
-``10.0.1.0/24`` Public Subnet에 배치됩니다. EC2의 Primary ENI에는
-해당 Subnet의 Private IPv4가 할당됩니다.
+OpenStack 과 Kubernetes 가 실행되는 EC2 는 ``10.0.0.0/16`` VPC 의
+``10.0.1.0/24`` Public Subnet 에 배치됩니다. EC2 의 Primary ENI 에는
+해당 Subnet 의 Private IPv4 가 할당됩니다.
-AWS Cloud는 사용자가 구성하는 VPC 영역과 AWS가 운영하는 관리형 서비스
+AWS Cloud 는 사용자가 구성하는 VPC 영역과 AWS 가 운영하는 관리형 서비스
영역으로 구분할 수 있습니다.
.. code-block:: text
@@ -87,15 +90,15 @@ AWS Cloud는 사용자가 구성하는 VPC 영역과 AWS가 운영하는 관리
└── AWS 관리형 서비스
└── AWS Systems Manager
-Public Subnet의 Route Table에는
+Public Subnet 의 Route Table 에는
``0.0.0.0/0 → Internet Gateway`` 경로가 설정됩니다.
-EC2는 이 경로를 통해 패키지와 컨테이너 이미지를 내려받습니다.
+EC2 는 이 경로를 통해 패키지와 컨테이너 이미지를 내려받습니다.
-``본 배포에서 EC2의 Security Group은 아웃바운드 통신만 허용`` 하고 있으며
-인바운드 통신은 허용하고 있지 않습니다. 따라서 사용자는 EC2의
-Public IPv4나 SSH를 통해 직접 접속하지 않습니다.
+본 배포에서 EC2 의 Security Group 은 **아웃바운드 통신만 허용** 하고 있으며
+인바운드 통신은 허용하고 있지 않습니다. 따라서 사용자는 EC2 의
+Public IPv4 나 SSH 를 통해 직접 접속하지 않습니다.
-EC2 내부의 SSM Agent가 AWS Systems Manager에 아웃바운드 관리 채널을
+EC2 내부의 SSM Agent 가 AWS Systems Manager 에 아웃바운드 관리 채널을
생성하며, ``make ssm`` 과 OpenStack 배포 명령도 이 채널을 통해 전달됩니다.
.. list-table::
@@ -105,25 +108,25 @@ EC2 내부의 SSM Agent가 AWS Systems Manager에 아웃바운드 관리 채널
* - 구성 요소
- 역할
* - VPC
- - EC2가 배치되는 10.0.0.0/16 AWS 가상 네트워크
+ - EC2 가 배치되는 10.0.0.0/16 AWS 가상 네트워크
* - Public Subnet
- - EC2의 Primary ENI가 배치되는 10.0.1.0/24 주소 대역
+ - EC2 의 Primary ENI 가 배치되는 10.0.1.0/24 주소 대역
* - Internet Gateway
- - Public Subnet과 외부 네트워크 사이의 통신 경로
+ - Public Subnet 과 외부 네트워크 사이의 통신 경로
* - Primary ENI
- - AWS Network와 EC2 Host Network 간 연결
+ - AWS Network 와 EC2 Host Network 간 연결
* - Security Group
- 인바운드 차단 및 모든 아웃바운드 통신 허용
* - AWS Systems Manager
- SSH 없는 EC2 명령 전달 및 관리 세션 생성
EC2 Host Network
-----------------
+================
-EC2 Host Network는 AWS Network, Kubernetes Network 및
-Neutron Tenant VM Network가 함께 존재하는 호스트 내부 네트워크입니다.
+EC2 Host Network 는 AWS Network, Kubernetes Network 및
+Neutron Tenant VM Network 가 함께 존재하는 호스트 내부 네트워크입니다.
-본 프로젝트에서는 하나의 EC2가 ``Kubernetes Node`` 이자
+본 프로젝트에서는 하나의 EC2 가 ``Kubernetes Node`` 이자
``OpenStack Compute Host`` 역할을 수행합니다.
.. code-block:: text
@@ -144,24 +147,25 @@ Neutron Tenant VM Network가 함께 존재하는 호스트 내부 네트워크
└── provider1
└── Linux Dummy Interface
-``Primary Network Interface`` 는 AWS의 Primary ENI에 대응하며,
-EC2 운영체제와 AWS VPC를 연결합니다.
+``Primary Network Interface`` 는 AWS 의 Primary ENI 에 대응하며,
+EC2 운영체제와 AWS VPC 를 연결합니다.
-``Open vSwitch`` 는 여러 VM이 같은 Tenant Network에서 통신할 수 있도록
+``Open vSwitch`` 는 여러 VM 이 같은 Tenant Network 에서 통신할 수 있도록
EC2 Host 안에 가상 스위치 구조를 만듭니다.
-Neutron OVS Agent는 Neutron에 정의된 Network와 Port 정보를 바탕으로
-Open vSwitch의 Bridge와 연결 상태를 구성합니다.
+Neutron OVS Agent 는 Neutron 에 정의된 Network 와 Port 정보를 바탕으로
+Open vSwitch 의 Bridge 와 연결 상태를 구성합니다.
-``br-int`` 는 여러 VM의 Virtual NIC가 연결되는 중심 Bridge입니다.
-같은 Tenant Network에 속한 VM과 DHCP Port 사이의 패킷을 전달합니다.
+``br-int`` 는 여러 VM 의 Virtual NIC 가 연결되는 중심 Bridge 입니다.
+같은 Tenant Network 에 속한 VM 과 DHCP Port 사이의 패킷을 전달합니다.
-``br-tun`` 은 서로 다른 Compute Host 사이에서 Tenant Network의 패킷을
-VXLAN으로 전달할 때 사용됩니다. 현재는 단일 Compute Host 환경이므로
+``br-tun`` 은 서로 다른 Compute Host 사이에서 Tenant Network 의 패킷을
+:term:`VXLAN` 으로 전달할 때 사용됩니다. 현재는 단일 Compute Host 환경이므로
실제 Host 간 VXLAN Tunnel 트래픽은 발생하지 않습니다.
-``br-ex`` 는 VM이 Provider Network나 외부 네트워크로 접근할 때 사용하는
-Bridge입니다. 본 배포에서는 실제 외부 NIC 대신 ``provider1`` Dummy Interface가
-연결되므로 AWS VPC나 인터넷으로 이어지는 외부 경로는 구성되지 않습니다.
+``br-ex`` 는 VM 이 Provider Network 나 외부 네트워크로 접근할 때 사용하는
+Bridge 입니다. 본 배포에서는 실제 외부 NIC 대신 ``provider1`` Dummy
+Interface 가 연결되므로 AWS VPC 나 인터넷으로 이어지는 외부 경로는 구성되지
+않습니다.
.. list-table::
:header-rows: 1
@@ -170,22 +174,22 @@ Bridge입니다. 본 배포에서는 실제 외부 NIC 대신 ``provider1`` Dumm
* - 구성 요소
- 역할
* - Primary Network Interface
- - AWS VPC와 EC2 Host Network 간 연결
+ - AWS VPC 와 EC2 Host Network 간 연결
* - Linux Network Stack
- - Host의 Routing 및 패킷 전달 처리
+ - Host 의 Routing 및 패킷 전달 처리
* - Neutron OVS Agent
- Neutron Network 상태의 OVS Bridge·Port·Flow 구현
* - br-int
- - VM Port와 Neutron Tenant Network 간 연결
+ - VM Port 와 Neutron Tenant Network 간 연결
* - br-tun
- VXLAN Segment 및 다중 Compute Host 간 Tunnel 처리
* - br-ex
- - Neutron Provider Network의 Host 측 연결 지점
+ - Neutron Provider Network 의 Host 측 연결 지점
* - provider1
- - 실제 외부 NIC를 대신해 br-ex에 연결된 Dummy Interface
+ - 실제 외부 NIC 를 대신해 br-ex 에 연결된 Dummy Interface
-``br_netfilter`` 와 ``net.ipv4.ip_forward = 1`` 은 별도의 Network Interface가
-아니라 Linux Kernel의 패킷 처리 설정입니다.
+``br_netfilter`` 와 ``net.ipv4.ip_forward = 1`` 은 별도의 Network Interface 가
+아니라 Linux Kernel 의 패킷 처리 설정입니다.
.. code-block:: text
@@ -196,16 +200,16 @@ Bridge입니다. 본 배포에서는 실제 외부 NIC 대신 ``provider1`` Dumm
└── 서로 다른 Interface와 Network Namespace 사이의 패킷 전달 허용
Kubernetes Network
-------------------
+==================
-Kubernetes Network는 Node Communication, Pod Network, Service Network라는
+Kubernetes Network 는 Node Communication, Pod Network, Service Network 라는
서로 다른 역할의 영역으로 나누어 이해할 수 있습니다.
-Node Communication은 Kubernetes Node 자체의 통신을 담당하고,
-Pod Network는 일반 Pod에 독립된 IP와 통신 환경을 제공합니다.
-Service Network는 여러 Pod를 하나의 고정된 가상 주소로 연결합니다.
+Node Communication 은 Kubernetes Node 자체의 통신을 담당하고,
+Pod Network 는 일반 Pod 에 독립된 IP 와 통신 환경을 제공합니다.
+Service Network 는 여러 Pod 를 하나의 고정된 가상 주소로 연결합니다.
-본 프로젝트에서는 하나의 EC2가 단일 Kubernetes Node로 사용되므로
+본 프로젝트에서는 하나의 EC2 가 단일 Kubernetes Node 로 사용되므로
Node 간 통신은 발생하지 않습니다.
.. code-block:: text
@@ -228,19 +232,19 @@ Node 간 통신은 발생하지 않습니다.
└── ClusterIP
└── Endpoint Pod IP로 전달
-``Node Communication`` 에서는 EC2의 Primary Private IPv4인 ``10.0.1.x`` 가
-Node InternalIP로 사용됩니다. Kubernetes 전체를 대표하는 별도의
-Network Interface가 생성되는 것은 아닙니다.
+``Node Communication`` 에서는 EC2 의 Primary Private IPv4 인 ``10.0.1.x`` 가
+Node InternalIP 로 사용됩니다. Kubernetes 전체를 대표하는 별도의
+Network Interface 가 생성되는 것은 아닙니다.
-``Pod Network`` 에서는 일반 Pod에 독립된 Network Namespace와 ``eth0`` 이
-구성되고, ``192.168.0.0/16`` 범위에서 개별 IP가 할당됩니다.
-본 프로젝트에서는 Calico CNI가 Pod Network를 구성합니다.
+``Pod Network`` 에서는 일반 Pod 에 독립된 Network Namespace 와 ``eth0`` 이
+구성되고, ``192.168.0.0/16`` 범위에서 개별 IP 가 할당됩니다.
+본 프로젝트에서는 :term:`Calico` CNI 가 Pod Network 를 구성합니다.
-``Service Network`` 는 Pod IP가 변경되더라도 동일한 주소로 접근할 수 있도록
-ClusterIP를 제공합니다. 본 프로젝트는 Service CIDR을 별도로 지정하지
+``Service Network`` 는 Pod IP 가 변경되더라도 동일한 주소로 접근할 수 있도록
+ClusterIP 를 제공합니다. 본 프로젝트는 Service CIDR 을 별도로 지정하지
않으므로 kubeadm 기본값인 ``10.96.0.0/12`` 를 사용합니다.
-``kube-proxy`` 는 ClusterIP로 들어온 요청을 실제 Endpoint Pod IP와 Port로
+``kube-proxy`` 는 ClusterIP 로 들어온 요청을 실제 Endpoint Pod IP 와 Port 로
전달하는 규칙을 구성합니다.
.. list-table::
@@ -250,34 +254,34 @@ ClusterIP를 제공합니다. 본 프로젝트는 Service CIDR을 별도로 지
* - 구성 요소
- 역할
* - Node InternalIP
- - Kubernetes의 Node 식별 주소
+ - Kubernetes 의 Node 식별 주소
* - Primary Network Interface
- - Node InternalIP의 기반이 되는 Private IPv4 보유 EC2 Host Interface
+ - Node InternalIP 의 기반이 되는 Private IPv4 보유 EC2 Host Interface
* - Pod CIDR
- 일반 Pod IP 할당을 위한 192.168.0.0/16 주소 범위
* - Calico CNI
- - 일반 Pod의 Network Namespace·Interface·IP·통신 경로 구성
+ - 일반 Pod 의 Network Namespace·Interface·IP·통신 경로 구성
* - Pod eth0
- - 일반 Pod의 기본 패킷 송수신 Network Interface
+ - 일반 Pod 의 기본 패킷 송수신 Network Interface
* - Service CIDR
- ClusterIP 할당을 위한 10.96.0.0/12 주소 범위(kubeadm 기본값)
* - ClusterIP
- - 여러 Endpoint Pod를 대표하는 고정 가상 주소
+ - 여러 Endpoint Pod 를 대표하는 고정 가상 주소
* - kube-proxy
- ClusterIP 요청의 Endpoint Pod 전달 규칙 구성
.. note::
- ClusterIP는 특정 Network Interface에 직접 할당되는 실제 IP가 아닙니다.
- kube-proxy가 전달 규칙을 구성하고, 실제 패킷 변환과 전달은
- Linux Kernel이 수행합니다.
+ ClusterIP 는 특정 Network Interface 에 직접 할당되는 실제 IP 가 아닙니다.
+ kube-proxy 가 전달 규칙을 구성하고, 실제 패킷 변환과 전달은
+ Linux Kernel 이 수행합니다.
OpenStack Service Network
--------------------------
+=========================
-OpenStack Service Network는 OpenStack API Service와
-Kubernetes Pod 위에 배포된 openstack Service가 통신하는 네트워크 영역입니다.
+OpenStack Service Network 는 OpenStack API Service 와
+Kubernetes Pod 위에 배포된 openstack Service 가 통신하는 네트워크 영역입니다.
.. code-block:: text
@@ -299,14 +303,14 @@ Kubernetes Pod 위에 배포된 openstack Service가 통신하는 네트워크
│
└── ...
-``openstack Namespace`` 는 OpenStack 관련 Kubernetes Resource를
+``openstack Namespace`` 는 OpenStack 관련 Kubernetes Resource 를
구분하고 관리하는 논리적 범위입니다.
-각 OpenStack API는 Kubernetes Service를 통해 노출됩니다.
-Service는 고정된 DNS 이름과 ClusterIP를 제공하며,
-해당 Service로 전달된 요청을 연결된 API Pod로 전달합니다.
+각 OpenStack API 는 Kubernetes Service 를 통해 노출됩니다.
+Service 는 고정된 DNS 이름과 ClusterIP 를 제공하며,
+해당 Service 로 전달된 요청을 연결된 API Pod 로 전달합니다.
-``osc`` Pod는 Keystone, Glance, Nova 및 Neutron Service에
+``osc`` Pod 는 Keystone, Glance, Nova 및 Neutron Service 에
API 요청을 보냅니다.
.. code-block:: text
@@ -315,11 +319,11 @@ API 요청을 보냅니다.
└── OpenStack Service
└── OpenStack API Pod
-이 과정에서 Service의 ClusterIP로 전달된 요청은
-Node의 Linux Network Stack에서 kube-proxy가 구성한 전달 규칙에 따라
-해당 Service의 Endpoint Pod IP로 변환됩니다.
+이 과정에서 Service 의 ClusterIP 로 전달된 요청은
+Node 의 Linux Network Stack 에서 kube-proxy 가 구성한 전달 규칙에 따라
+해당 Service 의 Endpoint Pod IP 로 변환됩니다.
-변환된 패킷은 Kubernetes Pod Network를 통해 대상 Pod로 전달됩니다.
+변환된 패킷은 Kubernetes Pod Network 를 통해 대상 Pod 로 전달됩니다.
.. list-table::
:header-rows: 1
@@ -328,32 +332,32 @@ Node의 Linux Network Stack에서 kube-proxy가 구성한 전달 규칙에 따
* - 구성 요소
- 역할
* - openstack Namespace
- - OpenStack 관련 Kubernetes Resource의 논리적 관리 범위
+ - OpenStack 관련 Kubernetes Resource 의 논리적 관리 범위
* - osc Pod
- OpenStack API 요청을 보내는 Client Pod
* - OpenStack Service
- OpenStack API 접근을 위한 DNS 이름과 ClusterIP 제공
* - OpenStack API Pod
- - Service를 통해 전달된 OpenStack API 요청 처리
+ - Service 를 통해 전달된 OpenStack API 요청 처리
Neutron Tenant VM Network
--------------------------
+=========================
-Neutron Tenant VM Network는 OpenStack VM에 독립된 IP와
+Neutron Tenant VM Network 는 OpenStack VM 에 독립된 IP 와
Layer 2 통신 환경을 제공하는 Data Plane 네트워크입니다.
-Tenant Network는 OpenStack 사용자가 VM을 연결하기 위해 생성하는
+Tenant Network 는 OpenStack 사용자가 VM 을 연결하기 위해 생성하는
논리적인 가상 네트워크입니다.
-같은 Tenant Network에 연결된 VM은 동일한 Layer 2 네트워크에 속하며,
-다른 Network와 분리된 환경에서 통신합니다.
+같은 Tenant Network 에 연결된 VM 은 동일한 Layer 2 네트워크에 속하며,
+다른 Network 와 분리된 환경에서 통신합니다.
-Neutron Server는 Network, Subnet 및 Port 정보를 관리하고,
-Neutron Agent는 해당 정보를 EC2 Host의 네트워크 구조에 반영합니다.
+Neutron Server 는 Network, Subnet 및 Port 정보를 관리하고,
+Neutron Agent 는 해당 정보를 EC2 Host 의 네트워크 구조에 반영합니다.
본 환경의 ``demo-net``, ``demo-subnet`` 및 ``test-vm`` 은
-VM 생성과 Tenant Network의 동작을 확인하기 위한 테스트용 Resource입니다.
+VM 생성과 Tenant Network 의 동작을 확인하기 위한 테스트용 Resource 입니다.
-이 절에서는 해당 구성을 기준으로 Tenant Network의 구조와
+이 절에서는 해당 구성을 기준으로 Tenant Network 의 구조와
VM 패킷 전달 경로를 설명합니다.
.. code-block:: text
@@ -369,18 +373,18 @@ VM 패킷 전달 경로를 설명합니다.
│
└── VM Data Path
-``demo-net`` 은 ``test-vm`` 이 연결되는 테스트용 Tenant Network입니다.
+``demo-net`` 은 ``test-vm`` 이 연결되는 테스트용 Tenant Network 입니다.
-Neutron Agent가 Network와 Port 정보를 EC2 Host에 반영하면,
-VM 패킷을 전달하기 위한 Open vSwitch Data Plane이 구성됩니다.
+Neutron Agent 가 Network 와 Port 정보를 EC2 Host 에 반영하면,
+VM 패킷을 전달하기 위한 Open vSwitch Data Plane 이 구성됩니다.
-``test-vm`` 은 Neutron Port를 통해 ``demo-net`` 에 연결됩니다.
-Neutron Port에는 VM에 할당된 Fixed IP와 MAC Address가 저장되며,
-VM과 Tenant Network의 연결을 나타냅니다.
+``test-vm`` 은 Neutron Port 를 통해 ``demo-net`` 에 연결됩니다.
+Neutron Port 에는 VM 에 할당된 Fixed IP 와 MAC Address 가 저장되며,
+VM 과 Tenant Network 의 연결을 나타냅니다.
-VM의 Virtual NIC는 EC2 Host에 생성된 TAP Interface와 연결됩니다.
-TAP Interface로 전달된 패킷은 ``qbr`` 와 ``qvb``·``qvo`` 를 거쳐
-Open vSwitch의 ``br-int`` 로 전달됩니다.
+VM 의 Virtual NIC 는 EC2 Host 에 생성된 TAP Interface 와 연결됩니다.
+TAP Interface 로 전달된 패킷은 ``qbr`` 와 ``qvb``·``qvo`` 를 거쳐
+Open vSwitch 의 ``br-int`` 로 전달됩니다.
.. code-block:: text
@@ -392,7 +396,7 @@ Open vSwitch의 ``br-int`` 로 전달됩니다.
└── demo-net의 다른 Port
이 경로는 VM 패킷에 Host Network 규칙을 적용한 뒤,
-같은 Tenant Network에 연결된 다른 Port로 전달하기 위해 사용됩니다.
+같은 Tenant Network 에 연결된 다른 Port 로 전달하기 위해 사용됩니다.
.. list-table::
:header-rows: 1
@@ -405,31 +409,31 @@ Open vSwitch의 ``br-int`` 로 전달됩니다.
* - demo-subnet
- 10.10.10.0/24 주소 범위와 DHCP 설정을 제공하는 테스트용 Subnet
* - Neutron Port
- - VM의 Fixed IP·MAC Address·Network 연결 정의
+ - VM 의 Fixed IP·MAC Address·Network 연결 정의
* - TAP Interface
- - VM Virtual NIC와 EC2 Host Network Data Plane 간 연결
+ - VM Virtual NIC 와 EC2 Host Network Data Plane 간 연결
* - qbr·qvb·qvo
- - Host Network 규칙 적용 및 TAP Interface와 br-int 사이의 연결 경로
+ - Host Network 규칙 적용 및 TAP Interface 와 br-int 사이의 연결 경로
* - br-int
- - 같은 Tenant Network에 연결된 Port 사이의 Layer 2 패킷 전달
+ - 같은 Tenant Network 에 연결된 Port 사이의 Layer 2 패킷 전달
* - br-tun
- - VXLAN Segment와 다중 Compute Host 간 Tunnel 처리
+ - VXLAN Segment 와 다중 Compute Host 간 Tunnel 처리
* - DHCP Namespace
- - demo-subnet에 연결된 VM을 대상으로 DHCP 응답 제공
+ - demo-subnet 에 연결된 VM 을 대상으로 DHCP 응답 제공
-``demo-net`` 이 VXLAN Network로 구성된 경우,
+``demo-net`` 이 VXLAN Network 로 구성된 경우,
``br-tun`` 은 서로 다른 Compute Host 사이의 VXLAN Tunnel 처리에
사용됩니다.
현재는 단일 Compute Host 환경이므로
-다른 Compute Host로 전달되는 VXLAN Tunnel 트래픽은 발생하지 않습니다.
+다른 Compute Host 로 전달되는 VXLAN Tunnel 트래픽은 발생하지 않습니다.
-``br-ex`` 와 ``provider1`` 은 Provider Network를 위한 Host 측 구성입니다.
-현재 환경에는 External Network, Neutron Router 및 Floating IP가 없으므로
+``br-ex`` 와 ``provider1`` 은 Provider Network 를 위한 Host 측 구성입니다.
+현재 환경에는 External Network, Neutron Router 및 Floating IP 가 없으므로
``demo-net`` 과 ``br-ex`` 사이의 패킷 전달 경로는 구성되지 않습니다.
.. note::
- 현재 ``test-vm`` 은 ``demo-net`` 내부 통신과 DHCP를 사용할 수 있지만,
- Neutron Router를 통한 외부 연결이 없으므로 AWS VPC나 인터넷에는
+ 현재 ``test-vm`` 은 ``demo-net`` 내부 통신과 DHCP 를 사용할 수 있지만,
+ Neutron Router 를 통한 외부 연결이 없으므로 AWS VPC 나 인터넷에는
접근할 수 없습니다.
diff --git a/doc/source/openstack-on-kubernetes/openstack-helm.rst b/doc/source/openstack-on-kubernetes/openstack-helm.rst
index 559d723..c49ddb1 100644
--- a/doc/source/openstack-on-kubernetes/openstack-helm.rst
+++ b/doc/source/openstack-on-kubernetes/openstack-helm.rst
@@ -2,8 +2,9 @@
openstack-helm
==============
-`openstack-helm `_ 은 OpenStack
-서비스를 Helm chart 로 패키징하여 Kubernetes 위에 배포하는 프로젝트입니다.
+`openstack-helm `_ 은
+OpenStack 서비스를 Helm chart 로 패키징하여 Kubernetes 위에 배포하는
+프로젝트입니다.
.. note::
@@ -54,8 +55,20 @@ openstack-helm 운영의 실질 핵심은 chart 기본값을 환경에 맞게
블록별 설명 보강.
+chart 하나를 예로 들어 values 가 실제 Kubernetes 리소스로 바뀌는 과정을
+따라가려면 :doc:`neutron-helm-chart` 를 참고하세요.
+
+
GitOps 연계
===========
FluxCD/ArgoCD 와 결합하여 선언적 배포와 Day-2 운영을 자동화하는 방법은
:doc:`operations` 에서 다룹니다.
+
+
+관련 문서
+=========
+
+* :doc:`neutron-helm-chart` — neutron chart 의 파일 구성과 리소스 매핑
+* :doc:`openstack-helm-network-outline` — 배포된 환경의 네트워크 구조
+* :doc:`../labs/openstack-helm-lab` — 단계별 실습
diff --git a/doc/source/openstack-on-kubernetes/operations.rst b/doc/source/openstack-on-kubernetes/operations.rst
index 4c7d226..e1f6a3d 100644
--- a/doc/source/openstack-on-kubernetes/operations.rst
+++ b/doc/source/openstack-on-kubernetes/operations.rst
@@ -1,6 +1,6 @@
-================
+============
운영 (Day-2)
-================
+============
배포가 끝이 아닙니다. 업그레이드, 모니터링, 백업/복구, 스케일링 등 배포
이후의 운영(Day-2)을 다룹니다.
diff --git a/doc/source/openstack-on-kubernetes/reference-architecture.rst b/doc/source/openstack-on-kubernetes/reference-architecture.rst
index 01073ca..1d1871d 100644
--- a/doc/source/openstack-on-kubernetes/reference-architecture.rst
+++ b/doc/source/openstack-on-kubernetes/reference-architecture.rst
@@ -1,6 +1,6 @@
-========================
+=================
레퍼런스 아키텍처
-========================
+=================
OpenStack on Kubernetes 를 멀티노드로 구성할 때의 노드 역할 분리와 최소
토폴로지, 리소스 산정 기준을 정리합니다. 실습(:doc:`../labs/index`)에 앞서 잡아
diff --git a/doc/source/storage/cinder.rst b/doc/source/storage/cinder.rst
index add1b3e..28bac88 100644
--- a/doc/source/storage/cinder.rst
+++ b/doc/source/storage/cinder.rst
@@ -1,9 +1,9 @@
-=========================
+======================
Cinder (블록 스토리지)
-=========================
+======================
Cinder 는 OpenStack 의 블록 스토리지 서비스입니다. 이 문서는 서비스 자체를
-다루며, K8s 에서 CSI 로 소비하는 관점은
+다루며, Kubernetes 에서 CSI 로 소비하는 관점은
:doc:`../kubernetes-on-openstack/cinder-csi` 에서 다룹니다.
.. note::
diff --git a/doc/source/storage/index.rst b/doc/source/storage/index.rst
index 0ff0794..16d74ee 100644
--- a/doc/source/storage/index.rst
+++ b/doc/source/storage/index.rst
@@ -4,7 +4,7 @@
OpenStack 의 스토리지 서비스를 다룹니다. 블록 스토리지(Cinder)와 오브젝트
스토리지(Swift), 그리고 두 스택이 공유하는 통합 백엔드 Ceph 를 포함합니다.
-K8s 와의 연동(Cinder CSI 등)은 통합 패턴 섹션에서 다룹니다.
+Kubernetes 와의 연동(Cinder CSI 등)은 통합 패턴 섹션에서 다룹니다.
.. toctree::
:maxdepth: 1
diff --git a/doc/source/storage/swift.rst b/doc/source/storage/swift.rst
index b3308b5..2da4e12 100644
--- a/doc/source/storage/swift.rst
+++ b/doc/source/storage/swift.rst
@@ -1,6 +1,6 @@
-============================
+=========================
Swift (오브젝트 스토리지)
-============================
+=========================
Swift 는 OpenStack 의 오브젝트 스토리지 서비스입니다. Kubernetes 생태계에서도
여러 용도로 쓰입니다.
diff --git a/doc/source/translation-i18n/index.rst b/doc/source/translation-i18n/index.rst
index 462b6e6..3165509 100644
--- a/doc/source/translation-i18n/index.rst
+++ b/doc/source/translation-i18n/index.rst
@@ -1,6 +1,6 @@
-================
+=============
번역 · 국제화
-================
+=============
번역과 국제화(i18n/l10n)를 다룹니다. 두 오픈소스 기술을 직접 이해한 상태에서
공식 문서를 100% 한글화하고, 번역 플랫폼과 AI 보조 번역 워크플로우를
diff --git a/doc/source/translation-i18n/kubernetes-localization.rst b/doc/source/translation-i18n/kubernetes-localization.rst
index c060ac7..5e3e88d 100644
--- a/doc/source/translation-i18n/kubernetes-localization.rst
+++ b/doc/source/translation-i18n/kubernetes-localization.rst
@@ -1,6 +1,6 @@
-========================
+=================
Kubernetes 현지화
-========================
+=================
Kubernetes 문서는 언어별 디렉터리와 SIG Docs Localization 하위 그룹을 통해
현지화됩니다. OpenStack i18n 과는 도구·프로세스가 다릅니다.
diff --git a/doc/source/translation-i18n/localization-communities.rst b/doc/source/translation-i18n/localization-communities.rst
index ff2ea5d..45028ea 100644
--- a/doc/source/translation-i18n/localization-communities.rst
+++ b/doc/source/translation-i18n/localization-communities.rst
@@ -1,9 +1,10 @@
-================================================
+=============================================
두 한글화 공동체의 만남: I18n SIG 와 SIG Docs
-================================================
+=============================================
:doc:`../introduction/history-and-sigs` 에서 살펴본 것처럼, OpenStack 과
-Kubernetes 두 커뮤니티는 기술 통합을 위해 SIG(Special Interest Group)라는
+Kubernetes 두 커뮤니티는 기술 통합을 위해
+특별 관심 그룹(Special Interest Group, SIG)이라는
형태로 공식적으로 만났습니다. 흥미롭게도 **문서 한글화** 영역에서도 같은
구도가 나타납니다. 두 프로젝트는 각각 번역·현지화를 책임지는 공동체를 두고
있으며, 본 프로젝트의 한글화 작업은 이 두 공동체가 만나는 지점에 서 있습니다.
diff --git a/doc/source/translation-i18n/openstack-i18n.rst b/doc/source/translation-i18n/openstack-i18n.rst
index bbb9e3f..601d4cf 100644
--- a/doc/source/translation-i18n/openstack-i18n.rst
+++ b/doc/source/translation-i18n/openstack-i18n.rst
@@ -16,7 +16,7 @@ OpenStack 의 국제화는 **i18n SIG** 가 주도합니다
=========
* OpenStack I18n Contributor Guide —
- https://docs.openstack.org/i18n/
+ https://docs.openstack.org/i18n/latest/
번역 파이프라인 개요
diff --git a/doc/source/translation-i18n/weblate.rst b/doc/source/translation-i18n/weblate.rst
index a83d203..28a752c 100644
--- a/doc/source/translation-i18n/weblate.rst
+++ b/doc/source/translation-i18n/weblate.rst
@@ -2,7 +2,7 @@
Weblate
=======
-`Weblate `_ 는 웹 기반 번역 플랫폼입니다.
+`Weblate `_ 는 웹 기반 번역 플랫폼입니다.
본 프로젝트의 한글 문서는 한국어를 원문으로 하고, Weblate 를 통해
영어로 번역됩니다.
diff --git a/tox.ini b/tox.ini
index 3697ba5..b1de475 100644
--- a/tox.ini
+++ b/tox.ini
@@ -19,6 +19,11 @@ commands =
sphinx-build -W --keep-going -b html -D language=en \
doc/source doc/build/html/en
+[testenv:linkcheck]
+description = 문서의 외부 링크가 살아 있는지 검사합니다.
+commands =
+ sphinx-build -b linkcheck doc/source doc/build/linkcheck
+
[testenv:gettext]
description = 번역 대상 문자열을 .pot 카탈로그로 추출합니다.
commands =