Dự án & IAM

Dự án là gì?

Một dự án là đơn vị cô lập và sở hữu cơ bản trong Nohost Cloud — tương đương với một project trên GCP hay một tài khoản AWS. Mọi dịch vụ khác (Kinetic, Dev Box, Bucket, Engines và Registry) đều tạo tài nguyên của mình bên trong một dự án, và việc tính phí cùng hạn ngạch được theo dõi theo từng dự án.

Một dự án mang lại cho bạn ba điều:

• Sự cô lập — mỗi dự án được hậu thuẫn bởi namespace Kubernetes riêng của nó, project-<project-id>, nên workload, secret và mạng được tách biệt khỏi các dự án khác.
• Hạn ngạch (quota) — một ResourceQuota giới hạn lượng CPU, bộ nhớ và dung lượng đĩa mà namespace có thể tiêu thụ, nên một dự án không bao giờ làm cạn tài nguyên của dự án khác.
• Kiểm soát truy cập (IAM) — thành viên, tài khoản dịch vụ và vai trò đều được giới hạn trong phạm vi dự án. Ai được làm gì được quyết định ở đây, một lần, cho mọi dịch vụ.

id của dự án do bạn chọn, là duy nhất trên toàn hệ thống, và không thể thay đổi sau khi đã tạo. Nó là một nhãn DNS-1123 —^[a-z]([-a-z0-9]*[a-z0-9])?$, tối đa 30 ký tự — bởi vì nó trở thành một phần của tên namespace và của mọi URL trong console. displayName thân thiện với con người có thể được đổi bất kỳ lúc nào.

Tạo một dự án

Bất kỳ ai cũng có thể tự tạo dự án. Từ console, mở bộ chuyển dự án ở thanh trên cùng và chọn Create project, rồi cung cấp:

Người gọi tạo ra dự án sẽ tự động trở thành chủ sở hữu của nó. Một dự án tự tạo được cấp phát với hạn ngạch mặc định bên dưới; quản trị viên nền tảng có thể nâng nó lên sau từ các trang quản trị.

Mô hình URL theo dự án đang hoạt động

Mọi trang trong console đều được giới hạn theo dự án đang hoạt động và id của nó xuất hiện đầu tiên trong đường dẫn: /<project>/<service>. Ví dụ, trang thành viên IAM cho một dự án tên là demo-01 là:

/demo-01/iam/members
/demo-01/iam/service-accounts
/demo-01/iam/roles

Mục IAM của console có ba trang con — Members, Service accounts và Roles. Chuyển dự án chỉ đơn giản là tráo đoạn đầu tiên, nên bạn có thể đánh dấu một liên kết sâu và nó luôn nằm đúng dự án.

Thành viên

Một thành viên là một người dùng Keycloak đã được cấp một hoặc nhiều vai trò trên dự án. Chủ sở hữu luôn là một thành viên với vai trò owner và được hiển thị đầu tiên trong danh sách.

Để thêm một thành viên, hãy vào /<project>/iam/members và nhấn Add member:

• Subject — tên người dùng Keycloak hiện có cần thêm. Nếu tên người dùng không tồn tại bạn sẽ nhận được lỗi 400.
• Roles — một hoặc nhiều id vai trò (xem Vai trò bên dưới). Một thành viên có thể giữ nhiều vai trò cùng lúc.

Sau này bạn có thể đổi vai trò của một thành viên hoặc loại bỏ họ hoàn toàn. Quản lý thành viên đòi hỏi vai trò owner hoặc editor.

Vai trò

Việc phân quyền dựa trên vai trò. Có hai nhóm vai trò: vai trò phạm vi toàn dự án cấp quyền truy cập rộng, và vai trò theo từng dịch vụ ủy quyền cho một dịch vụ duy nhất. Toàn bộ danh mục có sẵn từ GET /iam/roles.

Vai trò dự án

Vai trò theo từng dịch vụ

Mỗi dịch vụ cũng định nghĩa một vai trò admin và một vai trò viewer. Vai trò <service>.admin cho phép một thành viên quản lý đầy đủ chỉ riêng một dịch vụ đó mà không biến họ thành editor toàn dự án — lý tưởng để ủy quyền, chẳng hạn, lưu trữ cho một người và hàm cho một người khác.

Tài khoản dịch vụ

Một tài khoản dịch vụ (SA) là một danh tính máy được giới hạn trong đúng một dự án. Hãy dùng nó cho các pipeline CI, cron job, hay bất kỳ tự động hóa nào cần gọi API mà không cần con người đăng nhập. Khác với thành viên, một SA xác thực bằng khóa API do Nohost Cloud cấp — chứ không phải bằng Keycloak.

