Kinetic

Kinetic là gì?

Một Kinetic là một container bạn chạy bên trong một dự án. Bạn mang đến một image, và nền tảng lập lịch cho nó, cấp cho nó một URL ổn định (cho các dịch vụ HTTP), đấu nối TLS, tự động co giãn và ghi log, đồng thời tính CPU/bộ nhớ của nó vào hạn ngạch dự án của bạn. Không có bước build ở đây — một Kinetic chạy một image. Hãy build hoặc đẩy image đó bằng Registry (hoặc bất kỳ registry công khai nào), rồi trỏ một Kinetic vào nó.

Một Kinetic chạy ở một trong hai chế độ:

• serving — một dịch vụ HTTP chạy lâu dài được phơi bày tại https://<kid>.<project>.<base-domain>. Nó có thể công khai (bất kỳ ai cũng gọi được) hoặc được bảo vệ (người gọi phải xuất trình một khóa API tài khoản dịch vụ của dự án). Hỗ trợ tự động co giãn và scale-to-zero.
• schedule — một cron job chạy image của bạn định kỳ rồi thoát. Không có URL công khai; lý tưởng cho các tác vụ theo lô, đồng bộ và dọn dẹp.

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

• Một dự án, và vai trò owner hoặc editor trên đó (hoặc vai trò kinetic.admin). Cùng một cơ chế phân quyền kiểm soát mọi thao tác create/update/delete ở đây. Xem Dự án & IAM.
• Một container image — hoặc công khai, hoặc đã đẩy lên Registry riêng của bạn (rồi đính kèm một pull secret, xem Image riêng tư).
• Đối với một Kinetic serving được bảo vệ: ít nhất một tài khoản dịch vụ với một khóa API (định dạng mksa_…) để gọi nó. Tạo các khóa này trên trang Service Accounts của dự án.

Tạo một hàm serving

Trong console, mở /<project>/kinetic và nhấn New (việc này mở trang con tạo mới tại /<project>/kinetic/new). Rồi:

1. Đặt cho nó một id — một nhãn DNS-1123 (chữ thường, chữ số và dấu gạch ngang), tối đa 30 ký tự. Nó phải là duy nhất trong dự án và trở thành subdomain của URL.
2. Đặt image, ví dụ ghcr.io/acme/hello:1.
3. Chọn chế độ serving và port của container (mặc định 8080).
4. Tùy chọn thêm biến môi trường, đặt giới hạn CPU/bộ nhớ, và cấu hình tự động co giãn.
5. Quyết định công khai hay được bảo vệ. Nếu được bảo vệ, hãy chọn các tài khoản dịch vụ được phép gọi nó.
6. Lưu. Kinetic chuyển từ Pending → Ready khi Deployment của nó trở nên khả dụng.

Lệnh gọi API tương đương — tạo bằng REST API:

curl -X POST https://api.<base-domain>/api/v1/projects/<project>/kinetics \
  -H "Authorization: Bearer <your-user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "hello",
    "image": "ghcr.io/acme/hello:1",
    "mode": "serving",
    "port": 8080,
    "env": [{"name": "GREETING", "value": "hi"}],
    "resources": {"cpu": "500m", "memory": "256Mi"},
    "serving": {
      "protected": true,
      "minReplicas": 1,
      "maxReplicas": 4,
      "allowedServiceAccounts": ["<sa-id>"]
    }
  }'

Các trường của body tạo mới

URL kết quả

Đối với một Kinetic serving, backend tính ra host <kid>.<project>.<base-domain> và operator cấp phát một Service, một Ingress và (trên staging/prod) một chứng chỉ TLS. Một khi ở trạng thái Ready, trang chi tiết hiển thị url trực tiếp — hãy luôn đọc nó từ đó thay vì đoán scheme: trên dev không có TLS issuer, nên URL là http://<host>, trong khi staging/prod dùng https://<host>.

Công khai và được bảo vệ

Một Kinetic serving hoặc là công khai (serving.protected = false — bất kỳ ai trên mạng đều có thể gọi nó) hoặc được bảo vệ (serving.protected = true — mọi yêu cầu phải mang theo một khóa API tài khoản dịch vụ hợp lệ của dự án). Việc bảo vệ được thực thi tại ingress qua một bước kiểm tra xác thực trước khi lưu lượng chạm tới container của bạn.

