Platform Engineering 7 — Internal Developer Platform & Backstage

Suốt sáu bài đầu của series, platform team đã dựng lần lượt từng lớp năng lực: hạ tầng bằng IaC/Terraform, triển khai bằng GitOps & Argo CD, CI/CD, observability với OpenTelemetry và secrets/policy-as-code. Mỗi lớp mạnh nhưng rời rạc: một developer muốn tạo dịch vụ mới phải biết Terraform, viết Dockerfile, cấu hình pipeline, khai báo Argo CD Application, gắn Vault, thêm dashboard — hàng chục công cụ, hàng trăm quy ước. Đó chính là cognitive load (tải nhận thức) mà tổng quan Platform Engineering mô tả là kẻ thù số một của năng suất. Internal Developer Platform (IDP) là lời giải: gói toàn bộ năng lực đó thành một trải nghiệm tự phục vụ liền mạch, để developer làm việc từ "một cửa" thay vì chạy vòng quanh mười công cụ.

IDP là gì

Internal Developer Platform là lớp tự phục vụ (self-service) hợp nhất, đặt phía trên toàn bộ hạ tầng và công cụ, cho phép developer tìm, tạo, triển khai và vận hành dịch vụ mà không cần rời khỏi một giao diện thống nhất. Nó không thay thế Kubernetes, Terraform hay CI/CD — nó kết dính chúng lại thành golden path (con đường vàng): lối đi được lát sẵn, an toàn theo mặc định, mà đa số việc thường ngày đều đi qua.

Điểm mấu chốt: IDP không phải một sản phẩm mua về, mà là một lớp trải nghiệm platform team tự lắp ghép. Nó biến các câu hỏi thường trực của developer thành thao tác vài cú click:

• "Dịch vụ payment-gateway do team nào sở hữu, gọi API ở đâu?" → tra service catalog.
• "Tôi cần một microservice Python mới có sẵn CI, manifest, secret, dashboard." → chạy một software template.
• "Tài liệu vận hành của dịch vụ này ở đâu?" → đọc TechDocs ngay trong portal.
• "Dịch vụ đang chạy version nào, deploy lần cuối khi nào, tốn bao nhiêu tiền cloud?" → xem plugins gắn vào trang dịch vụ.

Trước IDP, những câu này được trả lời bằng cách hỏi trên Slack, lục wiki cũ, hoặc "hỏi anh X vì chỉ anh ấy biết". IDP biến tri thức ẩn (tribal knowledge) thành dữ liệu có cấu trúc, tra được, chuẩn hóa.

Các thành phần cốt lõi của một IDP

Một IDP trưởng thành thường gồm năm khối chức năng:

Developer Portal là mặt tiền. Nó tập hợp service catalog (danh mục toàn bộ dịch vụ, kèm chủ sở hữu, vòng đời, phụ thuộc), tài liệu, và trạng thái vận hành. Giá trị lớn nhất là khám phá (discoverability): một kỹ sư mới vào có thể tự tìm hiểu hệ thống thay vì phụ thuộc vào người cũ.

Software templates / scaffolding là trái tim tự phục vụ. Thay vì copy-paste một repo cũ rồi sửa tay (dễ sót, dễ lệch chuẩn), developer điền một form ngắn và platform tự sinh (scaffold) toàn bộ khung dịch vụ mới: tạo Git repository, gắn CI pipeline, viết sẵn Kubernetes manifest / Argo CD Application, khai báo secret qua External Secrets, thêm dashboard observability. Mọi thứ ra đời đã "đúng chuẩn" ngay từ commit đầu tiên.

Service catalog là nguồn sự thật về "cái gì tồn tại và ai chịu trách nhiệm". Mỗi thực thể (dịch vụ, API, database, website) được đăng ký bằng metadata có cấu trúc, cho phép truy vấn quan hệ phụ thuộc — cực kỳ quan trọng khi điều tra sự cố hoặc đánh giá tác động thay đổi.

