From 3e386b715530a475a3dfee14a2a3ac1c9393940b Mon Sep 17 00:00:00 2001 From: dongjune8931 Date: Tue, 11 Aug 2026 12:51:10 +0900 Subject: [PATCH] Add declarative management and CRD concepts Explain the CRD and controller model with Magnum/CAPO and Metal3/Ironic as OpenStack integration examples. --- doc/source/foundations/bridging-concepts.rst | 4 + .../foundations/kubernetes-fundamentals.rst | 93 +++++++++++++++++-- 2 files changed, 91 insertions(+), 6 deletions(-) diff --git a/doc/source/foundations/bridging-concepts.rst b/doc/source/foundations/bridging-concepts.rst index aeba307..653bc3c 100644 --- a/doc/source/foundations/bridging-concepts.rst +++ b/doc/source/foundations/bridging-concepts.rst @@ -47,6 +47,8 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점 openstack-helm 을 비롯한 아래 여러 방식의 기반입니다. +.. _bridging-concepts-provisioning: + 배포·프로비저닝 ======================== @@ -70,6 +72,8 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점 - :doc:`../kubernetes-on-openstack/cluster-api` +.. _bridging-concepts-baremetal: + 베어메탈 (물리 서버) ======================== diff --git a/doc/source/foundations/kubernetes-fundamentals.rst b/doc/source/foundations/kubernetes-fundamentals.rst index 0a7f240..b29c0f7 100644 --- a/doc/source/foundations/kubernetes-fundamentals.rst +++ b/doc/source/foundations/kubernetes-fundamentals.rst @@ -50,15 +50,96 @@ Workloads 선언적 관리와 CRD ================= -.. todo:: +Kubernetes에서는 원하는 상태(desired state)를 리소스에 선언하고, +컨트롤러(Controller)가 현재 상태(current state)와 비교하여 두 상태가 +일치하도록 지속적으로 조정(reconciliation)합니다. + +OpenStack과 Kubernetes를 연동하는 일부 프로젝트에서는 이러한 선언적 관리 +방식을 사용하여 OpenStack API로 관리되는 인프라의 원하는 상태를 Kubernetes +리소스로 표현합니다. + +이때 사용자 정의 리소스 정의(CustomResourceDefinition, :term:`CRD`)는 +Kubernetes 기본 리소스로 표현하기 어려운 OpenStack 연동 대상을 새로운 +리소스 종류로 정의하는 데 사용됩니다. +사용자는 CRD를 통해 추가된 사용자 정의 리소스(Custom Resource)에 원하는 +상태를 선언합니다. + +이 연동 구조에서 컨트롤러나 :term:`오퍼레이터(Operator) ` 는 +사용자 정의 리소스를 감시하고, OpenStack API를 호출하여 선언된 상태가 실제 +인프라에 반영되도록 조정합니다. +CRD 자체가 OpenStack API를 호출하는 것이 아니라, 해당 리소스의 수명주기 +관리 로직을 가진 컨트롤러나 오퍼레이터가 상태 조정을 수행합니다. + +.. code-block:: text + + Custom Resource + -> Controller/Operator + -> OpenStack API + -> 실제 인프라 + +대표 사례 +--------- + +이 패턴을 OpenStack 연동에 적용한 대표 사례는 다음과 같습니다. +전체 연동 구조에서는 다음 영역에 해당합니다. + +* **Magnum과 Cluster API(CAPI)·Cluster API Provider OpenStack(CAPO)** — + :ref:`배포·프로비저닝 ` +* **Metal3와 Ironic** — + :ref:`베어메탈 (물리 서버) ` + + +Magnum CAPI 드라이버와 CAPO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Magnum의 CAPI 기반 드라이버는 CAPI와 CAPO의 사용자 정의 리소스를 생성하고, +CAPO 컨트롤러는 OpenStack API를 호출하여 Nova·Neutron 등의 +인프라를 조정합니다. - * CRD / Operator → Magnum 드라이버, Metal3 ``BareMetalHost`` 등 통합 - 프로젝트의 기반 (:doc:`bridging-concepts`) +.. code-block:: text + Magnum CAPI 드라이버 + -> Cluster API/CAPO 사용자 정의 리소스 + -> CAPI/CAPO 컨트롤러 + -> OpenStack API(Nova·Neutron 등) + -> Kubernetes 클러스터 인프라 + +이 대응 관계를 알면 Magnum API로 받은 클러스터 생성 요청이 CAPI 리소스로 +변환되는 단계와 CAPO가 실제 OpenStack 인프라를 조정하는 역할을 구분할 수 +있습니다. + +자세한 내용은 :doc:`../kubernetes-on-openstack/magnum` 과 +:doc:`../kubernetes-on-openstack/cluster-api` 를 참고합니다. + + +.. _kubernetes-fundamentals-metal3-ironic: + +Metal3와 Ironic +~~~~~~~~~~~~~~~~ + +:term:`Metal3` 는 ``BareMetalHost`` 리소스를 CRD로 제공합니다. +``BareMetalHost`` 는 OpenStack :term:`Ironic` 이 관리하는 물리 서버의 +원하는 상태를 표현합니다. + +Metal3의 Bare Metal Operator(BMO)는 Kubernetes 컨트롤러로서 +``BareMetalHost`` 를 감시하고 Ironic API를 호출하여 물리 서버의 검사와 +프로비저닝을 조정합니다. + +.. code-block:: text + + BareMetalHost -> BMO -> Ironic API -> 물리 서버 + +이 대응 관계를 알면 Kubernetes에 선언된 물리 서버의 상태와 Ironic이 +수행하는 실제 하드웨어 작업의 경계를 구분할 수 있습니다. 더 읽을거리 =========== -.. todo:: - - Kubernetes 공식 개념 문서(kubernetes.io/docs/concepts) 링크. +* `Kubernetes 객체 공식 문서 + `_ +* `컨트롤러 공식 문서 + `_ +* `Custom Resources 공식 문서 + `_ +* `Operator 패턴 공식 문서 + `_