Các Kinetic được bảo vệ được ràng buộc với những tài khoản dịch vụ cụ thể qua serving.allowedServiceAccounts (một danh sách các id SA). Chỉ những khóa thuộc về một SA đã ràng buộc mới được chấp nhận — là bất kỳ SA nào của dự án thì chưa đủ. Khi protected = true, bạn phải liệt kê ít nhất một SA, nếu không Kinetic sẽ không thể truy cập được. Chuyển sang công khai sẽ xóa các ràng buộc.

Tùy chọn serving

Gọi một hàm được bảo vệ

Gửi khóa API dưới dạng một header X-API-Key hoặc một Bearer token. Khóa phải thuộc về một trong các tài khoản dịch vụ đã ràng buộc của Kinetic. Trang chi tiết hiển thị các SA đã ràng buộc và một đoạn curl sẵn sàng để sao chép.

# Using X-API-Key
curl https://<kid>.<project>.<base-domain>/ \
  -H "X-API-Key: mksa_xxxxxxxxxxxxxxxx"

# Equivalent, using a Bearer token
curl https://<kid>.<project>.<base-domain>/ \
  -H "Authorization: Bearer mksa_xxxxxxxxxxxxxxxx"

Biến môi trường

Truyền cấu hình vào container qua env — một danh sách các cặp {name, value}. Thêm hoặc sửa chúng trong biểu mẫu, hoặc qua API. Sửa env trên một Kinetic serving hiện có sẽ luân chuyển Deployment để áp dụng thay đổi.

"env": [
  {"name": "LOG_LEVEL", "value": "info"},
  {"name": "DATABASE_URL", "value": "rqlite://my-db.project-acme.svc.cluster.local:4001"}
]

Giới hạn CPU và bộ nhớ

Lượng request được giữ thấp một cách có chủ đích (50m CPU / 64Mi bộ nhớ) để một Kinetic rẻ khi lập lịch và thân thiện với hạn ngạch dự án. Thứ bạn đặt là giới hạn — trần mà container có thể dùng. Mặc định là 500m / 256Mi.

Giới hạn quan trọng vì hai lý do: một container vượt quá giới hạn bộ nhớ của nó sẽ bị OOM-kill (thoát 137), và ngưỡng tự động co giãn được tính bằng một phần trăm của giới hạn. Hãy định cỡ nó theo workload của bạn.

"resources": {"cpu": "1", "memory": "512Mi"}

Tự động co giãn và scale-to-zero

Các Kinetic serving co giãn theo chiều ngang giữa serving.minReplicas và serving.maxReplicas. Cách co giãn hoạt động phụ thuộc vào giá trị tối thiểu:

• minReplicas ≥ 1 và maxReplicas > minReplicas → một HorizontalPodAutoscaler dựa trên tài nguyên. Nó thêm bản sao khi mức sử dụng trung bình mỗi pod đạt 90% giới hạn (CPU hoặc bộ nhớ bạn đặt), và co lại về min khi rảnh rỗi.
• minReplicas = 0 (scale-to-zero) → KEDA HTTP add-on quản lý việc co giãn 0..maxReplicas dựa trên nhu cầu HTTP. Khi không có lưu lượng, Kinetic chạy không pod nào (không tốn phí); yêu cầu đầu tiên sau khi rảnh rỗi chịu một cold start ~3 giây. HPA dựa trên tài nguyên không áp dụng ở đây.
• maxReplicas không đặt hoặc ≤ minReplicas (min ≥ 1) → không tự động co giãn; số bản sao cố định tại minReplicas.

Trang chi tiết hiển thị min..max và số bản sao hiện tại.

Chế độ theo lịch

Đặt mode = schedule để chạy image theo một lịch cron thay vì phục vụ HTTP. Không có URL và không có tự động co giãn — nền tảng tạo một CronJob khởi chạy image của bạn theo lịch đã cho, chạy nó đến hoàn thành, và thử lại khi thất bại (tối đa 3 lần).

curl -X POST https://api.<base-domain>/api/v1/projects/<project>/kinetics \
  -H "Authorization: Bearer <your-user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "nightly-sync",
    "image": "ghcr.io/acme/sync:2",
    "mode": "schedule",
    "schedule": {"cron": "0 2 * * *", "args": ["--full"], "suspend": false}
  }'

