Triển khai Backstage Core trên Kubernetes với Helm
Chúng ta sẽ khởi tạo namespace riêng cho Backstage để cô lập tài nguyên và tránh xung đột với các service khác trong cluster.
kubectl create namespace backstage
Namespace "backstage" được tạo thành công, sẵn sàng chứa các workload.
Thêm Helm repository chính thức của Backstage vào local client để tải chart mới nhất.
helm repo add backstage https://backstage.github.io/charts
helm repo update
Repository được thêm và danh sách chart được cập nhật, sẵn sàng cài đặt.
Tạo file values.yaml tùy chỉnh để cấu hình backend, frontend, database và storage ngay từ bước đầu. File này sẽ được lưu tại đường dẫn /tmp/backstage-values.yaml.
apiVersion: v1
kind: ConfigMap
metadata:
name: backstage-config
namespace: backstage
data:
app-config.yaml: |
app:
title: Internal Developer Portal
baseUrl: https://portal.internal.company.com
backend:
baseUrl: http://backstage-backend:7007
auth:
providers:
github:
development:
clientId: ${GITHUB_CLIENT_ID}
clientSecret: ${GITHUB_CLIENT_SECRET}
database:
connection: postgresql://backstage:password@backstage-postgres:5432/backstage
catalog:
providers:
github:
org1:
token: ${GITHUB_TOKEN}
techdocs:
builder: 'local'
publisher:
type: 'gcs'
baseUrl: https://storage.internal.company.com
bucketName: techdocs
gcsCredentials: ${GCS_CREDENTIALS}
kubernetes:
serviceLocatorMethod:
type: 'multiTenant'
clusterLocatorMethodName: 'config'
clusters:
- name: production
url: https://k8s-api.internal.company.com
skipTLSVerify: false
authProvider: 'serviceAccountToken'
---
apiVersion: v1
kind: Secret
metadata:
name: backstage-secrets
namespace: backstage
type: Opaque
stringData:
GITHUB_CLIENT_ID: "your_github_client_id"
GITHUB_CLIENT_SECRET: "your_github_client_secret"
GITHUB_TOKEN: "your_github_token"
GCS_CREDENTIALS: |
{
"type": "service_account",
"project_id": "your-project",
"private_key_id": "key_id",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"client_email": "svc@your-project.iam.gserviceaccount.com",
"client_id": "123456",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/svc%40your-project.iam.gserviceaccount.com"
}
ConfigMap chứa cấu hình ứng dụng và Secret chứa thông tin nhạy cảm đã được tạo trong namespace backstage.
Triển khai Backstage bằng Helm chart, trỏ đến file values.yaml vừa tạo để khởi tạo tất cả các component (backend, frontend, database, storage).
helm install backstage backstage/backstage \
--namespace backstage \
--values /tmp/backstage-values.yaml \
--set backend.extraVolumeMounts[0].name=secrets \
--set backend.extraVolumeMounts[0].mountPath=/app/secrets \
--set backend.extraVolumes[0].name=secrets \
--set backend.extraVolumes[0].secret.secretName=backstage-secrets \
--set postgres.enabled=true \
--set postgres.postgresPassword=password \
--set minio.enabled=true \
--set minio.rootUser=minioadmin \
--set minio.rootPassword=minioadmin \
--set ingress.enabled=true \
--set ingress.hosts[0].host=portal.internal.company.com \
--set ingress.tls.enabled=true \
--set ingress.tls.secretName=backstage-tls
Helm hoàn tất việc cài đặt, các pod backend, frontend, postgres và minio đang trong trạng thái Pending hoặc Running.
Verify kết quả bằng cách liệt kê tất cả pod trong namespace backstage và kiểm tra trạng thái.
kubectl get pods -n backstage
Tất cả pod phải chuyển sang trạng thái "Running" với restart count = 0 sau khoảng 2-3 phút.
Cấu hình Database và Storage cho Backstage
Backstage yêu cầu PostgreSQL để lưu trữ metadata catalog và MinIO (S3 compatible) để lưu trữ tài liệu TechDocs. Chúng ta sẽ cấu hình các service này trong cùng cluster.
Đảm bảo PostgreSQL pod đang chạy và sẵn sàng chấp nhận kết nối từ backend.
kubectl exec -it backstage-postgres-0 -n backstage -- psql -U postgres -c "SELECT 1;"
Command trả về "1" xác nhận database đã khởi động và sẵn sàng.
Kiểm tra MinIO server đã khởi động và có thể truy cập qua internal URL.
kubectl port-forward svc/backstage-minio 9000:9000 -n backstage
Terminal hiển thị "Forwarding from 127.0.0.1:9000 -> 9000", xác nhận MinIO đang lắng nghe port.
Tạo bucket "techdocs" trong MinIO để lưu trữ tài liệu tự động sinh ra từ code.
mc alias set myminio http://localhost:9000 minioadmin minioadmin
mc mb myminio/techdocs
Bucket "techdocs" được tạo thành công, sẵn sàng cho plugin TechDocs sử dụng.
Verify kết quả bằng cách liệt kê bucket trong MinIO.
mc ls myminio
Danh sách bucket hiển thị "techdocs" với thời gian tạo gần đây.
Tích hợp Backstage với Git Provider (GitHub/GitLab)
Để Backstage tự động quét và hiển thị các repository, chúng ta cần cấu hình Catalog Provider trong app-config.yaml.
Cập nhật lại ConfigMap để thêm cấu hình GitHub Organization hoặc GitLab Group.
kubectl edit configmap backstage-config -n backstage
File cấu hình mở ra trong editor, cho phép chỉnh sửa trực tiếp.
Thêm đoạn cấu hình catalog.providers vào app-config.yaml trong ConfigMap. Ví dụ dưới đây cho GitHub.
catalog:
providers:
github:
org1:
# Thay bằng token thực tế của GitHub App hoặc Personal Access Token
token: ${GITHUB_TOKEN}
# Tên organization trên GitHub
organization: my-company-org
# Loại entity: user hoặc repo
types:
- user
- repo
ConfigMap được cập nhật, Backstage sẽ đọc token từ secret đã tạo trước đó.
Khởi động lại Backstage backend để áp dụng thay đổi cấu hình.
kubectl rollout restart deployment backstage-backend -n backstage
Deployment được restart, pod mới sẽ load cấu hình catalog mới.
Verify kết quả bằng cách vào trang Backstage (http://localhost:7007) và kiểm tra tab "Catalog".
curl -s http://localhost:7007/api/catalog/entities | jq '.items | length'
API trả về số lượng entity lớn hơn 0, xác nhận Backstage đã lấy được thông tin từ GitHub.
Cấu hình Plugin TechDocs để tự động tạo tài liệu
Plugin TechDocs cho phép developer tạo tài liệu ngay trong code repository và Backstage tự động build, publish lên storage.
Cấu hình TechDocs trong app-config.yaml để chỉ định builder và publisher.
kubectl edit configmap backstage-config -n backstage
Editor mở ra, sẵn sàng chỉnh sửa cấu hình techdocs.
Thêm hoặc cập nhật phần techdocs trong app-config.yaml. Cấu hình này sử dụng "local" builder (chạy trong pod) và "gcs" publisher (thực chất là S3 compatible như MinIO).
techdocs:
builder: 'local'
publisher:
type: 'gcs'
baseUrl: https://storage.internal.company.com
bucketName: techdocs
gcsCredentials: ${GCS_CREDENTIALS}
Cấu hình được lưu, Backstage biết cách lấy code từ repo và build tài liệu vào MinIO.
Tạo một repository mẫu có file README.md và thư mục docs để test tính năng TechDocs.
mkdir /tmp/test-repo
cd /tmp/test-repo
echo "name: test-service" > catalog-info.yaml
mkdir docs
echo "# Test Documentation" > docs/index.md
git init
git add .
git commit -m "Initial commit with techdocs"
Repository mẫu được tạo với file catalog-info.yaml và docs/index.md.
Verify kết quả bằng cách kích hoạt tính năng "TechDocs" trong Backstage UI sau khi thêm repository vào catalog.
curl -s http://localhost:7007/api/catalog/entities/test-service | jq '.metadata.annotations.techdocs'
API trả về thông tin metadata chứa key "techdocs", xác nhận plugin đã nhận diện tài liệu.
Thiết lập Authentication (OAuth2) cho Developer
Để developer truy cập portal, chúng ta cần cấu hình OAuth2 provider (GitHub/GitLab/Google) trong Backstage.
Tạo OAuth2 Application trên GitHub Developer Settings và lấy Client ID, Client Secret.
echo "CLIENT_ID=your_github_client_id" >> /tmp/backstage-secrets.txt
echo "CLIENT_SECRET=your_github_client_secret" >> /tmp/backstage-secrets.txt
Thông tin OAuth2 được lưu vào file tạm để cập nhật vào Secret.
Cập nhật Secret backstage-secrets với thông tin OAuth2 mới.
kubectl create secret generic backstage-secrets \
--from-literal=GITHUB_CLIENT_ID=$(grep CLIENT_ID /tmp/backstage-secrets.txt | cut -d'=' -f2) \
--from-literal=GITHUB_CLIENT_SECRET=$(grep CLIENT_SECRET /tmp/backstage-secrets.txt | cut -d'=' -f2) \
--from-literal=GITHUB_TOKEN=your_github_token \
--from-file=GCS_CREDENTIALS=/tmp/gcs-credentials.json \
-n backstage \
--dry-run=client -o yaml | kubectl apply -f -
Secret được cập nhật, chứa đầy đủ thông tin xác thực cho OAuth2.
Cấu hình backend để sử dụng provider OAuth2 trong app-config.yaml.
kubectl edit configmap backstage-config -n backstage
Editor mở ra, sẵn sàng chỉnh sửa phần auth.
Thêm cấu hình auth.providers vào app-config.yaml trong ConfigMap.
backend:
auth:
providers:
github:
development:
clientId: ${GITHUB_CLIENT_ID}
clientSecret: ${GITHUB_CLIENT_SECRET}
# Redirect URI phải khớp với cấu hình trên GitHub
# Ví dụ: http://localhost:7007/auth/github/handling
ConfigMap được cập nhật, Backstage backend biết cách xử lý OAuth flow.
Khởi động lại Backstage backend để áp dụng cấu hình authentication.
kubectl rollout restart deployment backstage-backend -n backstage
Deployment được restart, pod mới sẽ load cấu hình auth mới.
Verify kết quả bằng cách truy cập Backstage UI và nhấn nút "Sign in with GitHub".
curl -s -I http://localhost:7007/auth/github/login
Response header chứa "Location: https://github.com/login/oauth/authorize..." xác nhận OAuth flow đã được kích hoạt.
Điều hướng series:
Mục lục: Series: Series: Xây dựng hệ thống Platform Engineering nội bộ với Crossplane, Backstage và GitOps trên hạ tầng Kubernetes để tự động hóa môi trường Dev
« Phần 3: Xây dựng quy trình GitOps với ArgoCD và Crossplane
Phần 5: Tích hợp Backstage với Crossplane để tạo Template tự động »