Engines

Tổng quan

Engines là tầng dữ liệu được quản lý của Nohost Cloud. Thay vì tự vận hành cơ sở dữ liệu, bộ nhớ đệm hay message broker của riêng mình, bạn tạo một engine — một instance độc lập, tự đóng gói, được hậu thuẫn bởi một volume bền vững — và kết nối các hàm Kinetic, không gian làm việc Dev Box và ứng dụng bên ngoài của bạn vào nó. Mỗi engine nằm trong một project, được cấp thông tin đăng nhập tự sinh, và được tính vào hóa đơn cũng như hạn mức của project đó.

Có ba loại engine, mỗi loại bao bọc một engine mã nguồn mở quen thuộc:

Khi nào dùng loại nào: chọn database khi bạn cần dữ liệu quan hệ bền vững, có thể truy vấn bằng SQL; cache khi bạn cần lưu trữ key/value tạm thời cực nhanh hoặc pub/sub qua Redis; và queue khi bạn muốn các topic MQTT nhẹ để phân phối sự kiện hoặc đo từ xa thiết bị.

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

• Một project mà bạn có quyền quản lý. Việc tạo, khởi động, dừng, đổi kích thước hay xóa một engine đòi hỏi vai trò owner hoặc editor của project, hoặc vai trò theo từng dịch vụ engines.admin. Một viewer (hoặc engines.viewer) chỉ có thể đọc.
• Dịch vụ Engines phải được bật cho nền tảng. Nếu chưa được cấu hình thì API trả về 503 engines service not configured.
• Project còn dư hạn mức — một engine tiêu tốn CPU, bộ nhớ và đĩa. Xem Hóa đơn.

Bố cục console & ánh xạ loại

Trong console, Engines nằm tại /<project>/engines với ba mục con — Database, Caching và Queue. Mỗi mục con liệt kê các engine thuộc loại đó và cho phép bạn tạo mới; nhấp vào một engine sẽ mở trang chi tiết của nó với thông tin kết nối, số liệu và các thao tác khởi động/dừng/xóa.

Tạo một engine

Từ console, mở mục con liên quan (Database, Caching hoặc Queue), nhấp Create, rồi điền vào drawer:

Khi tạo, backend sinh một thông tin đăng nhập (username + password), lưu nó trong một secret riêng cho từng engine, cấp phát workload và PVC, rồi khởi động engine ngay lập tức (running: true). Id trở thành một phần của tên DNS trong cụm của engine và host bên ngoài của nó, nên hãy chọn cẩn thận — nó không thể thay đổi.

Tạo qua API

API cơ sở là https://api.<base-domain>/api/v1. Xác thực bằng một token OIDC của người dùng hoặc một khóa service-account. Các ví dụ giả định $BASE và $TOKEN đã được đặt.

BASE=https://api.example.com/api/v1
TOKEN=<your-session-token>      # or an mksa_ service-account key
PROJECT=demo-01

curl -s -X POST "$BASE/projects/$PROJECT/engines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "id": "app-db",
        "type": "database",
        "storageSize": "10Gi",
        "resources": { "cpu": "1", "memory": "1Gi" }
      }'

curl -s -X POST "$BASE/projects/$PROJECT/engines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "id": "app-cache",
        "type": "cache",
        "storageSize": "1Gi",
        "resources": { "cpu": "500m", "memory": "512Mi" }
      }'

curl -s -X POST "$BASE/projects/$PROJECT/engines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "id": "events",
        "type": "queue",
        "storageSize": "1Gi"
      }'

Tạo thành công trả về 201 cùng chi tiết engine (bao gồm thông tin kết nối). Bạn nhận 400 nếu id, type hay storageSize không hợp lệ, và 409 nếu đã có một engine với id đó.

Hiển thị & dùng thông tin đăng nhập

Mỗi engine có một thông tin đăng nhập được sinh tự động. Username cố định theo loại và password là ngẫu nhiên:

Trên trang chi tiết engine, thẻ Connection hiển thị username và nút Reveal credentials để lấy password theo yêu cầu (chỉ owner / editor / engines.admin). Password có thể được hiển thị lại bất cứ lúc nào — nó được lưu trong secret của engine, không phải chỉ hiện một lần.

