> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GreenNode

> Kết nối GreenNode để agent đọc tài nguyên vServer, VKS, vLB, vDB, storage và chạy thay đổi qua GreenNode CLI dưới Approvals của bạn

Kết nối GreenNode để agent CloudThinker đọc và vận hành tài nguyên GreenNode của bạn, như instance vServer, cluster VKS, load balancer, cơ sở dữ liệu và storage. Kết nối đăng nhập bằng **service account** (client ID và client secret) và chạy GreenNode CLI chính thức, `grn`, trong một region.

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

* Quyền truy cập [GreenNode IAM](https://iam.console.greennode.ai/service-accounts) với quyền tạo service account.
* Region GreenNode chứa tài nguyên của bạn: **HCM-3** (TP. Hồ Chí Minh) hoặc **HAN** (Hà Nội).
* Với vServer, cần **Project ID** của project bạn muốn agent dùng, và **Account ID** dạng số của bạn. GreenNode không tự chọn project cho bạn.
* Vai trò **Admin** trong workspace CloudThinker, vai trò có thể thêm và sửa kết nối. Xem [Vai trò](https://docs.cloudthinker.io/vi/guide/security/roles.md).

> [!NOTE]
>
> Mỗi workspace có **một** kết nối GreenNode, cho một region và một project. Để bao quát cả HCM-3 và HAN, hoặc project thứ hai, hãy [tạo workspace riêng](https://docs.cloudthinker.io/vi/guide/workspaces.md#tạo-workspace) cho từng trường hợp, với thành viên và cài đặt Approvals riêng.

> [!WARNING]
>
> Sao chép **Client secret** ngay khi tạo service account và lưu ở nơi an toàn. Nếu làm mất, bạn phải tạo service account mới và thay vào các giá trị mới theo [Xoay vòng thông tin xác thực](https://docs.cloudthinker.io/vi/guide/connections/overview.md#xoay-vòng-thông-tin-xác-thực).

## Thiết lập

**1. Tạo service account GreenNode**

Mở [GreenNode IAM → Service accounts](https://iam.console.greennode.ai/service-accounts), rồi:

1. Nhấn **Create a Service account**.
2. Nhập tên, ví dụ `cloudthinker`.
3. Trong bộ chọn scope, chỉ chọn scope cho các dịch vụ bạn muốn agent dùng. Xem [Quyền yêu cầu](#quyền-yêu-cầu).
4. Nhấn **Create Service account**.
5. Sao chép **Client ID** và **Client secret**.

**2. Chỉ cho vServer: sao chép Project ID và Account ID**

Bỏ qua bước này nếu agent không làm việc với vServer.

1. Trong [GreenNode dashboard](https://dashboard.console.greennode.ai/), mở **vServer → Limit** và sao chép **User Project ID** của project bạn muốn agent dùng.
2. Nhấn avatar ở góc trên bên phải và di chuột lên thẻ **Currently signed in as**. Sao chép **Account ID** dạng số, ví dụ `123456`. Không dùng email tài khoản. Form của CloudThinker gọi giá trị này là **Portal user ID**.

**3. Thêm kết nối trong CloudThinker**

Mở **More → Workspace settings → Connections**, chọn **GreenNode** và điền các trường theo [Chi tiết kết nối](#chi-tiết-kết-nối). Với vServer, nhập User Project ID vào **Project ID** và Account ID vào **Portal user ID**. Nếu không, để trống cả hai. Nhấn **Connect**.

**Trạng thái thành công:** kết nối hiển thị **Connecting** và **Verifying**, rồi trạng thái **Connected**. CloudThinker xác minh thông tin xác thực bằng cách đọc danh tính của service account từ GreenNode IAM.

Nếu kiểm tra thất bại, kết nối hiển thị **Error** cùng **Retry** (kiểm tra lại các giá trị đã lưu) và **Replace credentials** (nhập giá trị mới). Để thay đổi giá trị trên kết nối đang hoạt động, làm theo [Xoay vòng thông tin xác thực](https://docs.cloudthinker.io/vi/guide/connections/overview.md#xoay-vòng-thông-tin-xác-thực).

## Chi tiết kết nối

Form có đúng năm trường sau.

| Trường | Bắt buộc | Nội dung cần nhập |
| - | - | - |
| **Client ID** | Có | Client ID của service account. |
| **Client secret** | Có | Client secret của service account. |
| **Portal user ID** | Cho vServer | **Account ID** dạng số của GreenNode (cùng giá trị, khác nhãn). Phải là số nguyên dương. Để trống nếu bạn không dùng vServer. |
| **Default region** | Có | **HCM-3** (được chọn sẵn) hoặc **HAN**. Dù có nhãn như vậy, đây là region duy nhất kết nối bao quát, nên agent không truy cập được region còn lại. Để bao quát cả hai, dùng workspace thứ hai. |
| **Project ID** | Cho vServer | Project mà agent làm việc. Lệnh vServer thất bại nếu thiếu giá trị này. VKS không dùng giá trị này. |

## Quyền yêu cầu

Scope của service account quyết định mọi thứ agent có thể xem và thay đổi. CloudThinker không tự thêm quyền truy cập nào.

* **Bắt buộc cho việc kiểm tra kết nối:** scope cho phép service account đọc danh tính IAM của chính nó. CloudThinker chạy `grn iam whoami` để kiểm tra kết nối, và lệnh thất bại nếu thiếu scope đó.
* Với mỗi dịch vụ bạn muốn agent kiểm tra, chỉ cấp scope đọc của dịch vụ đó.
* Chỉ thêm scope ghi cho một dịch vụ khi bạn muốn agent thay đổi dịch vụ đó, ví dụ khởi động hoặc dừng instance vServer.

> [!TIP]
>
> Bắt đầu với scope đọc cho một hoặc hai dịch vụ bạn quan tâm, như vServer và VKS. Nếu agent báo lỗi quyền, hãy thêm scope mà GreenNode nêu tên và kiểm tra lại.

## Khả năng của agent

Agent dùng GreenNode CLI và đọc phần trợ giúp tích hợp sẵn của CLI trước mỗi lệnh, nên chỉ chạy các thao tác mà CLI thực sự cung cấp. CLI bao quát 13 nhóm dịch vụ:

| Nhóm dịch vụ | Agent có thể làm việc với |
| - | - |
| `vserver` | Máy chủ ảo và volume của chúng |
| `vks` | Cluster Kubernetes VKS |
| `vlb` | Load balancer |
| `vdb` | Cơ sở dữ liệu được quản lý |
| `vstorage`, `vstorage-gateway` | Storage và storage gateway |
| `vbackup` | Backup |
| `vcr` | Container registry |
| `vmonitor`, `vmonitor-log` | Metric và log |
| `iam` | Danh tính và quyền truy cập |
| `saas-ai`, `agentbase` | Các dịch vụ nền tảng AI của GreenNode |

Thao tác đọc chạy mà không cần hỏi. **Allow writes** trên bảng chi tiết của kết nối mặc định bật; tắt công tắc này để từ chối mọi thay đổi. Mọi thao tác tạo, cập nhật, xóa, khởi động, dừng, đổi kích thước, gắn, khôi phục hoặc thay đổi khác đều đi qua [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) trước.

Mọi thay đổi do agent thực hiện đều đi qua [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) của workspace trước. Ở chế độ mặc định **Auto · Rules + AI · Ask me**, AI judgment có thể cho một thay đổi an toàn chạy mà không cần hỏi. Allow Rule cũng vậy, sau khi CloudThinker bật [Rule enforcement](https://docs.cloudthinker.io/vi/guide/approvals/rules.md#khắc-phục-sự-cố) cho workspace của bạn. Chọn **Manual** nếu bạn muốn tự phê duyệt mọi thay đổi.

Nếu CLI không có lệnh cho điều bạn yêu cầu, agent sẽ báo cho bạn thay vì tìm cách lách, và nêu các hành động gần nhất mà CLI có cung cấp.

### Xác minh kết nối

```text theme={null}
Who am I signed in as on GreenNode, and which VKS clusters exist in my region?
```

Kết quả mong đợi là danh tính của service account, sau đó là danh sách cluster VKS, hoặc thông báo rõ ràng rằng region không có cluster nào.

### Ví dụ prompt

```text theme={null}
List my GreenNode vServer instances with their status and flavor
List my VKS clusters with their status and Kubernetes version
Stop the vServer instance web-01, and show me the exact change before you run it
```

## Khắc phục sự cố

> **GreenNode requires GRN\_ACCESS\_KEY\_ID and GRN\_SECRET\_ACCESS\_KEY**
>
> `GRN_ACCESS_KEY_ID` là trường **Client ID** và `GRN_SECRET_ACCESS_KEY` là trường **Client secret**. Một trong hai đang trống. Nhập cả hai giá trị từ service account, rồi kiểm tra lại.

> **GreenNode region must be HCM-3 or HAN**
>
> Chọn **HCM-3** hoặc **HAN** trong **Default region**, rồi kiểm tra lại.

> **GreenNode portal user ID must be a positive numeric value**
>
> **Portal user ID** đang chứa email hoặc văn bản khác. Nhập **Account ID** dạng số từ thẻ **Currently signed in as**, hoặc xóa trường đó.

> **GreenNode project ID contains unsupported characters**
>
> **Project ID** có khoảng trắng hoặc ký tự mà GreenNode không dùng. Sao chép lại **User Project ID** từ **vServer → Limit**, không kèm ký tự thừa.

> **GreenNode rejected the credentials or they lack the required read permission**
>
> Client ID hoặc secret sai, service account đã bị xóa, hoặc service account không thể đọc danh tính IAM của chính mình. Kiểm tra service account trong GreenNode IAM. Để nhập giá trị mới, nhấn **Replace credentials** trên kết nối bị lỗi, hoặc làm theo [Xoay vòng thông tin xác thực](https://docs.cloudthinker.io/vi/guide/connections/overview.md#xoay-vòng-thông-tin-xác-thực).

> **GreenNode did not answer before the connection test timeout**
>
> GreenNode không phản hồi trong khoảng thời gian kiểm tra, tức 60 giây. Đợi vài phút, rồi kiểm tra kết nối lại.

> **Connection 'greennode' already exists. Only one instance is allowed.**
>
> Workspace này đã có một kết nối GreenNode. Sửa kết nối đó, hoặc ngắt kết nối đó trước.

> **Câu hỏi về vServer thất bại nhưng VKS hoạt động**
>
> Lệnh vServer cần **Project ID**, và một số lệnh còn cần **Portal user ID**. Thêm cả hai, rồi kiểm tra lại.

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Thông tin xác thực nằm ngoài lệnh**: CloudThinker truyền client ID và secret cho CLI dưới dạng biến môi trường, và agent không thể in chúng ra, ghi đè endpoint GreenNode hoặc tắt kiểm tra chứng chỉ.
- **Xoay vòng secret**: để thay client ID và secret mới, làm theo [Xoay vòng thông tin xác thực](https://docs.cloudthinker.io/vi/guide/connections/overview.md#xoay-vòng-thông-tin-xác-thực).
- **Thu hồi tại nguồn**: xóa service account trong GreenNode IAM để dừng ngay mọi truy cập qua kết nối này.

## Liên quan

> **[Kết nối](https://docs.cloudthinker.io/vi/guide/connections/overview.md)**
>
> Xem mọi dịch vụ bạn có thể kết nối và cách trạng thái kết nối hoạt động.

> **[Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md)**
>
> Quyết định thay đổi GreenNode nào được chạy, chờ người duyệt hoặc bị từ chối.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.