Plugins biến portal tĩnh thành bảng điều khiển sống. Một plugin CI hiển thị trạng thái build; plugin Kubernetes cho thấy pod nào đang chạy; plugin cloud cost ước tính chi phí; plugin security tổng hợp lỗ hổng. Developer thấy toàn cảnh dịch vụ mà không cần mở năm tab công cụ khác nhau.

TechDocs áp dụng triết lý docs-as-code: tài liệu viết bằng Markdown nằm ngay trong repo của dịch vụ, build và render trong portal. Vì docs sống cùng code và đi qua cùng pipeline review, chúng ít lạc hậu hơn wiki tách rời.

Backstage — portal mở phổ biến nhất

Backstage là framework mã nguồn mở do Spotify tạo ra và hiến tặng cho CNCF (Cloud Native Computing Foundation), hiện là dự án phổ biến nhất để tự dựng developer portal. Backstage không phải sản phẩm "cắm là chạy" mà là một nền tảng để xây portal của riêng bạn — chính vì vậy nó linh hoạt nhưng đòi hỏi platform team đầu tư vận hành.

Ba trụ cột kỹ thuật của Backstage:

• Software Catalog — hạt nhân dữ liệu. Mỗi thực thể được mô tả bằng một file catalog-info.yaml đặt trong repo. Backstage quét (discover) các file này và dựng đồ thị quan hệ giữa Component (dịch vụ/thư viện), API, System, Resource, Group (team), User.
• Software Templates — cỗ máy scaffolding. Một template mô tả form đầu vào và chuỗi action (fetch skeleton, publish repo, register catalog...) để sinh dịch vụ mới.
• Plugin ecosystem — kiến trúc mở rộng. Backstage có hàng trăm plugin cộng đồng (Argo CD, GitHub Actions, Kubernetes, PagerDuty, Grafana, Kubecost...) và cho phép viết plugin nội bộ.

Các lựa chọn thay thế đáng lưu ý: Port và Cortex là các IDP SaaS (dịch vụ trả phí, ít công vận hành hơn Backstage tự host); cũng có các nhà cung cấp bán Backstage-based SaaS (Backstage được quản lý hộ, ví dụ Spotify Portal for Backstage, Roadie). Nguyên tắc chọn: Backstage tự host cho tùy biến sâu và không khóa nhà cung cấp; SaaS cho team nhỏ muốn có kết quả nhanh. Bài này minh họa bằng Backstage vì nó là chuẩn de-facto và định hình từ vựng chung (catalog-info.yaml, golden path) cho cả ngành.

Golden path hiện thực qua software template

Golden path chỉ là khẩu hiệu cho tới khi nó được đóng gói thành template chạy được. Luồng scaffolding một dịch vụ mới điển hình:

Trải nghiệm developer: chọn template "Python microservice", điền tên và team sở hữu, bấm Create. Trong vài phút, platform tự làm mọi việc — và mọi việc đã gắn chuẩn bảo mật và observability: logging cấu trúc theo chuẩn công ty, secret lấy qua External Secrets thay vì hard-code, policy-as-code (OPA/Kyverno) áp sẵn, dashboard và alert cơ bản có ngay. Developer không phải nhớ làm những việc đó, cũng không thể quên, vì template đã bake sẵn.

Đây là điểm khác biệt căn bản so với "viết tài liệu hướng dẫn": tài liệu dựa vào kỷ luật con người và luôn phân rã theo thời gian; template biến chuẩn thành mặc định thực thi được. Con đường đúng đồng thời là con đường dễ nhất.

Ví dụ minh họa: catalog-info.yaml và software template

Đăng ký một dịch vụ vào catalog (file catalog-info.yaml trong repo dịch vụ) — đây là YAML minh họa:

# MINH HOẠ — khai báo một Component trong Backstage catalog
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: loan-scoring-api
  description: "API chấm điểm tín dụng khoản vay"
  annotations:
    backstage.io/techdocs-ref: dir:.          # TechDocs cùng repo
    argocd/app-name: loan-scoring-api          # nối plugin Argo CD
spec:
  type: service
  lifecycle: production
  owner: team-data-credit                      # ownership rõ ràng
  system: credit-platform
  dependsOn:
    - resource:postgres-credit
    - component:feature-store