curl -s "$BASE/projects/$PROJECT/engines/app-db/credentials" \
  -H "Authorization: Bearer $TOKEN"

{
  "username": "admin",
  "password": "s3cr3t-generated-password"
}

Thông tin kết nối

Trang chi tiết và phản hồi engine của GET bao gồm một đối tượng connection mô tả cách tiếp cận engine. Mỗi engine có một endpoint trong cụm dùng Kubernetes DNS, và hầu hết cũng để lộ một endpoint bên ngoài khi chúng đang Running.

• Host trong cụm: <eid>.project-<project>.svc.cluster.local — có thể truy cập từ Kinetic và Dev Box trong cùng project.
• Bên ngoài: rqlite được để lộ qua HTTPS thông qua một URL Ingress; Redis và Mosquitto được để lộ qua TCP trên một NodePort tiếp cận tại host TCP của nền tảng.

Kết nối tới database (rqlite)

rqlite nói SQL qua một HTTP API đơn giản. Truy vấn đọc đi tới /db/query và ghi đi tới /db/execute; xác thực bằng HTTP basic auth dùng người dùng admin và password đã hiển thị. Cổng trong cụm là 4001; bên ngoài thì dùng URL HTTPS API từ thẻ kết nối.

# RQLITE = the "HTTP API" external endpoint, e.g. https://app-db.demo-01.engine.example.com
curl -s -u admin:$PASSWORD \
  "$RQLITE/db/query?q=SELECT%201"

# Create a table and insert a row
curl -s -u admin:$PASSWORD -XPOST "$RQLITE/db/execute?pretty" \
  -H "Content-Type: application/json" \
  -d '[
        "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)",
        "INSERT INTO notes(body) VALUES(\"hello\")"
      ]'

# Parameterised read
curl -s -u admin:$PASSWORD -XPOST "$RQLITE/db/query?pretty" \
  -H "Content-Type: application/json" \
  -d '[["SELECT * FROM notes WHERE id = ?", 1]]'

Từ bên trong cụm, đổi host thành http://admin@<eid>.project-<project>.svc.cluster.local:4001.

Kết nối tới cache (Redis)

Redis lắng nghe trên TCP 6379 với người dùng default và password của engine. Bên ngoài, dùng endpoint Redis (TCP) hiển thị trong thẻ kết nối, vốn trỏ tới host TCP của nền tảng và NodePort của engine.

# Sample shown in the console:
#   redis-cli -h <host> -p <port> -a <password> ping

# In-cluster:
redis-cli -h app-cache.project-demo-01.svc.cluster.local -p 6379 \
  -a "$PASSWORD" ping     # -> PONG

# External (host:port from the "Redis (TCP)" endpoint):
redis-cli -h tcp.example.com -p 31790 -a "$PASSWORD" \
  set greeting "hello"

import { createClient } from 'redis';

const client = createClient({
  url: 'redis://default:' + process.env.ENGINE_PASSWORD +
    '@app-cache.project-demo-01.svc.cluster.local:6379',
});
await client.connect();
await client.set('greeting', 'hello');

Kết nối tới queue (Mosquitto)

