Cấu hình xác thực OIDC cho cluster

ghi chú

Đây là tính năng beta, chỉ khả dụng với tài khoản được cấp quyền beta_user. Nếu không thấy mục này trên Portal, liên hệ team FKE để đăng ký tham gia beta.

Thay vì dùng chung 1 kubeconfig admin (client certificate) cho cả team, bạn có thể kết nối Managed GPU Cluster với Identity Provider (IdP) sẵn có của công ty — Keycloak, Azure AD, Okta, hoặc bất kỳ IdP chuẩn OIDC nào. Sau khi cấu hình, mỗi thành viên đăng nhập cluster bằng tài khoản SSO riêng.

ghi chú

Tính năng này chỉ xử lý authentication (xác minh danh tính). Bạn vẫn cần tự cấu hình authorization (quyền được làm gì) bằng Kubernetes RBAC. Sau khi bật OIDC, user đăng nhập thành công nhưng chưa có RoleBinding sẽ gặp lỗi 403 Forbidden khi chạy kubectl get pods — đây là hành vi đúng theo thiết kế, không phải lỗi cấu hình.

Cluster Admin (người đang giữ kubeconfig admin) thực hiện cấu hình này. Việc áp dụng chỉ tác động tới lớp xác thực của kube-apiserver — không restart node hay pod, nên GPU workload đang chạy (training, inference...) không bị gián đoạn. Bạn có thể cập nhật hoặc gỡ bỏ cấu hình bất kỳ lúc nào.

Ai nên dùng tính năng này

Vai trò	Mô tả
Cluster Admin	Quản trị GPU cluster, đang giữ kubeconfig admin (client certificate) — thực hiện cấu hình này
DevOps / MLOps Engineer	Phụ trách access control cho team dùng GPU workload — thường là người liên hệ team FKE để đăng ký beta

1. Mở mục SSO / OIDC.

   Vào AI infrastructure → Managed GPU cluster, mở cluster muốn cấu hình, ở tab Essential properties, cuộn tới mục SSO / OIDC (status hiện Disabled cho tới khi cấu hình), rồi chọn Edit.

   

2. Điền thông tin kết nối cơ bản.

   Chọn Edit mở form cấu hình SSO / OIDC, toggle Enable SSO / OIDC mặc định đang OFF. Bật ON (các field bên dưới sẽ dùng được), rồi điền:

   • Issuer URL (bắt buộc): địa chỉ gốc của Identity Provider — nơi cluster gửi yêu cầu xác minh token đăng nhập. Nhập URL đầy đủ bắt đầu bằng https://, không kèm ? (query string) hay # (fragment) ở cuối. Thường lấy nguyên URL này từ trang "Realm settings" hoặc "OIDC discovery" của IdP.
     • Keycloak: https://keycloak.mycompany.com/realms/production
     • Azure AD: https://login.microsoftonline.com/{tenant-id}/v2.0
     • Okta: https://mycompany.okta.com/oauth2/default
   • Client ID (bắt buộc): định danh của "ứng dụng" (chính là cluster này) đã đăng ký trên IdP, ví dụ trong Keycloak, ở mục Clients → Create client. Chỉ nhập 1 giá trị — hệ thống chưa hỗ trợ nhiều Client ID cho 1 cluster.
   • Username Claim (tùy chọn): field trong token đăng nhập dùng làm username Kubernetes. Mặc định là email. Xóa trắng field này nếu muốn hệ thống dùng sub (ID nội bộ của IdP, thường là chuỗi UUID khó đọc) thay thế. Nên chọn claim có giá trị ổn định theo thời gian — nếu email user đổi, RBAC binding cũ sẽ mất hiệu lực.
   • Groups Claim (tùy chọn): field trong token chứa danh sách group user thuộc về, dùng để gán quyền theo nhóm thay vì từng người — ví dụ nhóm "MLOps team" hay "GPU admins". Giá trị phổ biến là groups (mặc định Keycloak/Okta) hoặc client_roles (Keycloak client roles). Để trống nếu chưa cần phân quyền theo nhóm.

   

   mẹo

   Control plane của cluster cần đường truyền mạng tới Issuer URL. Nếu IdP nằm trong mạng nội bộ công ty, đảm bảo cluster truy cập được trước khi lưu.