Mỗi SA có một email danh tính ổn định theo dạng <sa-name>@<project-id>.sa.nohost.local. Tạo một SA từ /<project>/iam/service-accounts:

Tạo một SA không tạo ra một khóa. Bạn cấp khóa riêng (xem bên dưới). Quản lý tài khoản dịch vụ đòi hỏi owner hoặc editor. Xóa một SA cũng xóa tất cả khóa của nó.

Khóa API

Một khóa API xác thực một tài khoản dịch vụ. Khóa có định dạng mksa_<random>. Backend chỉ lưu một mã băm SHA-256 của khóa cộng với một prefix ngắn (12 ký tự đầu, dùng để tra cứu) — nó không bao giờ lưu chính khóa đó.

Cấp một khóa từ trang chi tiết của tài khoản dịch vụ, hoặc qua API. Các lệnh liệt kê sau đó chỉ hiển thị prefix, thời điểm tạo, thời điểm dùng lần cuối và cờ vô hiệu hóa — không bao giờ là văn bản thuần. Để xoay vòng hoặc vô hiệu một khóa, hãy thu hồi nó; SA vẫn hoạt động với các khóa khác của nó.

Gửi một khóa theo một trong hai cách sau:

# Preferred dedicated header
X-API-Key: mksa_xxxxxxxxxxxxxxxxxxxx

# …or as a bearer token (the mksa_ prefix is detected automatically)
Authorization: Bearer mksa_xxxxxxxxxxxxxxxxxxxx

Ví dụ API (với tư cách người dùng)

Địa chỉ cơ sở của API backend là https://api.<base-domain> và mọi đường dẫn đều nằm dưới /api/v1. Một người dùng đã đăng nhập xác thực bằng một bearer token OIDC:Authorization: Bearer <session-token>. Các ví dụ bên dưới giả định $TOKEN và $BASE đã được thiết lập.

BASE=https://api.example.com/api/v1
TOKEN=<your-session-token>

Liệt kê các dự án của bạn

curl -s "$BASE/projects" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "demo-01",
    "displayName": "Demo One",
    "owner": "alice",
    "myRole": "owner",
    "phase": "Ready",
    "namespace": "project-demo-01",
    "createdAt": "2026-06-30T10:00:00Z"
  }
]

Tạo một dự án

curl -s -X POST "$BASE/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"demo-01","displayName":"Demo One"}'

Trả về 201 kèm dự án mới (đã áp dụng hạn ngạch mặc định). Trả về 409 nếu id đã bị chiếm hoặc 400 nếu nó không hợp lệ.

Thêm một thành viên

curl -s -X POST "$BASE/projects/demo-01/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject":"bob","roles":["editor"]}'

subject phải là một tên người dùng Keycloak hiện có (nếu không thì 400).

Tạo một tài khoản dịch vụ

curl -s -X POST "$BASE/projects/demo-01/service-accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deployer","displayName":"CI Deployer","roles":["kinetic.admin"]}'

Cấp một khóa API

curl -s -X POST \
  "$BASE/projects/demo-01/service-accounts/<sa-id>/keys" \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "f0c1...",
  "key": "mksa_3Hf9Qk2Lp...full-plaintext...",
  "prefix": "mksa_3Hf9Qk",
  "createdAt": "2026-06-30T10:05:00Z"
}

Để thu hồi nó sau này: DELETE /projects/demo-01/service-accounts/<sa-id>/keys/<key-id> (trả về 204).

Xác thực với tư cách một tài khoản dịch vụ

Khi bạn đã có một khóa mksa_, tự động hóa của bạn gọi cùng API đó mà không cần một token người dùng. Gửi khóa qua X-API-Key (hoặc dưới dạng bearer token). SA chỉ có thể hành động trong phạm vi dự án của chính nó, với các vai trò ràng buộc với nó.

KEY=mksa_3Hf9Qk2Lp...

# List the SA's project resources using the key
curl -s "$BASE/projects/demo-01/service-accounts" \
  -H "X-API-Key: $KEY"

# Equivalent, as a bearer token
curl -s "$BASE/projects/demo-01/service-accounts" \
  -H "Authorization: Bearer $KEY"

IAM liên quan thế nào đến mọi dịch vụ

IAM là cánh cổng đứng trước toàn bộ Nohost Cloud. Để quản lý tài nguyên của bất kỳ dịch vụ nào bạn cần hoặc một vai trò owner/editor toàn dự án, hoặc vai trò admin của dịch vụ đó. Một viewer (dự án hoặc theo từng dịch vụ) chỉ có thể đọc.

Xem hướng dẫn riêng của từng dịch vụ để biết chi tiết: Kinetic, Dev Box, Bucket, Engines, Registry và Billing.

Thực hành tốt nhất

Khắc phục sự cố & những điểm cần lưu ý