Mosquitto là một MQTT broker trên TCP 1883, yêu cầu người dùng admin và password. Thẻ kết nối liệt kê một endpoint MQTT (TCP)(host TCP + NodePort) và, nơi có cấu hình, một endpoint MQTT qua WebSocket (wss://…).

# Sample shown in the console:
#   mosquitto_sub -h <host> -p <port> -u admin -P <password> -t '#'

# Subscribe to everything (in-cluster):
mosquitto_sub -h events.project-demo-01.svc.cluster.local -p 1883 \
  -u admin -P "$PASSWORD" -t '#'

# Publish a message (external TCP endpoint host:port):
mosquitto_pub -h tcp.example.com -p 31822 \
  -u admin -P "$PASSWORD" -t 'sensors/temp' -m '21.5'

Kết nối từ Kinetic hoặc Dev Box

Các workload trong cùng project dùng chung namespace của project (project-<project>), nên chúng có thể tiếp cận một engine trực tiếp qua tên DNS trong cụm của nó mà không phải đi qua endpoint bên ngoài. Cách này nhanh hơn và giữ lưu lượng bên trong cụm.

# database (rqlite, HTTP):
http://app-db.project-demo-01.svc.cluster.local:4001

# cache (Redis, TCP):
app-cache.project-demo-01.svc.cluster.local:6379

# queue (MQTT, TCP):
events.project-demo-01.svc.cluster.local:1883

Khởi động, dừng & đổi kích thước

Engine hoạt động giống một Dev Box. Trang chi tiết có một nút Stop / Start: dừng sẽ thu workload về không (nên nó ngừng tiêu tốn CPU/bộ nhớ) trong khi vẫn giữ nguyên volume bền vững và thông tin đăng nhập; khởi động sẽ đưa nó trở lại. Để đổi kích thước CPU và bộ nhớ, hãy patch resources của engine.

# Stop
curl -s -X PATCH "$BASE/projects/$PROJECT/engines/app-db" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"running": false}'

# Start
curl -s -X PATCH "$BASE/projects/$PROJECT/engines/app-db" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"running": true}'

curl -s -X PATCH "$BASE/projects/$PROJECT/engines/app-db" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"resources": {"cpu": "2", "memory": "2Gi"}}'

Tham chiếu REST API

Tất cả route đều nằm dưới /api/v1/projects/<project>/engines. Đọc (list, get, metrics) thì mở cho mọi thành viên project; tạo, patch, xóa và credentials đòi hỏi owner / editor / engines.admin.

curl -s "$BASE/projects/$PROJECT/engines?type=cache" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "app-cache",
    "type": "cache",
    "image": "redis:7",
    "cpu": "500m",
    "memory": "512Mi",
    "running": true,
    "suspended": false,
    "phase": "Running",
    "createdAt": "2026-06-30T10:00:00Z"
  }
]

curl -s "$BASE/projects/$PROJECT/engines/app-db" \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "app-db",
  "type": "database",
  "image": "rqlite/rqlite:8",
  "storageSize": "10Gi",
  "resources": { "cpu": "1", "memory": "1Gi" },
  "running": true,
  "suspended": false,
  "phase": "Running",
  "createdAt": "2026-06-30T10:00:00Z",
  "connection": {
    "protocol": "http",
    "username": "admin",
    "internalHost": "app-db.project-demo-01.svc.cluster.local",
    "port": 4001,
    "internalEndpoint": "http://admin@app-db.project-demo-01.svc.cluster.local:4001",
    "external": [
      { "label": "HTTP API", "value": "https://app-db.demo-01.engine.example.com" }
    ],
    "sample": "curl -u admin:<password> <endpoint>/db/query?q=SELECT%201"
  }
}

curl -s "$BASE/projects/$PROJECT/engines/app-db/metrics?range=24h" \
  -H "Authorization: Bearer $TOKEN"

curl -s -X DELETE "$BASE/projects/$PROJECT/engines/app-db" \
  -H "Authorization: Bearer $TOKEN"     # -> 204 No Content

Hóa đơn & hạn mức

Giới hạn CPU và bộ nhớ của một engine được tính vào hạn mức project khi nó đang chạy, và volume bền vững của nó được tính vào hạn mức đĩa của project dù engine đang chạy hay đã dừng. Engine hoạt động giống Kinetic và Dev Box trong việc cưỡng chế hạn mức.

• Tự động tạm ngừng — nếu project vượt hạn mức CPU/bộ nhớ, các engine bị tạm ngừng (hiển thị với cờ suspended và huy hiệu Suspended) cho tới khi bạn giải phóng dung lượng hoặc nâng hạn mức.
• Đĩa — PVC vẫn tiếp tục được tính vào hạn mức đĩa kể cả khi engine đã dừng. Hãy xóa engine để thu hồi nó.
• Dừng sẽ giải phóng CPU/bộ nhớ (giúp bạn nằm trong hạn mức) nhưng không giải phóng đĩa.

Xem Hóa đơn để biết cách hạn mức, tạm ngừng và gói hoạt động trên toàn project.

Xử lý sự cố & mẹo