3. Cấu hình nâng cao (tùy chọn).

   Cả 4 field dưới đây đều tùy chọn và độc lập với nhau — điền field này không yêu cầu phải điền field kia.

   • Username Prefix: chuỗi ngắn, thường kết thúc bằng :, tự động thêm vào trước giá trị Username Claim khi map vào Kubernetes. Ví dụ oidc: biến email = an.nguyen@mycompany.com thành username Kubernetes oidc:an.nguyen@mycompany.com. Giúp phân biệt rõ user SSO với user hệ thống hoặc user tạo cách khác, đặc biệt hữu ích khi nhiều team cùng chia sẻ 1 GPU cluster. Không được bắt đầu bằng system: — prefix này dành riêng cho group hệ thống Kubernetes. Để trống thì Kubernetes dùng thẳng giá trị claim gốc làm username, dễ trùng với user khác.
   • Groups Prefix: tương tự Username Prefix nhưng áp dụng cho tên group — ví dụ oidc: biến group gpu-admins thành oidc:gpu-admins trong Kubernetes. Cùng giới hạn system: như trên.
   • CA Bundle (PEM): chứng chỉ CA để cluster tin tưởng kết nối HTTPS tới IdP. Chỉ cần thiết nếu IdP dùng chứng chỉ tự ký (self-signed) hoặc CA nội bộ công ty — để trống nếu IdP dùng CA công cộng (Let's Encrypt, DigiCert...). Dán toàn bộ nội dung file .pem hoặc .crt, bắt đầu bằng -----BEGIN CERTIFICATE----- và kết thúc bằng -----END CERTIFICATE-----, phần thân là chuỗi base64 hợp lệ.
   • Required Claims: danh sách điều kiện bắt buộc token đăng nhập phải khớp mới được chấp nhận, kể cả khi user có tài khoản IdP hợp lệ. Chọn + Add claim và điền Claim (tên field trong token) và Value (giá trị bắt buộc phải khớp) cho từng dòng — cả 2 ô đều bắt buộc, không được khai trùng tên Claim ở 2 dòng khác nhau. Ví dụ Claim hd với Value mycompany.com chỉ cho phép tài khoản Google Workspace thuộc domain mycompany.com đăng nhập, dù IdP có phục vụ cả tài khoản Gmail cá nhân.

   

4. Chọn Save.

   Cluster chuyển sang trạng thái đang xử lý trong lúc áp dụng thay đổi — theo dõi qua status chung ở đầu trang cluster detail. Khi cluster về lại Succeeded/Running, cấu hình đã có hiệu lực, và GPU workload đang chạy không bị gián đoạn trong suốt quá trình này.

Kết quả

Team bạn giờ có thể lấy kubeconfig kèm kubelogin/OIDC plugin, đăng nhập GPU cluster bằng tài khoản SSO thay vì dùng chung kubeconfig admin. Bạn vẫn cần tự tạo RBAC binding (RoleBinding/ClusterRoleBinding) khớp đúng với username/group (đã cộng thêm prefix nếu có) bằng kubeconfig admin — bước này nằm ngoài phạm vi tự động hóa của Portal.

Xem Đăng nhập cluster bằng SSO để biết các bước thiết lập phía end-user, ví dụ RBAC, và hướng dẫn về GPU quota.

Cập nhật hoặc gỡ bỏ cấu hình

Chọn Edit ở mục SSO / OIDC bất kỳ lúc nào để thay đổi cấu hình hiện có:

• Cập nhật giá trị — sửa field bất kỳ (ví dụ xoay vòng Issuer URL hoặc Client ID sau khi IdP thay đổi), rồi chọn Save.
• Gỡ bỏ cấu hình — tắt toggle Enable SSO / OIDC, rồi chọn Save. Dialog xác nhận cảnh báo mọi phiên đăng nhập OIDC hiện tại sẽ ngừng hoạt động khi thay đổi có hiệu lực (vài phút), và kubeconfig admin (client certificate) không bị ảnh hưởng. Xác nhận để tiếp tục, hoặc hủy để giữ nguyên.

Gỡ bỏ cấu hình không ảnh hưởng tới kubeconfig admin — bạn luôn có thể quay lại dùng, và cũng không ảnh hưởng tới GPU workload đang chạy.

Vấn đề thường gặp

Vấn đề	Nguyên nhân / cách xử lý
"This feature isn't available for your account yet"	Tài khoản chưa được cấp quyền beta_user — liên hệ team FKE để đăng ký
"This cluster is still processing" khi chọn Save hoặc delete	Cluster đang xử lý thay đổi khác — đợi vài phút rồi thử lại
Đăng nhập SSO bị từ chối dù cấu hình có vẻ đúng	Kiểm tra RBAC binding đã khớp đúng username/group (kèm đúng prefix nếu có) chưa; kiểm tra token có đủ Required Claims đã khai không
Không nhập được Prefix bắt đầu bằng system:	Đây là giới hạn cố ý — tránh trùng với group hệ thống Kubernetes, có thể gây rủi ro leo thang quyền
Field (Issuer URL, CA Bundle...) sai định dạng nhưng không hiện dòng báo lỗi	Hạn chế đã biết ở bản beta hiện tại — field chỉ đổi viền đỏ, chưa hiện text mô tả. Kiểm tra lại đúng định dạng yêu cầu: HTTPS không kèm query/fragment cho Issuer URL, đúng PEM cho CA Bundle
Lo ngại ảnh hưởng tới GPU workload đang chạy (training, inference...)	Bật/sửa/xóa OIDC chỉ tác động tới lớp xác thực của kube-apiserver — không restart node hay pod, GPU workload không bị gián đoạn

Mẹo

• Thử kết nối IdP với 1 GPU cluster staging trước, trước khi áp dụng cho cluster production cả team đang phụ thuộc vào.
• Giữ lại kubeconfig admin làm phương án dự phòng — không bị ảnh hưởng khi bật/tắt OIDC.
• Dùng Required Claims để giới hạn phạm vi đăng nhập — ví dụ chỉ chấp nhận token có hd = yourcompany.com, tránh tài khoản ngoài công ty (nếu IdP dùng chung nhiều tổ chức) đăng nhập được.
• Đặt Username Prefix rõ ràng (ví dụ oidc:) để dễ phân biệt user SSO với user hệ thống khi xem log/audit, đặc biệt khi GPU cluster có nhiều team cùng chia sẻ.
• Xem trạng thái SSO / OIDC cùng với các cấu hình khác của cluster ở tab Essential properties trong Access a cluster.