Để chạy nó theo yêu cầu mà không cần chờ nhịp cron tiếp theo, hãy dùng trang Testing — nó tạo một lần chạy thủ công đơn lẻ từ mẫu của CronJob. Lần chạy đó và đầu ra của nó sau đó hiện ra trên các trang Requests và Logs.

Sử dụng một image riêng tư từ Registry

Image công khai không cần gì thêm. Đối với một image riêng tư — bao gồm bất cứ thứ gì trong Registry của dự án bạn — hãy cung cấp một registryCredential khi tạo hoặc cập nhật. Backend lưu nó dưới dạng một docker pull secret trong namespace của dự án và đính nó vào Kinetic một cách tự động; xóa Kinetic sẽ xóa secret.

"registryCredential": {
  "server": "registry.<project>.<base-domain>",
  "username": "<sa-id>",
  "password": "<sa-key>"
}

Khả năng quan sát: Logs, Requests, Testing

Ba trang con thao tác trên một Kinetic đã chọn (trang cung cấp một bộ chọn):

• Logs — mức sử dụng CPU/bộ nhớ trực tiếp (với một biểu đồ lịch sử ngắn) cộng với stdout container được tail. Serving hiển thị các pod của Deployment; schedule hiển thị các pod của Job gần nhất. Nếu metrics API của cụm không khả dụng, bạn sẽ nhận được một thông báo thân thiện thay vì một biểu đồ.
• Requests — với serving, một bảng phân trang gồm các yêu cầu được ghi lại (dấu thời gian, phương thức, đường dẫn, SA, được phép). Các dòng bị từ chối hoặc lỗi (allowed = false hoặc trạng thái ≥ 400) được đánh dấu và mở rộng để hiển thị status và reason của gateway (ví dụ "missing api key", "service account not bound"). Với schedule, nó liệt kê các lần chạy CronJob kèm thời gian bắt đầu/hoàn thành và thành công/thất bại.
• Testing — với serving, gọi Kinetic trong cụm (bỏ qua ingress và phần xác thực của nó) với một phương thức, đường dẫn, header và body đã chọn, và xem trạng thái, thời lượng và phản hồi. Với schedule, kích hoạt một lần chạy thủ công đơn lẻ.

Tham chiếu API

Tất cả endpoint nằm dưới /api/v1/projects/{project}/kinetics và yêu cầu một token người dùng owner/editor (hoặc kinetic.admin) làm header Bearer.

BASE=https://api.<base-domain>/api/v1/projects/<project>/kinetics
AUTH="Authorization: Bearer <your-user-token>"

# List all Kinetics
curl "$BASE" -H "$AUTH"

# Get one (phase, url, lastScheduleTime are TOP-LEVEL in the JSON)
curl "$BASE/hello" -H "$AUTH"

# Patch — partial update (here: change image, raise the autoscale ceiling)
curl -X PATCH "$BASE/hello" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"image":"ghcr.io/acme/hello:2","serving":{"maxReplicas":6}}'

# Delete (also removes the pull secret and any SA bindings)
curl -X DELETE "$BASE/hello" -H "$AUTH"

PATCH chấp nhận bất kỳ tập con nào của image, env, port, resources, serving (protected, minReplicas, maxReplicas, allowedServiceAccounts), schedule (cron, args, suspend) và registryCredential. Một lần xóa thành công trả về 204.

Tính phí và hạn ngạch

CPU và bộ nhớ của một Kinetic được tính vào hạn ngạch dự án của bạn trong khi nó chạy. Nếu dự án vượt quá hạn ngạch CPU hoặc bộ nhớ, nền tảng tự động tạm ngưng Kinetic dùng nhiều nhất để đưa mức sử dụng trở lại dưới trần — một Kinetic serving bị tạm ngưng giảm xuống không bản sao (các đối tượng HPA/KEDA của nó bị cắt bỏ), và một schedule bị tạm ngưng ngừng kích hoạt.

Để khôi phục:

1. Giảm nhu cầu — hạ giới hạn CPU/bộ nhớ của một Kinetic hoặc maxReplicas của nó, hoặc xóa các Kinetic bạn không còn cần.
2. Hoặc nâng hạn ngạch bằng cách nâng cấp gói trên trang Billing.
3. Một khi mức sử dụng trở lại dưới hạn ngạch, Kinetic tiếp tục chạy.

Xem Billing để biết hạn ngạch, mức sử dụng và việc thực thi vượt hạn ngạch hoạt động thế nào trên mọi dịch vụ.

Khắc phục sự cố

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