Một software template rút gọn để scaffold dịch vụ mới — YAML minh họa:

# MINH HOẠ — Backstage software template (golden path)
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-service-golden-path
  title: "Python Microservice (chuẩn NCB)"
spec:
  parameters:
    - title: Thông tin dịch vụ
      required: [name, owner]
      properties:
        name: { type: string, title: "Tên service" }
        owner: { type: string, title: "Team sở hữu" }
  steps:
    - id: fetch
      name: Lấy skeleton golden-path
      action: fetch:template
      input:
        url: ./skeleton              # có sẵn Dockerfile, CI, manifest, dashboard
        values: { name: "${{ parameters.name }}" }
    - id: publish
      name: Tạo Git repository
      action: publish:github
      input:
        repoUrl: "github.com?owner=ncb&repo=${{ parameters.name }}"
    - id: register
      name: Đăng ký vào catalog
      action: catalog:register
      input:
        catalogInfoUrl: "...${{ parameters.name }}/catalog-info.yaml"

Ba steps trên chính là hiện thân của golden path: fetch khung chuẩn, publish repo, register vào catalog — sau đó CI/CD và GitOps đã dựng ở các bài trước tự tiếp quản.

Đo lường DX và adoption — platform-as-product

Một IDP xây xong nhưng không ai dùng là thất bại đắt giá. Vì thế platform hiện đại vận hành theo tư duy platform-as-product: coi developer là khách hàng nội bộ, có roadmap, thu thập phản hồi, và đo lường bằng số liệu chứ không bằng cảm tính.

Hai nhóm chỉ số cần theo dõi:

• Developer Experience (DX) — trải nghiệm và năng suất. Nền tảng phổ biến để đo là DORA (deployment frequency, lead time for changes, change failure rate, time to restore) và khung SPACE. IDP tốt sẽ kéo lead time xuống và tăng tần suất deploy vì bỏ được ma sát thủ công.
• Adoption (mức độ áp dụng) — bao nhiêu % dịch vụ mới được tạo qua golden path, bao nhiêu team dùng portal hằng tuần, tỉ lệ dịch vụ đã đăng ký catalog. Adoption thấp là tín hiệu golden path chưa đủ dễ hoặc chưa đủ tốt so với cách tự làm.

Tư duy sản phẩm còn nghĩa là: golden path phải tốt hơn cách tự dựng, không chỉ bắt buộc. Nếu developer thấy template gò bó, họ sẽ đi đường vòng và platform mất giá trị. Platform team lắng nghe feedback, ưu tiên trên roadmap, phát hành cải tiến — hệt như một sản phẩm thương mại.

Bối cảnh ngân hàng: nhúng tuân thủ vào template

Với một ngân hàng như NCB, giá trị lớn nhất của IDP không chỉ là tốc độ mà là tuân thủ nhúng sẵn (compliance-by-default). Trong môi trường chịu quản lý chặt (yêu cầu của cơ quan quản lý, kiểm toán nội bộ, phân loại dữ liệu nhạy cảm), mỗi dịch vụ mới phải thỏa hàng loạt điều kiện: logging tập trung phục vụ audit, secret quản lý qua Vault, nhãn phân loại dữ liệu, policy chặn image chưa ký, network policy zero-trust.

Nếu để mỗi team tự nhớ và tự làm, tỉ lệ sai sót cao và kiểm toán vất vả. Với IDP, các yêu cầu đó được bake vào golden-path template một lần: mọi dịch vụ scaffold ra đều tự động có logging chuẩn, secret đúng cách, policy áp sẵn. Kiểm toán chuyển từ "rà từng dịch vụ xem có tuân thủ không" sang "chứng minh mọi dịch vụ đều sinh từ template đã được phê duyệt". Đây là sự dịch chuyển từ tuân thủ phản ứng sang tuân thủ theo thiết kế — nối trực tiếp với secrets & policy-as-code và các nguyên tắc truy cập & mã hóa.

Use case thực tế

