Bài 51 — Internal Service Catalog & Developer Portal

Mở đầu — vì sao bài này quan trọng

Hãy tưởng tượng bạn vừa gia nhập một công ty fintech tại TP.HCM có khoảng 45 kỹ sư và hơn 50 microservices đang chạy production. Sếp giao cho bạn task đầu tiên: "Fix cái bug ở service payment-reconcile". Nghe đơn giản, nhưng thực tế bạn phải trả lời một loạt câu hỏi trước khi gõ được dòng code đầu tiên:

• Service payment-reconcile nằm ở repo nào? GitHub org có tới 200 repo.
• Ai là owner? Ping nhầm người thì đợi cả buổi không ai trả lời.
• Nó deploy bằng pipeline nào, đang ở version bao nhiêu trên production?
• Dashboard theo dõi lỗi ở đâu? Grafana, Datadog, hay Kibana?
• Có runbook xử lý sự cố không? Khi nó chết lúc 2 giờ sáng thì làm gì?
• Nó gọi những service nào và bị service nào gọi (dependency)?

Ở nhiều công ty, câu trả lời cho những câu hỏi trên nằm rải rác trong Confluence (viết từ 2 năm trước, đã lỗi thời), trong các kênh Slack, trong đầu của một anh senior đã nghỉ việc tháng trước. Một new hire thường mất cả tuần chỉ để "dò đường" trước khi thực sự đóng góp được.

Đây chính là bài toán mà Internal Service Catalog (danh mục dịch vụ nội bộ) và Developer Portal (cổng thông tin dành cho lập trình viên) ra đời để giải quyết. Trong bối cảnh CI/CD, service catalog không chỉ là "danh bạ" mà còn là trung tâm điều phối: nó gắn liền với pipeline, với ownership, với chất lượng release. Đây là bài học về cách biến kiến thức phân mảnh, ẩn giấu trong tổ chức thành một nguồn thông tin tập trung, luôn cập nhật và tự phục vụ được.

Khái niệm cốt lõi

Service Catalog là gì?

Service Catalog là một danh sách có cấu trúc của tất cả các thành phần phần mềm trong tổ chức của bạn: microservices, thư viện dùng chung, website, pipeline, database, API... Mỗi entry (mục) trong catalog mô tả một "software component" cùng với metadata quan trọng nhất về nó.

Điểm khác biệt so với một trang wiki thông thường: service catalog có schema chuẩn hóa. Mỗi service đều mô tả bằng cùng một tập trường thông tin, nên bạn có thể tìm kiếm, lọc, và tự động hóa trên đó. Ví dụ, một entry điển hình gồm:

• Tên & mô tả: payment-reconcile — Đối soát giao dịch thanh toán với ngân hàng.
• Owner / Team: team payments, tech lead: Nguyễn Văn A.
• Source code: link tới repo GitHub.
• Lifecycle: production / experimental / deprecated.
• Dependencies: gọi ledger-service, bank-gateway; được gọi bởi checkout-api.
• Links: dashboard Grafana, runbook, tài liệu API (OpenAPI), on-call rotation.
• CI/CD: pipeline nào build, version đang chạy trên mỗi environment.

Developer Portal là gì?

Nếu Service Catalog là dữ liệu thì Developer Portal là giao diện và trải nghiệm để tương tác với dữ liệu đó, cộng thêm nhiều tính năng khác. Developer Portal là một website nội bộ nơi lập trình viên có thể:

• Discover — tra cứu mọi service, xem sơ đồ phụ thuộc, biết ai là owner.
• Tech Docs — đọc tài liệu kỹ thuật viết dạng "docs-as-code" (Markdown trong repo, render tự động).
• Software Templates / Scaffolder — tạo mới một service từ template chuẩn chỉ với vài cú click (đúng chuẩn CI/CD, đúng cấu trúc, đúng owner).
• Self-service actions — trigger deploy, xem trạng thái pipeline, tạo resource... ngay trên portal.

Công cụ phổ biến nhất hiện nay là Backstage (mã nguồn mở, do Spotify tạo ra và đóng góp cho CNCF). Ngoài ra còn có các nền tảng thương mại như Port, Cortex, OpsLevel, Roadie (Backstage-as-a-service).

Vì sao đây là mảnh ghép của Platform Engineering

