Vấn nạn phân mảnh khi đội ngũ kỹ thuật tăng trưởng
Khi một tổ chức kỹ thuật mở rộng quy mô vượt quá 50 kỹ sư, kiến trúc microservice thường bắt đầu trở nên lộn xộn. Tại công ty chúng tôi, việc vượt qua cột mốc 80 microservice đã tạo ra những trở ngại vận hành thực sự rõ rệt.
Các lập trình viên mất hàng giờ trong mỗi sprint chỉ để tìm kiếm những câu trả lời đơn giản: Ai là người chịu trách nhiệm dịch vụ auth-billing? Kênh Slack nào tiếp nhận và xử lý webhook thanh toán? Các hợp đồng gRPC (gRPC contract) được lưu trữ ở đâu? Quá trình onboarding một nhân sự mới kéo dài trọn vẹn hai tuần, phần lớn thời gian chỉ dành cho việc cấu hình môi trường cục bộ, xin cấp quyền IAM và clone các repository nằm rải rác khắp nơi.
Các kỹ sư DevOps phải gánh chịu phần lớn những công việc thủ công, tẻ nhạt này. Thay vì tập trung cải thiện độ tin cậy của hạ tầng, đội ngũ platform của chúng tôi phải dành khoảng 30% thời lượng sprint chỉ để đóng vai trò như một bàn hỗ trợ kỹ thuật (helpdesk). Họ phải tạo repository GitHub thủ công, ghép nối mã mẫu Terraform và sao chép – dán các manifest triển khai Kubernetes giữa các cụm staging và production. Trong khi đó, tài liệu kỹ thuật lại phân tán ở ba nơi đầy mâu thuẫn: các không gian Confluence bị bỏ quên, các file README lỗi thời và các workspace Notion cá nhân.
Chúng tôi cần một giao diện quản lý tập trung (single pane of glass) để giải tỏa bớt gánh nặng nhận thức đó. Đó chính là lúc Spotify Backstage phát huy giá trị. Được Spotify phát triển từ năm 2016 và trao tặng cho CNCF vào năm 2020, Backstage là một framework mã nguồn mở được thiết kế để xây dựng Internal Developer Portal (IDP). Nền tảng này hợp nhất quyền sở hữu dịch vụ, docs-as-code và cơ chế tạo dự án tự động (project scaffolding) vào một trung tâm điều phối duy nhất.
Các khái niệm cốt lõi của Spotify Backstage
Backstage kết hợp frontend bằng React với backend Node.js chạy trên nền Express. Thay vì thay thế các công cụ hạ tầng hiện có, nó tích hợp trực tiếp với chúng—kết nối liền mạch với GitHub, GitLab, Kubernetes, SonarQube và ArgoCD thông qua hệ thống plugin dạng mô-đun. Ba trụ cột nền tảng vận hành toàn bộ hệ thống gồm:
- Software Catalog: Danh mục quản lý tập trung theo dõi các dịch vụ, thư viện, cơ sở dữ liệu và pipeline. Quyền sở hữu, ranh giới hệ thống và quan hệ phụ thuộc giữa các API được khai báo trực tiếp trong mã nguồn thông qua các tệp YAML gọn nhẹ.
- TechDocs: Giải pháp docs-as-code của Spotify. Các kỹ sư viết tài liệu Markdown trực tiếp bên cạnh mã nguồn trong thư mục
/docs. Backstage sử dụng MkDocs để biên dịch và hiển thị các trang HTML hỗ trợ tìm kiếm toàn diện ngay trên giao diện portal. - Software Templates (The Scaffolder): Công cụ tự động hóa giúp chuyển hóa các chuẩn mực kiến trúc thành các biểu mẫu tự phục vụ (self-service). Lập trình viên chỉ cần điền một vài thông tin đầu vào, hệ thống sẽ tự động khởi tạo một repository hoàn chỉnh, được tích hợp sẵn CI/CD pipeline, linter và công cụ giám sát theo đúng chuẩn.
Thực hành: Triển khai và cấu hình Backstage
Bước 1: Khởi tạo phiên bản Backstage của bạn
Đảm bảo máy của bạn đã cài đặt Node.js (phiên bản Active LTS 18 hoặc 20) và Yarn. Backstage phụ thuộc chặt chẽ vào Yarn workspaces, do đó npm không được khuyến nghị để quản lý cấu trúc monorepo này. Chạy lệnh khởi tạo chính thức:
npx @backstage/create-app@latest --skip-install
cd my-developer-portal
yarn install
yarn devGiao diện frontend hoạt động tại http://localhost:3000, trong khi API backend tiếp nhận yêu cầu qua cổng 7007. Khi phát triển cục bộ, Backstage mặc định sử dụng cơ sở dữ liệu SQLite in-memory, tuy nhiên môi trường production thường sẽ kết nối với PostgreSQL 14+.
Bước 2: Định nghĩa các Component trong Software Catalog
Mỗi dịch vụ sẽ công khai metadata của mình trực tiếp qua code. Thêm tệp catalog-info.yaml vào thư mục gốc của repository dịch vụ:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payments-api
description: Dịch vụ điều phối thanh toán cốt lõi xử lý webhook của Stripe
annotations:
github.com/project-slug: itfromzero/payments-api
backstage.io/techdocs-ref: dir:.
tags:
- payments
- go
- grpc
spec:
type: service
lifecycle: production
owner: group:payment-platform-team
system: core-finance
providesApis:
- payments-grpc-apiĐăng ký thực thể này vào tệp cấu hình toàn cục của portal (app-config.yaml):
catalog:
locations:
- type: url
target: https://github.com/itfromzero/payments-api/blob/main/catalog-info.yaml
rules:
- allow: [Component, System, API]Backstage sẽ định kỳ quét vị trí này, đăng ký thực thể và tự động phác thảo sơ đồ phụ thuộc (dependency graph) giữa các dịch vụ của các đội ngũ khác nhau.
Bước 3: Kích hoạt TechDocs (Docs-as-Code)
Các trang wiki tập trung thường nhanh chóng bị mai một và lỗi thời vì chúng tách rời khỏi các pull request thường nhật. TechDocs khắc phục triệt để điều này bằng cách đặt tài liệu kỹ thuật nằm ngay cạnh mã nguồn mà nó mô tả. Thêm tệp mkdocs.yml vào thư mục gốc của repository:
site_name: Tài liệu Payments API
plugins:
- techdocs-core
nav:
- Tổng quan: index.md
- Kiến trúc: architecture.md
- Khắc phục sự cố: troubleshooting.mdSoạn thảo tài liệu hướng dẫn bên trong thư mục docs/ với tệp index.md:
# Payments API
Chào mừng bạn đến với tài liệu kỹ thuật dành cho nhà phát triển của dịch vụ Payments.
## Bắt đầu nhanh
Chạy các dependency cục bộ qua Docker Compose:
```bash
docker-compose up -d redis postgres
go run cmd/server/main.go
```Khi kỹ sư mở component này trên Backstage, hệ sinh thái sẽ nhận diện annotation backstage.io/techdocs-ref, kích hoạt trình biên dịch MkDocs trong container ngầm hoặc worker chuyên biệt, rồi hiển thị tài liệu với đầy đủ tính năng tìm kiếm ngay trong giao diện portal.
Bước 4: Tự động hóa tạo khung dự án Golden Path với Software Templates
Các template tự phục vụ chính là nơi Backstage đem lại lợi tức đầu tư (ROI) nhanh chóng nhất. Thay vì phải mòn mỏi chờ đợi nhiều ngày để đội DevOps phê duyệt ticket cấp phát hạ tầng, lập trình viên chỉ cần điền vào một biểu mẫu trên giao diện web. Template engine sẽ kiểm tra tính hợp lệ của tham số, nhân bản repository khung (skeleton), hoán đổi biến số, tạo Git repository từ xa và tự động thiết lập các quy trình CI/CD mặc định.
Dưới đây là một cấu hình template mẫu hoàn chỉnh (template.yaml):
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: create-standard-microservice
title: Dịch vụ Node.js chuẩn
description: Khởi tạo REST API Node.js sẵn sàng cho production với Docker và GitHub Actions
spec:
owner: group:platform-core
type: service
parameters:
- title: Thông tin chi tiết dịch vụ
required:
- component_id
- description
- owner
properties:
component_id:
title: Tên dịch vụ
type: string
description: Tên component duy nhất dạng kebab-case
description:
title: Mô tả
type: string
owner:
title: Nhóm phụ trách
type: string
ui:field: OwnerPicker
ui:options:
catalogFilter:
kind: Group
- title: Cấu hình Repository
required:
- repoUrl
properties:
repoUrl:
title: Vị trí Repository
type: string
ui:field: RepoUrlPicker
ui:options:
allowedHosts:
- github.com
steps:
- id: fetch-base
name: Tải mã nguồn mẫu Skeleton
action: fetch:template
input:
url: ./skeleton
values:
component_id: ${{ parameters.component_id }}
description: ${{ parameters.description }}
owner: ${{ parameters.owner }}
- id: publish-github
name: Đẩy lên GitHub
action: publish:github
input:
allowedHosts: ['github.com']
description: ${{ parameters.description }}
repoUrl: ${{ parameters.repoUrl }}
defaultBranch: main
- id: register-catalog
name: Đăng ký vào Software Catalog
action: catalog:register
input:
repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'
output:
links:
- title: Mở trên GitHub
url: ${{ steps['publish-github'].output.remoteUrl }}
- title: Xem trong Catalog
icon: catalog
entityRef: ${{ steps['register-catalog'].output.entityRef }}Trong thư mục skeleton/ đi kèm, bạn lưu trữ toàn bộ mã nguồn dựng sẵn chứa các biến thay thế cookiecutter như ${{ values.component_id }}. Khi được kích hoạt, Backstage sẽ tuần tự thực thi các bước, khởi tạo repo GitHub và ngay lập tức đăng ký dịch vụ mới vào Software Catalog của tổ chức.
Trong môi trường production thực tế của chúng tôi, quy trình này đã rút ngắn thời gian khởi tạo một dịch vụ từ khoảng 36 giờ phối hợp liên phòng ban xuống vỏn vẹn 8 phút. Ấn tượng hơn nữa, giải pháp này giải quyết triệt để tình trạng lệch chuẩn cấu hình (configuration drift) ngay từ gốc: mọi repository mới sinh ra đều được cấu hình sẵn endpoint kiểm tra trạng thái (health-check), truy vết với Datadog và tích hợp công cụ quét lỗ hổng bảo mật.
Xây dựng tư duy Platform bền vững
Đưa một Internal Developer Portal vào vận hành là một bước chuyển đổi sâu sắc về tổ chức, chứ không đơn thuần chỉ là bài toán cài đặt công cụ. Hãy đối xử với Backstage như một sản phẩm nội bộ có lộ trình phát triển rõ ràng. Hãy lắng nghe phản hồi từ các nhóm kỹ sư sản phẩm, đặt ra quy định phân định trách nhiệm minh bạch cho catalog, và kiến tạo những golden path sao cho con đường an toàn, chuẩn chỉ nhất cũng chính là con đường thuận tiện, dễ đi nhất đối với lập trình viên.
