> 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/automate-protect-and-extend/vi/tich-hop-va-api/rancher-integration.md).

# Tích hợp Rancher

## Tổng quan

VergeOS tích hợp với [Rancher](https://www.rancher.com/) thông qua một driver node Docker Machine và một tiện ích mở rộng giao diện người dùng. Cùng nhau, các thành phần này cho phép chúng tôi cung cấp và quản lý các cụm RKE2/K3s trên hạ tầng VergeOS trực tiếp từ giao diện Rancher.

| Thành phần                                      | Mục đích                                                          |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| [Docker Machine Driver](#docker-machine-driver) | Cung cấp các VM VergeOS làm các node Kubernetes                   |
| [Tiện ích mở rộng UI](#ui-extension)            | Thêm thông tin xác thực cloud VergeOS và cấu hình máy vào Rancher |

Khi các cụm đã chạy, [Tích hợp Kubernetes](/automate-protect-and-extend/vi/tich-hop-va-api/kubernetes-integration.md) các thành phần (CSI Driver và Cloud Controller Manager) cung cấp lưu trữ bền vững và quản lý vòng đời node — các thành phần này hoạt động với bất kỳ cụm Kubernetes nào trên VergeOS, không chỉ các cụm được Rancher cung cấp.

```mermaid
graph TD
    subgraph rancher["Rancher Server"]
        ui["Tiện ích mở rộng UI cho VergeOS"]
        creds["Thông tin xác thực cloud"] --> driver["Docker Machine Driver"]
    end

    driver --> vms["VM VergeOS"]

    subgraph cluster["Cụm RKE2/K3s (VM VergeOS)"]
        ccm["Cloud Controller Manager"]
        csi["CSI Driver"]
        ccm_features["Metadata node · Vòng đời node · Cân bằng tải"]
        csi_features["NAS ReadWriteMany · Block ReadWriteOnce"]
        ccm --- ccm_features
        csi --- csi_features
    end

    vms --> cluster
```

### Điều kiện tiên quyết

* Một môi trường VergeOS có quyền truy cập API
* Một cài đặt Rancher Server (v2.10+)
* Một VM mẫu chạy Ubuntu 24.04 với cloud-init đã cài đặt
* Một khóa API VergeOS (được tạo trong Cài đặt người dùng)
* `kubectl` và `helm` Các công cụ CLI

***

## Docker Machine Driver

Driver Docker Machine là nền tảng của tích hợp Rancher. Nó quản lý toàn bộ vòng đời VM thông qua API VergeOS — nhân bản các VM mẫu, chèn khóa SSH qua cloud-init, và tạo máy khi các cụm được cung cấp. Khi một cụm bị xóa, driver sẽ tự động xóa các VM mà nó đã tạo.

### Cách hoạt động

1. **Nhân bản** VM mẫu với tên máy được yêu cầu
2. **Cấu hình** số lõi CPU, RAM và cloud-init (khóa SSH + hostname + user-data tùy chọn)
3. **Thay đổi kích thước** ổ đĩa chính nếu chỉ định kích thước tùy chỉnh
4. **Gắn** VM vào mạng được chỉ định
5. **Bật nguồn** và chờ địa chỉ IP (ưu tiên QEMU guest agent, dự phòng bằng DHCP của NIC)

Nếu bất kỳ bước nào thất bại, driver sẽ tự động dọn dẹp VM được tạo dở.

### Chuẩn bị VM mẫu

Trước khi cung cấp các cụm, chúng ta cần một VM mẫu trong VergeOS với các yêu cầu sau:

**Bắt buộc:**

* **Ubuntu 24.04** (Noble Numbat) — hiện tại là hệ điều hành mẫu duy nhất được hỗ trợ
* **cloud-init** đã cài đặt và bật — driver chèn khóa SSH và đặt hostname thông qua một payload cloud-init MIME nhiều phần

**Khuyến nghị:**

* **QEMU guest agent** — cho phép phát hiện IP chính xác; nếu không có, driver sẽ quay về dùng IP lease DHCP của NIC

{% hint style="success" %}
**Chi tiết riêng cho Ubuntu 24.04**

Driver tự động xử lý một số chi tiết riêng của Ubuntu 24.04 thông qua cloud-init:

* **Cấu hình DHCP Netplan** — ghi một cấu hình netplan khớp với `en*` giao diện với `dhcp4: true`, xử lý các thay đổi tên khe PCI giữa các bản sao
* **Tạo lại Machine-ID** — tạo lại `/etc/machine-id` trên mỗi bản sao để mỗi VM có một định danh khách DHCP duy nhất
* **Dọn dẹp lease DHCP được lưu cache** — xóa các lease DHCP cũ được thừa kế từ mẫu
  {% endhint %}

{% hint style="warning" %}
**Yêu cầu về bộ nhớ**

Khi dùng với Rancher, hãy cấp phát ít nhất **4 GB RAM** mỗi node (khuyến nghị 8 GB). Một cụm RKE2 một node với Calico CNI sẽ bị OOM với 2 GB.
{% endhint %}

Docker là **không** bắt buộc trên mẫu — Rancher cài đặt runtime container riêng của nó (containerd) thông qua system agent. Mẫu chỉ cần cloud-init và guest agent.

### Yêu cầu về mạng

Mạng VergeOS được chỉ định trong `--vergeos-network` phải đáp ứng các yêu cầu sau để các cụm do Rancher cung cấp hoạt động.

{% hint style="warning" %}
**Bắt buộc có DHCP**

Mạng phải bật DHCP. Driver phát hiện IP của node qua QEMU guest agent, và các VM được nhân bản sẽ không nhận được địa chỉ nếu không có DHCP.
{% endhint %}

{% hint style="info" %}
**Kết nối với Rancher**

Các node phải có thể truy cập máy chủ Rancher, và Rancher phải có thể truy cập các node. Hãy đảm bảo các cổng sau được mở giữa chúng:

Để xem toàn bộ ma trận cổng, bao gồm các yêu cầu node-to-node (thay đổi theo CNI), xem [yêu cầu cổng Rancher RKE2](https://docs.rke2.io/install/requirements#networking) .
{% endhint %}

| Hướng           | Cổng | Giao thức | Mục đích                          |
| --------------- | ---- | --------- | --------------------------------- |
| Node → Rancher  | 443  | TCP       | Đăng ký và giao tiếp system agent |
| Rancher → Node  | 9345 | TCP       | Đăng ký node RKE2                 |
| Rancher → Node  | 6443 | TCP       | Máy chủ API Kubernetes            |
| Node → Internet | 443  | TCP       | Kéo image container từ registry   |

### Cài đặt trong Rancher

Driver node và tiện ích mở rộng UI được đóng gói cùng nhau trong một Helm chart duy nhất. Nó cài đặt binary Docker Machine driver, đăng ký tài nguyên NodeDriver, và triển khai tiện ích mở rộng UI.

**Qua Helm CLI:**

```bash
helm repo add verge-io https://verge-io.github.io/helm-charts
helm repo update

helm install vergeos-node-driver verge-io/vergeos-node-driver \\
  -n cattle-system \\
  --set "vergeosHosts={vergeos.example.com}"
```

Danh sách `vergeosHosts` giá trị là một danh sách trắng các hostname VergeOS mà proxy của Rancher được phép truy cập. Hãy thay `vergeos.example.com` bằng hostname của môi trường VergeOS.

**Qua giao diện Rancher:**

1. Đi tới **Tiện ích mở rộng** và nhấp vào **⋮** menu > **Quản lý kho lưu trữ**
2. Thêm một kho lưu trữ mới với URL `https://verge-io.github.io/helm-charts`
3. Quay lại **Tiện ích mở rộng** và cài đặt **VergeOS Node Driver** tiện ích mở rộng

Sau khi cài đặt, **VergeOS** sẽ xuất hiện như một tùy chọn node driver khi tạo cụm.

{% hint style="info" %}
**Chứng chỉ tự ký**

Nếu môi trường VergeOS dùng chứng chỉ tự ký, hãy đặt `insecure` thành `true` khi tạo thông tin xác thực cloud trong Rancher. Điều này báo cho driver bỏ qua xác thực TLS khi giao tiếp với API VergeOS.
{% endhint %}

### Cách dùng độc lập

Driver cũng hoạt động bên ngoài Rancher với Docker Machine trực tiếp:

```bash
docker-machine create \\
  --driver vergeos \\
  --vergeos-host vergeos.example.com \\
  --vergeos-api-key your-api-key \\
  --vergeos-insecure \\
  --vergeos-template-vm ubuntu-2404 \\
  --vergeos-network your-network-name \\
  --vergeos-ssh-user ubuntu \\
  --vergeos-cpu-cores 2 \\
  --vergeos-ram 4096 \\
  --vergeos-disk-size 30 \\
  my-docker-host
```

{% hint style="info" %}
**Docker là bắt buộc cho cách dùng độc lập**

Khi dùng như một Docker Machine driver độc lập (không thông qua Rancher), VM mẫu cũng cần Docker được cài đặt, hoặc chúng ta có thể dùng `--vergeos-cloudinit` để cài đặt nó ở lần khởi động đầu tiên.
{% endhint %}

Để xem danh sách đầy đủ các cờ của driver và biến môi trường, hãy xem kho lưu trữ driver trong [Tài liệu và tài nguyên](#documentation-and-resources) bên dưới.

{% hint style="info" %}
**Mặc định SSH User**

Driver mặc định dùng `root` làm người dùng SSH, nhưng tiện ích mở rộng UI của Rancher mặc định dùng `ubuntu`. Khi dùng trực tiếp CLI, hãy đặt `--vergeos-ssh-user ubuntu` cho các mẫu Ubuntu.
{% endhint %}

***

## Tiện ích mở rộng UI

Tiện ích mở rộng UI bổ sung các thành phần đặc thù VergeOS vào giao diện Rancher, mang lại trải nghiệm gốc khi tạo thông tin xác thực cloud và cấu hình máy.

### Nó thêm gì

**Biểu mẫu thông tin xác thực cloud** — yêu cầu:

* URL máy chủ VergeOS
* Khóa API (được lưu dưới dạng secret của Rancher)
* Công tắc xác minh TLS

**Biểu mẫu cấu hình máy** — cung cấp:

* Tên VM mẫu (tên của VM VergeOS cần nhân bản)
* Tên mạng (VNet VergeOS để gắn vào)
* Các trường nhập cho số lõi CPU, RAM và kích thước đĩa
* Trường user-data của cloud-init
* Cấu hình người dùng SSH và cổng

{% hint style="info" %}
**Tương thích**

Tiện ích mở rộng UI yêu cầu Rancher v2.10+ và Rancher Extensions framework v3.x.
{% endhint %}

{% hint style="info" %}
**Cài đặt**

Tiện ích mở rộng UI được cài đặt tự động như một phần của [Helm chart kết hợp](#installing-in-rancher). Không có bước cài đặt riêng.
{% endhint %}

***

## Tóm tắt

Tích hợp Rancher gồm hai thành phần được đóng gói trong một Helm chart duy nhất:

* **Docker Machine Driver** — nhân bản các VM mẫu VergeOS và quản lý vòng đời của chúng cho việc cung cấp cụm
* **Tiện ích mở rộng UI** — thêm các biểu mẫu thông tin xác thực cloud và cấu hình máy VergeOS vào giao diện Rancher

Cùng nhau, chúng cho phép chúng ta cung cấp các cụm RKE2/K3s trên hạ tầng VergeOS trực tiếp từ giao diện Rancher. Khi các cụm đã chạy, [Tích hợp Kubernetes](/automate-protect-and-extend/vi/tich-hop-va-api/kubernetes-integration.md) các thành phần xử lý lưu trữ bền vững và vòng đời node.

## Các bước tiếp theo

* Chuẩn bị một VM mẫu (Ubuntu 24.04 + cloud-init + QEMU guest agent) trong VergeOS
* Cài đặt [VergeOS Node Driver](#installing-in-rancher) Helm chart trong cụm Rancher
* Cung cấp một cụm downstream bằng cách dùng **VergeOS** làm node driver
* Cài đặt [CSI Driver và Cloud Controller Manager](/automate-protect-and-extend/vi/tich-hop-va-api/kubernetes-integration.md) trên cụm downstream để có lưu trữ bền vững và bộ cân bằng tải

## Tài liệu và tài nguyên

Để xem cấu hình chi tiết, cờ của driver, giá trị chart và ghi chú phát hành, hãy xem các kho lưu trữ GitHub:

| Kho lưu trữ                                                                                | Mô tả                                |
| ------------------------------------------------------------------------------------------ | ------------------------------------ |
| [docker-machine-driver-vergeos](https://github.com/verge-io/docker-machine-driver-vergeos) | Driver node Docker Machine / Rancher |
| [ui-extension-vergeos](https://github.com/verge-io/ui-extension-vergeos)                   | Tiện ích mở rộng UI của Rancher      |
| [helm-charts](https://github.com/verge-io/helm-charts)                                     | Kho lưu trữ Helm chart               |

## Hỗ trợ

Nếu bạn gặp sự cố hoặc có yêu cầu tính năng, vui lòng mở issue trong kho lưu trữ GitHub liên quan:

<https://github.com/verge-io/docker-machine-driver-vergeos/issues>


---

# 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/automate-protect-and-extend/vi/tich-hop-va-api/rancher-integration.md?ask=<question>&goal=<endgoal>
```

`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.