From d51cf4b62f36314eccdeaf56bd9b79748debe777 Mon Sep 17 00:00:00 2001 From: eunjeong Park Date: Wed, 23 Sep 2026 09:52:52 +0900 Subject: [PATCH 1/2] Unify writing style and terminology across the docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pages had drifted into two Korean writing styles and several spellings for the same thing, so they read like they came from different projects. Move the four remaining 한다체 documents to 합니다체 and leave the glossary in its dictionary style. Put a space between a Latin word and the Korean particle that follows it, the way most of the docs already did. Settle on the glossary headwords for Pod, VM, Octavia, openstack-helm and Kubernetes. ovn-ovs and openstack-helm-network-outline used '-' for their top-level sections, which contradicts CONTRIBUTING, so promote them to '=' and size every title decoration to the width of its title. Point the eight redirecting links at their final URLs, turn two sentences wrapped in inline literals into bold text, replace the one :code: role with an inline literal, and let the numbered list number itself. Add the terms the newer pages already use - libvirt, KVM, QEMU, cgroup, VXLAN, ML2, Placement, Horizon, Calico, Kubespray, kOps, amphora - to the glossary and link first mentions with :term:. The longest pages were reachable only through a toctree, so link them from the documents that lead into them. Rewrite the CSI component section, which listed kubelet as a CSI component and lost a sentence along the way. It is the controller and node plugins, with kubelet calling the node plugin over a UNIX socket. --- doc/source/contributing.rst | 4 +- .../kubernetes-doc-conventions.rst | 6 +- .../openstack-doc-conventions.rst | 4 +- .../documentation/rst-sphinx-basics.rst | 10 +- doc/source/foundations/bridging-concepts.rst | 32 +- doc/source/foundations/helm.rst | 22 +- doc/source/foundations/index.rst | 4 +- doc/source/foundations/kubernetes-csi.rst | 80 +++-- .../foundations/kubernetes-fundamentals.rst | 54 +-- .../foundations/openstack-fundamentals.rst | 174 +++++----- doc/source/foundations/openstack.rst | 6 +- doc/source/foundations/vm-vs-container.rst | 4 +- doc/source/glossary.rst | 85 ++++- doc/source/index.rst | 4 +- doc/source/integration-patterns.rst | 4 +- doc/source/introduction/history-and-sigs.rst | 7 +- doc/source/introduction/index.rst | 7 +- doc/source/introduction/learning-path.rst | 9 +- .../why-openstack-and-kubernetes.rst | 22 +- .../kubernetes-on-openstack/cinder-csi.rst | 8 +- .../cloud-provider-openstack.rst | 4 +- .../kubernetes-on-openstack/cluster-api.rst | 16 +- .../kubernetes-on-openstack/concepts.rst | 8 +- doc/source/kubernetes-on-openstack/magnum.rst | 8 +- .../octavia-load-balancer.rst | 6 +- doc/source/labs/index.rst | 4 +- .../labs/kubernetes-on-openstack-lab.rst | 7 +- doc/source/labs/openstack-helm-lab.rst | 10 +- doc/source/networking/index.rst | 6 +- doc/source/networking/load-balancing.rst | 8 +- doc/source/networking/neutron-basics.rst | 10 +- doc/source/networking/ovn-ovs.rst | 62 ++-- .../openstack-on-kubernetes/approaches.rst | 7 +- .../cni-and-neutron.rst | 309 +++++++++--------- .../openstack-on-kubernetes/comparison.rst | 13 +- .../openstack-on-kubernetes/concepts.rst | 17 +- .../openstack-on-kubernetes/gateway-api.rst | 8 +- doc/source/openstack-on-kubernetes/index.rst | 5 +- doc/source/openstack-on-kubernetes/kolla.rst | 17 +- .../openstack-on-kubernetes/metallb.rst | 8 +- .../neutron-helm-chart.rst | 45 +-- .../nova-libvirt-kvm.rst | 126 +++---- .../openstack-helm-network-outline.rst | 250 +++++++------- .../openstack-helm.rst | 17 +- .../openstack-on-kubernetes/operations.rst | 4 +- .../reference-architecture.rst | 4 +- doc/source/storage/cinder.rst | 6 +- doc/source/storage/index.rst | 2 +- doc/source/storage/swift.rst | 4 +- doc/source/translation-i18n/index.rst | 4 +- .../kubernetes-localization.rst | 4 +- .../localization-communities.rst | 7 +- .../translation-i18n/openstack-i18n.rst | 2 +- doc/source/translation-i18n/weblate.rst | 2 +- 54 files changed, 851 insertions(+), 705 deletions(-) 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/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 를 통해 영어로 번역됩니다. From 55286b42248ed5607e40a07fc6e30d0d36713515 Mon Sep 17 00:00:00 2001 From: eunjeong Park Date: Wed, 23 Sep 2026 09:52:57 +0900 Subject: [PATCH 2/2] Add a link check and write the style rules down Nothing checked the conventions the docs were meant to follow, so the same inconsistencies kept coming back. Add a linkcheck tox environment and run it in CI without failing the build, so broken links and redirects surface on their own. Write the Korean prose rules - sentence style, particle spacing, term notation on first use, preferred spellings - along with the markup and link rules into CONTRIBUTING, and add the matching items to the contributor and reviewer checklists. Drop sphinx.ext.intersphinx and its empty mapping; a comment says how to turn it back on when there is something to point at. --- .github/workflows/docs.yml | 4 ++ CONTRIBUTING.rst | 52 ++++++++++++++++--- doc/source/conf.py | 21 +++++--- .../documentation/review-guidelines.rst | 9 +++- tox.ini | 5 ++ 5 files changed, 78 insertions(+), 13 deletions(-) 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/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/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 =