Service Catalog + Developer Portal là trái tim của Internal Developer Platform (IDP) — nền tảng nội bộ giúp lập trình viên tự phục vụ. Triết lý ở đây là giảm cognitive load (gánh nặng nhận thức): một dev không cần nhớ 50 service nằm ở đâu, không cần biết chi tiết Kubernetes hay Terraform, họ chỉ cần vào một chỗ duy nhất — "one pane of glass" — để làm việc.

Golden Path và Software Templates

Một khái niệm quan trọng đi kèm là Golden Path (con đường vàng): cách làm được khuyến nghị, đã được đội platform kiểm chứng, để tạo một service mới. Thay vì mỗi team tự dựng CI/CD theo kiểu riêng, portal cung cấp template: bấm "Create Service", điền tên, chọn ngôn ngữ, portal sẽ tự sinh repo với Dockerfile, GitHub Actions workflow, Helm chart, và tự động đăng ký service đó vào catalog. Đây là chỗ service catalog kết nối trực tiếp với chủ đề CI/CD của cả khóa học.

Tình huống thực tế

Tình huống 1 — Fintech Việt Nam: Từ "hỏi Slack" đến self-service

Một công ty ví điện tử tại Hà Nội (gọi là VietPay, ~60 kỹ sư, 70+ microservices) gặp vấn đề kinh điển: mỗi khi có incident, người trực on-call phải mở 5-6 tab khác nhau để tìm hiểu service nào đang lỗi thuộc team nào. Trung bình MTTR (Mean Time To Recovery — thời gian trung bình để khôi phục) là 90 phút, trong đó có tới 30-40 phút chỉ để "tìm đúng người và đúng dashboard".

Đội platform triển khai Backstage. Họ yêu cầu mỗi repo phải có file catalog-info.yaml khai báo owner, dependencies và link runbook. Sau 3 tháng, khi có incident, người on-call chỉ cần search tên service trên portal, thấy ngay: owner là team wallet-core, on-call hiện tại là ai, runbook nào, dependency graph cho thấy service gọi tới kyc-service (nghi phạm chính). MTTR giảm xuống còn ~45 phút.

Bài học rút ra: Giá trị lớn nhất của catalog không phải lúc mọi thứ êm đẹp, mà là lúc "cháy nhà" — khi mỗi phút đều tính bằng tiền và uy tín. Ownership rõ ràng là tính năng "sát thủ".

Tình huống 2 — Spotify và bài toán quy mô

Backstage sinh ra tại Spotify chính vì bài toán tương tự nhưng ở quy mô khổng lồ: hàng nghìn microservice, hàng nghìn kỹ sư. Spotify công bố rằng sau khi có Backstage, thời gian onboarding một kỹ sư mới để đóng góp code lần đầu (time-to-first-commit) giảm đáng kể, từ khoảng 60 ngày xuống còn khoảng 20 ngày ở nhiều đội.

Chìa khóa của họ là Software Templates: 60% service mới được tạo từ template chuẩn, nghĩa là chúng tự động có CI/CD đúng chuẩn, tự động xuất hiện trong catalog, không cần ai đi "đăng ký thủ công". Catalog luôn phản ánh đúng thực tế vì việc tạo service và việc đăng ký vào catalog là cùng một hành động.

Bài học rút ra: Catalog chỉ hữu ích khi nó luôn cập nhật. Cách bền vững nhất để giữ nó cập nhật là tự động hóa việc điền dữ liệu ngay trong quy trình tạo và deploy, chứ đừng dựa vào con người cập nhật thủ công.

Tình huống 3 — Startup 15 người và cái bẫy "over-engineering"

Một startup SaaS ở Singapore với 15 kỹ sư và 12 service quyết định triển khai Backstage vì "công ty lớn nào cũng dùng". Họ mất 2 tháng dựng hạ tầng, viết plugin, cấu hình phức tạp. Kết quả: portal ít người dùng, dữ liệu nhanh chóng lỗi thời, và cuối cùng bị bỏ hoang. Với quy mô đó, một file SERVICES.md trong một repo docs chung kèm bảng owner, hoặc một Notion database đơn giản, đã đủ dùng.

