> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/07-kubernetes-rancher.md). # Tích hợp Kubernetes & Rancher Chạy Kubernetes trên VergeOS không phải là phần gắn thêm — đó là một **tích hợp hạng nhất** được xây dựng từ bốn thành phần chuyên dụng (Docker Machine Driver, Rancher UI Extension, Cloud Controller Manager và CSI Driver), cộng thêm một Cluster Autoscaler tùy chọn cho các cụm do Rancher cung cấp, giúp Rancher (và bất kỳ triển khai RKE2/K3s nào) nhận biết đầy đủ về tính toán, lưu trữ và mạng của VergeOS. Thay vì coi VergeOS là một máy chủ VM đơn thuần, các thành phần này cho phép Kubernetes cung cấp nút, gắn lưu trữ bền vững và tạo bộ cân bằng tải thông qua các API gốc của VergeOS — chính những API đang vận hành dashboard. ## Yêu cầu tiên quyết Trước khi cài đặt tích hợp, hãy đảm bảo môi trường cung cấp: * Một **Rancher Server** cài đặt (v2.10+) với `kubectl` và `helm` các công cụ CLI * Một **máy ảo mẫu** chạy Ubuntu 24.04 với cloud-init đã được cài đặt (và khuyến nghị QEMU guest agent) * Một **khóa API VergeOS** được tạo dưới **Cài đặt người dùng** * Một mạng VergeOS đích với **DHCP được bật** — trình điều khiển phát hiện IP của nút qua QEMU guest agent và các VM đã nhân bản sẽ không nhận địa chỉ nếu không có DHCP * Đối với lưu trữ bền vững dựa trên block: một VM VergeOS trống có tên **`k8spool`** để chứa các ổ đĩa block nhàn rỗi (VM ID của nó được truyền vào Helm chart CSI tại thời điểm cài đặt; VM này không bao giờ cần khởi động) ## Tổng quan ngăn xếp Tích hợp Kubernetes của VergeOS được cung cấp dưới dạng bốn thành phần riêng biệt — Docker Machine Driver, Rancher UI Extension, Cloud Controller Manager và CSI Driver — mỗi thành phần chịu trách nhiệm cho một lớp của ngăn xếp, với Cluster Autoscaler tùy chọn dành cho các cụm do Rancher cung cấp: ```mermaid graph TB subgraph "Bảng điều khiển Rancher" UI["Tiện ích mở rộng UI
(các bảng vergeos)"] RC["Thông tin xác thực đám mây &
Cấu hình máy"] end subgraph "Cung cấp nút" DMD["Docker Machine Driver
(docker-machine-driver-vergeos)"] end subgraph "Cụm Kubernetes" CCM["Cloud Controller Manager
(vergeos-cloud-controller-manager)"] CSI["CSI Driver
(csi-vergeos)"] end subgraph "Nền tảng VergeOS" API["API REST VergeOS"] VM["Máy ảo & Mẫu"] VSAN["Lưu trữ vSAN / NAS"] NET["Mạng ảo"] end UI --> RC RC --> DMD DMD -->|"Nhân bản mẫu,
chèn khóa SSH"| API API --> VM CCM -->|"Vòng đời nút,
bộ cân bằng tải"| API API --> NET CSI -->|"Các volume bền vững"| API API --> VSAN ``` ### Docker Machine Driver Cung cấp các VM VergeOS làm nút Kubernetes — nhân bản mẫu, chèn khóa SSH, thay đổi kích thước đĩa và gắn mạng. ### Rancher UI Extension Hiển thị trực tiếp các bảng Cloud Credential và Machine Config dành riêng cho VergeOS trong dashboard Rancher. ### Cloud Controller Manager Đồng bộ trạng thái nút Kubernetes với vòng đời VM VergeOS và cung cấp các dịch vụ bộ cân bằng tải theo yêu cầu. ### CSI Driver Ánh xạ lưu trữ vSAN/NAS/block của VergeOS thành PersistentVolumes của Kubernetes cho các workload có trạng thái. Cả bốn thành phần (DMD, UI Extension, CCM, CSI driver) đều được phân phối qua **kho Helm verge-io**, đảm bảo phiên bản nhất quán và cài đặt đơn giản hơn. Một **Cluster Autoscaler** tùy chọn có sẵn cho các cụm do Rancher cung cấp. ## Docker Machine Driver Tính năng `docker-machine-driver-vergeos` là nền tảng của tích hợp. Nó dạy Docker Machine (và qua đó là Rancher) cách tạo VM trên VergeOS — biến VergeOS thành trình cung cấp nút hạng nhất cho các cụm RKE2 và K3s. ### Cách hoạt động Khi Rancher (hoặc Docker Machine độc lập) yêu cầu một nút mới, trình điều khiển thực hiện chuỗi sau: 1. **Nhân bản VM mẫu** — Một mẫu VM VergeOS dựng sẵn (ví dụ: Ubuntu 24.04 với cloud-init) được nhân bản để tạo nút mới 2. **Cấu hình tài nguyên tính toán** — Số lõi CPU và RAM được đặt theo đặc tả của cụm 3. **Chèn khóa SSH qua cloud-init** — Trình điều khiển tạo cặp khóa SSH và chèn khóa công khai thông qua cloud-init để truy cập an toàn, không cần mật khẩu 4. **Thay đổi kích thước đĩa chính** — Nếu cụm yêu cầu nhiều dung lượng hơn mẫu cung cấp, trình điều khiển sẽ thay đổi kích thước đĩa khởi động 5. **Gắn vào mạng đích** — VM được kết nối vào mạng ảo VergeOS đã chỉ định 6. **Bật nguồn và chờ IP** — Trình điều khiển theo dõi địa chỉ IP qua QEMU guest agent (ưu tiên) hoặc phương án dự phòng bằng lease DHCP Nếu bất kỳ bước nào thất bại, trình điều khiển sẽ tự động dọn dẹp các VM được tạo dở dang — không để lại tài nguyên mồ côi. ### Xác thực Trình điều khiển sử dụng **xác thực bằng khóa API** để giao tiếp với API REST của VergeOS. Tạo một khóa API từ giao diện VergeOS tại **Cài đặt người dùng**, rồi cung cấp nó qua `--vergeos-api-key` cờ hoặc biến môi trường `VERGEOS_API_KEY` . ### Các cờ cấu hình | Cờ | Biến môi trường | Mặc định | Mô tả | | ----------------------- | --------------------- | -------------------- | -------------------------------------------------- | | `--vergeos-host` | `VERGEOS_HOST` | *(bắt buộc)* | URL điểm cuối VergeOS | | `--vergeos-api-key` | `VERGEOS_API_KEY` | *(bắt buộc)* | Khóa API để xác thực | | `--vergeos-insecure` | `VERGEOS_INSECURE` | `false` | Bỏ qua xác minh TLS | | `--vergeos-template-vm` | `VERGEOS_TEMPLATE_VM` | *(bắt buộc)* | Tên VM mẫu để nhân bản | | `--vergeos-network` | `VERGEOS_NETWORK` | *(bắt buộc)* | Mạng đích để gắn vào | | `--vergeos-cpu-cores` | `VERGEOS_CPU_CORES` | `2` | Số lõi CPU trên mỗi nút | | `--vergeos-ram` | `VERGEOS_RAM` | `2048` | RAM tính bằng MB trên mỗi nút | | `--vergeos-disk-size` | `VERGEOS_DISK_SIZE` | `0` (kích thước mẫu) | Ghi đè kích thước đĩa tính bằng MB | | `--vergeos-ssh-user` | `VERGEOS_SSH_USER` | `root` | Tên người dùng SSH | | `--vergeos-ssh-port` | `VERGEOS_SSH_PORT` | `22` | Cổng SSH | | `--vergeos-cloudinit` | — | — | Cấu hình cloud-init tùy chỉnh (tệp hoặc nội tuyến) | ### Yêu cầu của mẫu Mẫu VM của bạn phải bao gồm: * **Cloud-init** đã cài đặt và bật — cần cho việc chèn khóa SSH và cấu hình hostname * **QEMU guest agent** (khuyến nghị) — cung cấp khả năng phát hiện địa chỉ IP đáng tin cậy; sẽ chuyển sang lease DHCP của NIC nếu không có * **Docker** (chỉ dùng khi sử dụng độc lập) — các triển khai Rancher sẽ tự động cài đặt runtime của container ### Hỗ trợ Ubuntu 24.04 Trình điều khiển bao gồm xử lý tự động cho các đặc thù của Ubuntu 24.04: * **Cấu hình DHCP của Netplan** cho việc đặt tên `en*` giao diện động * **Tạo lại Machine-ID** để đảm bảo định danh DHCP duy nhất cho mỗi bản nhân bản * **Dọn dẹp lease DHCP cũ** để ngăn xung đột IP do kế thừa từ mẫu {% hint style="success" %} **Kích thước nút Rancher** Các triển khai Rancher yêu cầu **tối thiểu 4 GB RAM** mỗi nút. Để ổn định trong môi trường sản xuất, **8 GB RAM** mỗi nút được khuyến nghị. {% endhint %} ### Sử dụng độc lập Bạn có thể sử dụng trình điều khiển bên ngoài Rancher để cung cấp Docker Machine theo nhu cầu: ```bash docker-machine create --driver vergeos \ --vergeos-host vergeos.example.com \ --vergeos-api-key your-api-key \ --vergeos-template-vm ubuntu-2404 \ --vergeos-network my-k8s-network \ --vergeos-ssh-user ubuntu \ --vergeos-cpu-cores 4 \ --vergeos-ram 8192 \ k8s-worker-01 ``` {% hint style="info" %} **Mặc định người dùng SSH** Trình điều khiển mặc định `root` đối với SSH, nhưng các ảnh đám mây Ubuntu không cho phép đăng nhập SSH bằng root. Khi dùng CLI trực tiếp với mẫu Ubuntu, hãy đặt `--vergeos-ssh-user ubuntu` (giao diện mở rộng Rancher UI đã mặc định là `ubuntu`). {% endhint %} ## Rancher UI Extension Tính năng `ui-extension-vergeos` thêm các bảng dành riêng cho VergeOS vào **dashboard Rancher**, cung cấp trải nghiệm người dùng gốc để quản lý các cụm Kubernetes dựa trên VergeOS mà không cần rời khỏi giao diện Rancher UI. ### Bảng Thông tin xác thực đám mây Khi tạo một Cloud Credential mới trong Rancher, tiện ích mở rộng sẽ thêm một **VergeOS** tùy chọn nhà cung cấp. Nhập URL máy chủ VergeOS, khóa API và cài đặt TLS của bạn — Rancher lưu các thông tin này an toàn và sử dụng chúng cho tất cả các thao tác cung cấp nút tiếp theo. ### Bảng Cấu hình máy Khi định nghĩa các node pool cho một cụm mới, tiện ích mở rộng hiển thị các trường cấu hình dành riêng cho VergeOS: * **Máy ảo mẫu** — Chọn từ các mẫu VM VergeOS hiện có * **Mạng** — Chọn mạng ảo đích * **CPU / RAM / Đĩa** — Đặt tài nguyên tính toán cho mỗi nút * **Cloud-init** — Cung cấp các script khởi tạo tùy chỉnh Tiện ích mở rộng được triển khai như một phần của `vergeos-node-driver` Helm chart, gói cả Docker Machine Driver và UI Extension lại với nhau. ## Cloud Controller Manager Tính năng `vergeos-cloud-controller-manager` (CCM) kết nối các thao tác của cụm Kubernetes với control plane của VergeOS, triển khai giao diện cloud-provider chuẩn của Kubernetes. ### Đồng bộ vòng đời nút CCM liên tục giám sát danh sách nút Kubernetes và đồng bộ nó với trạng thái VM VergeOS: * **Đăng ký nút** — Khi một nút mới tham gia cụm, CCM gắn thêm metadata dành riêng cho VergeOS (VM ID, mạng, vùng) * **Xóa nút** — Khi một VM VergeOS bị xóa hoặc tắt nguồn, CCM đánh dấu nút Kubernetes tương ứng là không khả dụng và kích hoạt việc lên lịch lại pod * **Giám sát sức khỏe** — Các kiểm tra định kỳ đảm bảo trạng thái nút Kubernetes phản ánh tình trạng thực tế của VM ### Cung cấp bộ cân bằng tải Khi một Service Kubernetes kiểu `LoadBalancer` được tạo, CCM sẽ cung cấp một bộ cân bằng tải thông qua lớp mạng của VergeOS: * Cấp phát một IP ảo từ pool địa chỉ đã cấu hình * Cấu hình phân phối lưu lượng trên các cổng node backend * Cập nhật `status.loadBalancer.ingress` của Service với IP đã cấp phát VergeOS xử lý việc cung cấp bộ cân bằng tải một cách nguyên bản thông qua CCM. {% hint style="info" %} **Đến từ VMware?** Trên VergeOS, CCM kết hợp quản lý vòng đời nút và `LoadBalancer` cung cấp Service trong một thành phần duy nhất được cài qua Helm — không cần ghép nối các add-on cloud-provider, CSI/CPI và cân bằng tải riêng rẽ. {% endhint %} {% hint style="info" %} **Đến từ Nutanix?** VergeOS hoạt động với bất kỳ chuỗi công cụ RKE2/K3s nào thông qua Rancher thay vì phát hành một bản phân phối Kubernetes độc quyền — bạn chọn biến thể Kubernetes upstream, và CCM cung cấp tích hợp cloud-provider gốc bên trên. {% endhint %} ## CSI Driver Tính năng `csi-vergeos` (Container Storage Interface) driver đưa lưu trữ VergeOS lên các workload Kubernetes thông qua đặc tả CSI chuẩn. ### Các backend lưu trữ CSI driver hỗ trợ hai backend, cả hai đều được phục vụ bởi một binary Go duy nhất: | Backend | Chế độ truy cập | Mô tả | | --------- | --------------- | ------------------------------------------------------------------- | | **NAS** | ReadWriteMany | Các volume EXT4 trên dịch vụ NAS của VergeOS, được cung cấp qua NFS | | **Block** | ReadWriteOnce | Các ổ đĩa VM được hotplug vào VM VergeOS qua vSAN | ### Cách hoạt động 1. Một nhà phát triển tạo một `PersistentVolumeClaim` (PVC) trong Kubernetes 2. CSI driver giao tiếp với API của VergeOS để cung cấp bộ nhớ được yêu cầu 3. Bộ nhớ được gắn vào nút đang chạy pod và được mount tại đường dẫn đã chỉ định 4. Khi pod bị xóa, CSI driver xử lý việc tháo mount và (tùy chọn) xóa dựa trên chính sách reclaim ### Ví dụ StorageClass ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: vergeos-block provisioner: csi.vergeos.com parameters: type: block reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` Các quản trị viên Kubernetes định nghĩa `StorageClass` các tài nguyên ánh xạ tới backend lưu trữ VergeOS. Sau đó các nhà phát triển tham chiếu những lớp này trong PVC của họ mà không cần hiểu hạ tầng bên dưới. ## Các Helm chart Tính năng `helm-charts` kho lưu trữ đóng gói tất cả các thành phần Kubernetes của VergeOS để triển khai gọn gàng. Có ba chart khả dụng: ### Các chart khả dụng | Chart | Thành phần | Mục đích | | ---------------------------------- | ------------------------------------ | ------------------------------------------------ | | `vergeos-node-driver` | Docker Machine Driver + UI Extension | Cung cấp nút và tích hợp dashboard Rancher | | `vergeos-cloud-controller-manager` | CCM | Đồng bộ vòng đời nút và cung cấp bộ cân bằng tải | | `vergeos-csi` | CSI Driver | Lưu trữ bền vững (NAS + block) | ### Cài đặt Thêm kho Helm của VergeOS và cài đặt các chart: ```bash # Thêm kho Helm của VergeOS helm repo add verge-io https://verge-io.github.io/helm-charts helm repo update # Tìm các chart khả dụng helm search repo verge-io # Cài đặt Cloud Controller Manager helm install vergeos-ccm verge-io/vergeos-cloud-controller-manager \ --namespace kube-system # Cài đặt CSI Driver helm install vergeos-csi verge-io/vergeos-csi \ --namespace kube-system # Cài đặt Node Driver + UI Extension (cho Rancher) helm install vergeos-node-driver verge-io/vergeos-node-driver \ --namespace cattle-system \ --set "vergeosHosts={vergeos.example.com}" ``` Tính năng `vergeosHosts` là danh sách cho phép bắt buộc gồm các hostname VergeOS mà proxy của Rancher được phép truy cập. Thay `vergeos.example.com` bằng hostname của các môi trường VergeOS của bạn; nếu không có nó, trình điều khiển không thể truy cập API của VergeOS. ## Quy trình triển khai từ đầu đến cuối Kết hợp cả bốn thành phần lại, đây là quy trình đầy đủ để triển khai một cụm Kubernetes trên VergeOS với Rancher: ```mermaid flowchart LR A["1. Chuẩn bị
mẫu VM"] --> B["2. Đăng ký
Node Driver"] B --> C["3. Tạo
Cloud Credential"] C --> D["4. Cung cấp
cụm"] D --> E["5. Triển khai
CCM + CSI"] E --> F["6. Chạy
workload"] style A fill:#2563eb,color:#fff style B fill:#2563eb,color:#fff style C fill:#2563eb,color:#fff style D fill:#2563eb,color:#fff style E fill:#2563eb,color:#fff style F fill:#16a34a,color:#fff ``` ### Bước 1: Chuẩn bị một mẫu VM Tạo một VM VergeOS với Ubuntu 24.04 (Noble Numbat) — hiện là hệ điều hành mẫu duy nhất được hỗ trợ — cài cloud-init và QEMU guest agent, rồi lưu nó làm mẫu. Mẫu này sẽ được nhân bản cho mọi nút Kubernetes. ### Bước 2: Đăng ký Node Driver Áp dụng manifest VergeOS NodeDriver vào cụm quản trị Rancher của bạn bằng `kubectl`. Điều này thông báo cho Rancher về Docker Machine Driver của VergeOS và bật nó như một tùy chọn cung cấp. Khởi động lại Rancher sau khi đăng ký để kích hoạt lược đồ trình điều khiển. ### Bước 3: Tạo Cloud Credential Trong giao diện Rancher, tạo một **Cloud Credential** mới bằng nhà cung cấp VergeOS (được thêm bởi UI Extension). Nhập URL máy chủ VergeOS và khóa API của bạn. ### Bước 4: Cung cấp cụm Tạo một cụm RKE2 hoặc K3s mới trong Rancher, chọn VergeOS làm nhà cung cấp hạ tầng. Định nghĩa các node pool của bạn (control plane, etcd, workers) với tài nguyên tính toán mong muốn. Rancher dùng Docker Machine Driver để nhân bản VM, chèn khóa SSH và khởi động cụm Kubernetes. ### Bước 5: Triển khai CCM và CSI Cài đặt Cloud Controller Manager và CSI Driver qua Helm vào cụm mới. CCM ngay lập tức bắt đầu đồng bộ trạng thái nút với VergeOS, và CSI driver làm cho lưu trữ VergeOS khả dụng cho PersistentVolumeClaims. ### Bước 6: Chạy workload Triển khai ứng dụng của bạn bằng các manifest Kubernetes chuẩn. Các Service kiểu `LoadBalancer` được CCM xử lý, và PersistentVolumeClaims được CSI driver đáp ứng — tất cả đều dựa trên hạ tầng VergeOS. ## Đăng ký Node Driver trong Rancher Docker Machine Driver phải được đăng ký như một tài nguyên Rancher NodeDriver. Áp dụng manifest sau với `kubectl`: ```yaml apiVersion: management.cattle.io/v3 kind: NodeDriver metadata: name: vergeos annotations: privateCredentialFields: "apiKey" publicCredentialFields: "host,insecure" spec: active: true builtin: false displayName: vergeos uiUrl: "" url: "https://github.com/verge-io/docker-machine-driver-vergeos/releases/download/v0.1.0/docker-machine-driver-vergeos-linux-amd64.tar.gz" ``` Sau khi áp dụng, hãy khởi động lại Rancher để tải lược đồ trình điều khiển mới. Khi đó tùy chọn VergeOS sẽ xuất hiện trong trình hướng dẫn tạo cụm. ## Tóm tắt Tích hợp Kubernetes của VergeOS biến VergeOS từ một nền tảng VM thành một **nhà cung cấp đám mây Kubernetes hoàn chỉnh**. Bằng cách triển khai các giao diện Docker Machine, Cloud Controller Manager và CSI, VergeOS cung cấp cho Kubernetes các primitive giống như từ các nhà cung cấp đám mây công cộng — cấp phát nút tự động, quản lý vòng đời, cân bằng tải và lưu trữ bền vững — tất cả chạy trên hạ tầng của riêng bạn với hiệu năng và hiệu quả của vSAN và mạng ảo VergeOS. ### Cấp phát nút tự động Docker Machine Driver sao chép máy ảo từ các mẫu với cloud-init, khóa SSH và kết nối mạng — hoàn toàn tự động thông qua Rancher. ### Nhà cung cấp đám mây gốc CCM và CSI driver triển khai các giao diện Kubernetes tiêu chuẩn, vì vậy các workload sử dụng `LoadBalancer` dịch vụ và `PersistentVolumeClaims` mà không cần sửa đổi. ### Triển khai được quản lý bởi Helm Tất cả các thành phần được đóng gói dưới dạng biểu đồ Helm để cài đặt nhất quán, có kiểm soát phiên bản trên các cụm. ### Trải nghiệm gốc Rancher Phần mở rộng UI đưa cấu hình VergeOS trực tiếp vào bảng điều khiển Rancher — không cần chuyển đổi ngữ cảnh. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/07-kubernetes-rancher.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.