Bối cảnh: Team Dữ liệu NCB thường xuyên cần dựng dịch vụ và pipeline mới — một API chấm điểm tín dụng, một job ingest dữ liệu giao dịch, một feature service. Trước khi có IDP, quy trình khởi tạo một dịch vụ mới mất khoảng 3–5 ngày làm việc: copy một repo cũ, sửa Dockerfile, cấu hình pipeline, xin cấp secret, viết manifest, khai báo Argo CD Application, dựng dashboard, và gần như luôn có vài bước lệch chuẩn phải sửa lại sau review bảo mật. Kỹ sư mới onboard mất 2–3 tuần mới tự tạo được dịch vụ đúng chuẩn.

Giải pháp: Platform team dựng Backstage làm developer portal và đóng gói một golden-path template python-service-golden-path. Template gắn sẵn: CI pipeline, GitOps qua Argo CD, secret qua External Secrets/Vault, logging cấu trúc, policy-as-code, và dashboard observability cơ bản. Toàn bộ dịch vụ hiện hữu được đăng ký catalog-info.yaml để tra ownership và phụ thuộc.

Kết quả (số liệu ước lượng, minh họa):

Một analyst nghiệp vụ có nền kỹ thuật giờ có thể tự tạo một data API mới từ portal, thay vì mở ticket chờ platform team — trong khi mọi ràng buộc tuân thủ vẫn được đảm bảo tự động. Platform team chuyển từ vai "làm hộ từng việc" sang "làm sản phẩm cho nhiều người dùng", đúng tinh thần platform-as-product.

Ghi nhớ

• IDP là lớp tự phục vụ hợp nhất giúp developer tìm/tạo/triển khai/vận hành dịch vụ từ "một cửa"; nó kết dính IaC, GitOps, CI/CD, observability, secrets thành golden path liền mạch, không thay thế chúng.
• Năm thành phần cốt lõi: developer portal, software templates/scaffolding, service catalog, plugins, TechDocs. Scaffolding là trái tim tự phục vụ; catalog là nguồn sự thật về ownership và phụ thuộc.
• Backstage (Spotify → CNCF) là framework mở phổ biến nhất để tự dựng portal: dựa trên catalog-info.yaml, software templates và hệ sinh thái plugin. Lựa chọn khác: Port, Cortex, hoặc Backstage-based SaaS.
• Golden path chỉ thực sự tồn tại khi được đóng gói thành template chạy được: developer điền form, platform sinh repo + pipeline + manifest + secret + dashboard, đã gắn chuẩn bảo mật/observability ngay từ commit đầu.
• Vận hành theo tư duy platform-as-product: đo DX (DORA/SPACE) và adoption, có roadmap và feedback; golden path phải tốt hơn cách tự làm, không chỉ bắt buộc.
• Trong ngân hàng, giá trị lớn nhất là compliance-by-default: nhúng logging/secret/policy vào template một lần để mọi dịch vụ mới tự tuân thủ — kiểm toán chuyển từ rà từng dịch vụ sang chứng minh mọi thứ sinh từ template đã duyệt.

Nguồn tham khảo

• Backstage Documentation — tài liệu chính thức: Software Catalog, catalog-info.yaml, Software Templates (Scaffolder), Plugins, TechDocs.
• Backstage — CNCF Project — trang dự án Backstage tại Cloud Native Computing Foundation (do Spotify hiến tặng).
• Matthew Skelton & Manuel Pais — Team Topologies: Organizing Business and Technology Teams for Fast Flow (IT Revolution, 2019). Nền tảng khái niệm platform team, cognitive load, platform-as-a-product.
• DORA — DevOps Research and Assessment — bốn chỉ số DORA (deployment frequency, lead time for changes, change failure rate, time to restore).
• Nicole Forsgren, Margaret-Anne Storey, Chandra Maddila, et al. — The SPACE of Developer Productivity (ACM Queue, 2021). Khung SPACE đo lường năng suất & trải nghiệm developer.
• Spotify Engineering — What the heck is Backstage anyway? — bối cảnh Backstage do Spotify tạo ra và động cơ xây developer portal nội bộ.