Triển khai Backstage từ Helm Chart
Chuẩn bị Helm Repository và Namespace
Trước tiên, ta cần thêm repository chính thức của Backstage vào Helm client để tải chart mới nhất. Đồng thời tạo namespace riêng để cô lập môi trường phát triển.
Lý do: Việc dùng namespace riêng giúp dễ dàng quản lý tài nguyên, xóa toàn bộ môi trường khi cần reset, và tránh xung đột với các dịch vụ khác trên cluster.
Kết quả mong đợi: Repository được thêm thành công và namespace "backstage" được tạo.
helm repo add backstage https://backstage.github.io/backstage-helm-charts
helm repo update
kubectl create namespace backstage
Cấu hình giá trị cơ bản cho Helm Release
Tạo file values.yaml để định cấu hình cho Backstage, bao gồm service type, resource limits và các biến môi trường cơ bản. Đây là bước thay thế cho việc cài đặt từ source, giúp quy trình deployment nhanh hơn và dễ bảo trì.
Lý do: Sử dụng Helm chart giúp chuẩn hóa quy trình cài đặt, tự động hóa việc tạo Deployment, Service, Ingress và ConfigMap.
Kết quả mong đợi: File values.yaml được tạo sẵn sàng để truyền vào lệnh install.
cat > values.yaml
Thực hiện lệnh cài đặt Backstage
Chạy lệnh helm install để triển khai Backstage vào namespace đã tạo, sử dụng file values.yaml vừa cấu hình.
Lý do: Lệnh này kích hoạt Kubernetes tạo các Pod, Service và ConfigMap cần thiết để chạy ứng dụng Backstage.
Kết quả mong đợi: Backstage được cài đặt thành công, trạng thái các Pod chuyển sang Running sau vài phút.
helm install backstage backstage/backstage -n backstage -f values.yaml
Verify kết quả triển khai
Đảm bảo tất cả các Pod của Backstage đang chạy ổn định và Service đã được expose đúng cổng.
kubectl get pods -n backstage
kubectl get svc -n backstage
Cấu hình Database và Authentication trong app.config.yaml
Triển khai Database PostgreSQL
Backstage cần một database để lưu trữ metadata của các project và user. Ta sẽ dùng Helm chart của Bitnami để deploy PostgreSQL nhanh chóng vào cluster.
Lý do: Sử dụng database stateful riêng biệt đảm bảo dữ liệu không bị mất khi Pod Backstage bị restart, đồng thời tách biệt layer dữ liệu khỏi ứng dụng.
Kết quả mong đợi: Database PostgreSQL được tạo trong namespace "backstage" với username và password mặc định hoặc tùy chỉnh.
helm install postgres bitnami/postgresql -n backstage --set auth.postgresPassword=secret-db-password --set primary.persistence.size=10Gi
Chỉnh sửa ConfigMap chứa app.config.yaml
Backstage lưu cấu hình trong ConfigMap. Ta cần chỉnh sửa ConfigMap này để trỏ backend về database PostgreSQL vừa tạo và cấu hình authentication key.
Lý do: File app.config.yaml là "tim" của Backstage, quyết định cách nó kết nối với hạ tầng và xác thực người dùng. Nếu không cấu hình đúng, backend sẽ crash hoặc không lưu được dữ liệu.
Kết quả mong đợi: ConfigMap được cập nhật, chứa thông tin kết nối database chính xác và key xác thực.
kubectl edit configmap backstage-config -n backstage
Sau khi lệnh edit mở ra, thay thế toàn bộ nội dung của key `app-config.yaml` bằng nội dung dưới đây. Lưu ý thay thế `postgres` bằng hostname của database nếu bạn đặt tên khác.
apiVersion: v1
kind: ConfigMap
metadata:
name: backstage-config
namespace: backstage
data:
app-config.yaml: |
app:
title: My Company IDP
baseUrl: http://localhost:3000
backend:
baseUrl: http://backstage.backstage.svc.cluster.local:7007
listen:
port: 7007
database:
client: postgres
connection:
host: postgres
port: 5432
user: postgres
password: secret-db-password
# Không dùng sslmode: require trong môi trường dev nội bộ để tránh lỗi cert
# sslmode: require
auth:
keys:
- secret: my-super-secret-backstage-key-change-me
catalog:
import:
entityFilename: entities.yaml
rules:
- allow: [Component, System, API, Resource, Location]
rules:
- allow: [Component, System, API, Resource, Location]
techdocs:
builder: local
generator:
runner: local
publisher:
type: local
scaffolder:
catalog:
inputDefaults:
- name: repoUrl
type: string
- name: title
type: string
default: My Project
Restart Backend để áp dụng cấu hình mới
Sau khi cập nhật ConfigMap, cần restart Pod backend để nó đọc lại cấu hình mới từ ConfigMap.
Lý do: Kubernetes không tự động reload cấu hình từ ConfigMap vào môi trường đang chạy, trừ khi Pod được tạo mới hoặc restart.
Kết quả mong đợi: Pod backend bị xóa và tạo lại, logs hiển thị quá trình kết nối database thành công.
kubectl rollout restart deployment backstage-backend -n backstage
Verify kết quả cấu hình Database
Chạy lệnh xem logs của backend để kiểm tra thông báo kết nối database thành công (Connected to database).
kubectl logs -f deployment/backstage-backend -n backstage | grep -i "database\|connected"
Tùy chỉnh Giao diện UI và Theme cho Doanh nghiệp
Tạo Theme Custom trong Source Code
Để thay đổi màu sắc, logo và font chữ, ta cần tạo một thư mục theme trong cấu trúc source của Backstage (nếu build từ source) hoặc dùng plugin `@backstage/plugin-app-theme` nếu deploy từ Docker image đã có sẵn plugin. Ở đây ta giả định bạn đang build từ source để tùy chỉnh sâu.
Lý do: Default theme của Backstage mang tính generic. Doanh nghiệp cần nhận diện thương hiệu (logo, màu chủ đạo) để tạo sự tin tưởng cho developer.
Kết quả mong đợi: File theme.js được tạo trong thư mục `plugins/app` hoặc `src/components`.
mkdir -p src/components/Theme
cat > src/components/Theme/MyCompanyTheme.ts
Áp dụng Theme vào App Router
Chỉnh sửa file `App.tsx` để bao bọc toàn bộ ứng dụng bằng ThemeProvider và import theme vừa tạo.
Lý do: ThemeProvider của Material-UI cần được đặt ở cấp cao nhất để áp dụng theme cho toàn bộ component tree.
cat > src/components/App.tsx
Build và Deploy lại với Theme mới
Build lại Docker image chứa source code đã chỉnh sửa và đẩy lên registry, sau đó update Helm release để sử dụng image mới.
Lý do: Thay đổi code frontend (React) yêu cầu quá trình build lại thành file static và đóng gói vào container mới.
docker build -t my-registry/my-company-backstage:latest .
docker push my-registry/my-company-backstage:latest
helm upgrade backstage backstage/backstage -n backstage --set image.repository=my-registry/my-company-backstage --set image.tag=latest
Verify kết quả UI
Mở trình duyệt truy cập vào URL của Backstage (thường qua port-forward) và kiểm tra màu sắc, logo đã thay đổi theo theme chưa.
kubectl port-forward svc/backstage 3000:7007 -n backstage
Cấu hình Plugin App và TechDocs
Cấu hình Plugin App (Catalog)
Plugin App là nơi hiển thị danh sách các Component, System, API. Cần cấu hình `catalog` trong `app-config.yaml` để Backstage biết quét nguồn dữ liệu từ đâu (thường là Git repo chứa file `catalog-info.yaml`).
Lý do: Không có cấu hình này, dashboard App sẽ trống trơn vì không có nguồn dữ liệu nào để import.
kubectl edit configmap backstage-config -n backstage
Thêm hoặc cập nhật phần `catalog` trong `app-config.yaml` như sau:
catalog:
import:
entityFilename: catalog-info.yaml
rules:
- allow: [Component, System, API, Resource, Location]
scan:
schedule:
frequency: { minutes: 60 }
timeout: { minutes: 10 }
rules:
- allow: [Component, System, API, Resource, Location]
processors:
github:
runOn: [event, scheduled]
schedule: { frequency: { minutes: 5 } }
Cấu hình Plugin TechDocs
TechDocs tự động tạo tài liệu từ file README.md trong repository code. Cần cấu hình `techdocs` để chỉ định nơi lưu trữ tài liệu (publisher) và cách build (builder).
Lý do: Mặc định TechDocs chỉ chạy local. Để hiển thị tài liệu online, cần cấu hình để publish lên object storage (như S3, MinIO) hoặc dùng plugin `techdocs-cli` tích hợp sẵn.
kubectl edit configmap backstage-config -n backstage
Cập nhật phần `techdocs` trong `app-config.yaml` (giả sử dùng local storage cho dev, production sẽ cần S3/MinIO):
techdocs:
builder: local
generator:
runner: local
publisher:
type: local
local:
storageDir: /tmp/techdocs
Lưu ý: Nếu deploy production, cần thay `publisher.type` thành `s3` hoặc `gcs` và cung cấp credentials tương ứng.
Thêm Plugin TechDocs vào giao diện
Nếu build từ source, cần đảm bảo plugin `techdocs` được import trong `packages/app/src/components/App.tsx` hoặc `src/App.tsx`.
cat >> src/components/App.tsx
Verify kết quả Plugin
Tạo một file `catalog-info.yaml` mẫu trong một repo Git, cấu hình Backstage để scan repo đó, sau đó vào trang App để xem Component xuất hiện và vào tab Documentation để xem TechDocs.
# Tạo file mẫu catalog-info.yaml
cat > /tmp/test-catalog-info.yaml xem thành phần
# Vào Backstage UI -> Documentation -> xem tài liệu (nếu có README)
Verify tổng thể
Khởi động lại backend để áp dụng tất cả cấu hình plugin mới.
kubectl rollout restart deployment backstage-backend -n backstage
Truy cập UI và kiểm tra:
- Tab "App": Có hiển thị component "my-test-service" không?
- Tab "Documentation": Có thể xem tài liệu không?
- Giao diện: Màu sắc đã đổi theo theme chưa?
Điều hướng series:
Mục lục: Series: Series: Xây dựng nền tảng Internal Developer Platform (IDP) với Backstage, Crossplane và GitOps trên Kubernetes để tối ưu trải nghiệm phát triển phần mềm
« Phần 1: Chuẩn bị môi trường và kiến trúc tổng quan cho IDP
Phần 3: Cấu hình Crossplane để quản lý tài nguyên hạ tầng »