Sáu tháng sau, khi công ty lên 40 người và 30 service, họ mới quay lại — nhưng lần này chọn Port (SaaS) để không phải tự vận hành hạ tầng, và bắt đầu từ nhỏ: chỉ import catalog + ownership, chưa vội làm self-service actions.

Bài học rút ra: Developer Portal là công cụ giải quyết đau đớn của quy mô. Dưới ~20 service, cái giá vận hành có thể lớn hơn lợi ích. Hãy để "nỗi đau" xuất hiện thật rồi mới đầu tư đúng liều.

Hướng dẫn từng bước

Dưới đây là lộ trình thực dụng để triển khai một service catalog, minh họa bằng Backstage nhưng nguyên tắc áp dụng cho mọi công cụ.

Bước 1 — Xác định "đau đớn" và phạm vi. Trước khi cài gì, hãy trả lời: bài toán ưu tiên là onboarding chậm, hay tìm owner lúc incident, hay chuẩn hóa việc tạo service? Đừng làm tất cả cùng lúc. Chọn một mục tiêu đo được, ví dụ "giảm thời gian tìm owner khi incident từ 30 phút xuống 5 phút".

Bước 2 — Định nghĩa schema tối thiểu. Xác định tập trường bắt buộc cho mỗi service. Khuyến nghị bắt đầu gọn: name, owner, description, repo, lifecycle, tier (mức độ quan trọng), dashboard, runbook. Thêm trường sau khi thực sự cần.

Bước 3 — Chọn cách khai báo metadata bằng file trong repo. Nguyên tắc vàng: metadata sống cùng code. Với Backstage, mỗi service có file catalog-info.yaml ở gốc repo:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-reconcile
  description: Đối soát giao dịch thanh toán với ngân hàng
  annotations:
    grafana/dashboard-url: https://grafana.vietpay.internal/d/pay-rec
    pagerduty.com/service-id: PXXXXX
  links:
    - url: https://wiki.vietpay.internal/runbooks/payment-reconcile
      title: Runbook
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: payments
  dependsOn:
    - component:ledger-service
    - component:bank-gateway

Việc đặt file này trong repo đảm bảo khi code thay đổi thì metadata cũng được review qua Pull Request, giữ nó luôn khớp thực tế.

Bước 4 — Cấu hình auto-discovery. Cho catalog tự quét toàn bộ GitHub org để tìm mọi file catalog-info.yaml thay vì đăng ký thủ công. Backstage có github-discovery làm việc này. Kết quả: mỗi repo có file khai báo sẽ tự xuất hiện trong catalog.

Bước 5 — Tích hợp CI/CD và observability. Đây là bước biến catalog từ "danh bạ tĩnh" thành "trung tâm sống". Dùng annotation để nhúng trạng thái pipeline (GitHub Actions), phiên bản đang chạy trên mỗi environment, và link dashboard ngay trên trang service. Dev mở portal thấy luôn "service này đang chạy v2.4.1 trên production, build cuối cùng xanh".

Bước 6 — Thêm Software Templates (Golden Path). Tạo template "New Microservice" sinh sẵn cấu trúc chuẩn: Dockerfile, workflow CI/CD, và quan trọng nhất là catalog-info.yaml được điền sẵn. Từ đây, mọi service mới tự động vào catalog đúng chuẩn.

Bước 7 — Đo lường độ phủ và thúc đẩy adoption. Theo dõi tỷ lệ service có owner hợp lệ, có runbook, có dashboard. Đặt mục tiêu (ví dụ 90% service tier-1 phải có runbook). Nhiều đội dùng chính portal để hiển thị "scorecard" chất lượng, tạo áp lực tích cực để các team hoàn thiện metadata.

Lỗi thường gặp & mẹo

Lỗi 1 — Catalog trở thành "nghĩa địa dữ liệu chết". Đây là thất bại phổ biến nhất. Ai đó điền metadata một lần rồi không bao giờ cập nhật; sau 6 tháng owner đã đổi, dashboard đã chuyển, và không ai tin portal nữa. Mẹo: đặt metadata trong repo (không phải wiki riêng), tự động điền qua template, và tự động suy ra thông tin từ nguồn thật (owner từ CODEOWNERS, version từ pipeline). Tránh mọi trường phải nhập tay.

Lỗi 2 — Bắt đầu bằng schema quá phức tạp. Yêu cầu 30 trường bắt buộc ngay từ đầu khiến không team nào chịu điền. Mẹo: bắt đầu với 5-6 trường tối thiểu, tăng dần khi thấy giá trị.

Lỗi 3 — Nhầm lẫn giữa "cài công cụ" và "giải bài toán". Nhiều đội tự hào đã dựng xong Backstage nhưng không ai dùng. Công cụ chỉ là phương tiện. Mẹo: coi Developer Portal như một sản phẩm nội bộ có "khách hàng" là các dev. Phỏng vấn họ, đo mức độ dùng, ưu tiên tính năng gỡ đúng nỗi đau lớn nhất.

Lỗi 4 — Bỏ qua ownership của chính portal. Portal cũng là một service cần owner, cần SLA, cần được nuôi. Nếu để nó "cha chung không ai khóc" thì nó sẽ chết dần. Mẹo: giao portal cho đội Platform/DevEx sở hữu rõ ràng.

Lỗi 5 — Tự host khi chưa đủ nguồn lực. Backstage self-host cần công sức bảo trì đáng kể (nâng cấp, plugin, database). Mẹo: nếu đội nhỏ, cân nhắc SaaS như Port, Roadie, Cortex để tập trung vào giá trị thay vì vận hành hạ tầng.

Mẹo tổng quát: Định nghĩa rõ cấp độ quan trọng (tier) của service. Tier-1 (giao dịch tiền, đăng nhập) cần runbook, on-call, dashboard đầy đủ; tier-3 (công cụ nội bộ) có thể lỏng hơn. Áp dụng chuẩn khác nhau tránh việc "làm quá" cho service nhỏ.

Bài tập thực hành

• Thiết kế schema. Với công ty (thật hoặc giả định) của bạn, hãy liệt kê 6-8 trường metadata tối thiểu cho một service. Giải thích vì sao mỗi trường quan trọng và nguồn dữ liệu tự động cho nó (ví dụ: owner lấy từ CODEOWNERS).

• Viết catalog-info.yaml. Chọn một service tưởng tượng (ví dụ order-service của một sàn TMĐT), viết một file catalog-info.yaml hoàn chỉnh gồm owner, lifecycle, ít nhất 2 dependency, link runbook và annotation dashboard.

• Vẽ dependency graph. Cho 5 service: web-frontend, checkout-api, order-service, payment-reconcile, ledger-service. Vẽ sơ đồ ai gọi ai, và chỉ ra: nếu ledger-service chết thì những service nào bị ảnh hưởng (blast radius).

• Kịch bản incident. Viết ra 5 câu hỏi mà một người on-call cần trả lời trong 2 phút đầu của một incident, và chỉ ra service catalog cung cấp câu trả lời cho từng câu như thế nào.

• Đánh giá quyết định. Một startup 18 người, 14 service, đang cân nhắc dựng Backstage self-host. Hãy viết một đoạn tư vấn ngắn: nên hay không, nếu có thì cách tiếp cận nhẹ nhàng nhất là gì.

Tóm tắt

• Service Catalog là danh sách chuẩn hóa mọi thành phần phần mềm với metadata quan trọng: owner, repo, dependencies, dashboard, runbook, trạng thái CI/CD. Nó giải quyết bài toán "50 service, ai own cái gì, ở đâu".
• Developer Portal (như Backstage, Port, Cortex) là giao diện và trải nghiệm bao quanh catalog, cộng thêm docs-as-code, software templates (Golden Path) và self-service actions.
• Giá trị lớn nhất thể hiện lúc incident (tìm owner/runbook nhanh) và lúc onboarding (new hire không mất cả tuần dò đường).
• Nguyên tắc sống còn: metadata sống cùng code, tự động điền qua template và pipeline, tránh mọi thứ nhập tay để catalog không bị "chết".
• Đây là công cụ giải bài toán của quy mô. Đội nhỏ (dưới ~20 service) có thể bắt đầu bằng file Markdown hoặc Notion; đừng over-engineer. Khi mở rộng, cân nhắc SaaS để khỏi tự vận hành hạ tầng.
• Hãy coi portal là một sản phẩm nội bộ có owner rõ ràng, đo bằng mức độ sử dụng và độ phủ metadata, chứ không phải một dự án "cài xong là xong".