Cài đặt plugin Backstage cho Kubernetes và GitOps
Để Backstage hiển thị trạng thái hạ tầng và quy trình GitOps, chúng ta cần cài đặt các plugin hỗ trợ trực quan hóa Kubernetes và ArgoCD.
Cài đặt plugin backstage-plugin-kubernetes giúp hiển thị danh sách Pod, Service, ConfigMap trong cluster.
Cài đặt plugin backstage-plugin-argo giúp hiển thị trạng thái Sync, Health của các ứng dụng được quản lý bởi ArgoCD.
cd /opt/backstage
npm install @backstage/plugin-kubernetes @backstage/plugin-argo
Kết quả mong đợi: Các thư viện được cài đặt vào node_modules không có lỗi npm.
Cấu hình file app-config.yaml để kích hoạt plugin
Chúng ta cần khai báo các plugin mới trong cấu hình của Backstage để chúng xuất hiện trong menu điều hướng.
Cập nhật file /opt/backstage/app-config.yaml bằng nội dung dưới đây. Lưu ý phần kubernetes và argo.
catalog:
providers:
# Cấu hình Catalog Providers sẽ được làm ở phần tiếp theo
kubernetes:
serviceLocatorMethod:
type: 'multiTenant'
clusterLocatorMethods:
- type: 'config'
clusters:
- name: 'prod-cluster'
url: 'https://k8s-cluster-ip:6443'
authProvider: 'serviceAccountToken'
token: ${K8S_TOKEN}
skipTLSVerify: false
secrets:
method: 'remote'
remote:
url: ${K8S_PROXY_URL}
authProvider: 'serviceAccountToken'
token: ${K8S_TOKEN}
argo:
instances:
- name: 'argocd'
service:
url: 'https://argocd-server.argocd.svc.cluster.local:443'
authProvider: 'serviceAccountToken'
token: ${ARGO_TOKEN}
Kết quả mong đợi: File app-config.yaml được ghi đè, sẵn sàng nhận biến môi trường K8S_TOKEN và ARGO_TOKEN.
Cấu hình packages/app/src/components/catalog/EntityPage.tsx
Chúng ta cần thêm các thành phần (Component) hiển thị thông tin Kubernetes và Argo vào trang chi tiết của thực thể (Entity) trong Catalog.
Sửa file /opt/backstage/packages/app/src/components/catalog/EntityPage.tsx.
Đầu tiên, import các component cần thiết:
import { KubernetesContent } from '@backstage/plugin-kubernetes';
import { ArgoContent } from '@backstage/plugin-argo';
Sau đó, thêm chúng vào trong phần EntityPage, ngay sau phần EntityOverviewCard hoặc EntityRelationsCard.
const EntityPage = (
{/* ... Các phần tử hiện có ... */}
{/* ... Các phần tử còn lại ... */}
);
Kết quả mong đợi: Code được cập nhật, không có lỗi cú pháp TypeScript.
Verify kết quả cài đặt plugin
Chạy lại Backstage để áp dụng thay đổi.
npm run start
Mở trình duyệt truy cập http://localhost:3000. Vào một Component đã có trong Catalog.
Kiểm tra xem có xuất hiện thêm 2 tab mới là Kubernetes Resources và ArgoCD trong menu điều hướng của trang chi tiết Component.
Cấu hình Catalog để hiển thị Composite Resource từ Crossplane
Backstage mặc định không hiểu các tài nguyên Custom (CRD) của Crossplane như Cluster hay Database. Chúng ta cần cấu hình External Annotations để liên kết chúng.
Tạo Annotation cho Crossplane Resources
Khi tạo tài nguyên hạ tầng qua Crossplane, chúng ta cần thêm annotation backstage.io/kubernetes-labels hoặc argocd.argoproj.io/instance để Backstage nhận diện.
Tuy nhiên, để Backstage tự động pull thông tin từ Crossplane, cách tốt nhất là sử dụng kubernetes-plugin để hiển thị các Pod/Service, và dùng EntityPage để hiển thị metadata.
Để hiển thị trực tiếp Composite Resource (như KubeCluster), chúng ta cần đảm bảo tài nguyên đó có metadata.annotations chứa backstage.io/kubernetes-labels trỏ về Component.
apiVersion: kubernetes.crossplane.io/v1alpha1
kind: KubeCluster
metadata:
name: my-cluster-prod
namespace: crossplane-system
annotations:
backstage.io/kubernetes-labels: |
app.kubernetes.io/name: my-app-prod
argocd.argoproj.io/instance: my-app-prod
spec:
# ... spec của Crossplane ...
Kết quả mong đợi: Tài nguyên Crossplane được gắn nhãn (label) và annotation để Backstage có thể ánh xạ ngược lại Component.
Cấu hình Backstage để đọc Annotation
Plugin Kubernetes của Backstage tự động đọc metadata.annotations nếu cấu hình đúng. Chúng ta cần đảm bảo kubernetes trong app-config.yaml (đã cấu hình ở phần trên) có quyền get các tài nguyên Custom.
Role của Service Account dùng bởi Backstage trong Kubernetes cần được mở rộng.
cat > /tmp/backstage-crossplane-rbac.yaml
Kết quả mong đợi: RBAC được áp dụng, Service Account backstage có quyền đọc các tài nguyên Crossplane.
Verify kết quả hiển thị Crossplane
Tạo một tài nguyên Crossplane đơn giản (ví dụ: Cluster) có annotation trỏ về Component trong Catalog.
Vào trang Backstage, chọn Component tương ứng, chuyển sang tab Kubernetes Resources.
Kiểm tra xem có hiển thị danh sách tài nguyên Crossplane (hoặc Pod/Service liên quan) không. Nếu thấy thông tin, nghĩa là liên kết thành công.
Xây dựng mẫu (Template) trong Backstage để tự động hóa việc tạo môi trường
Chúng ta sẽ tạo một Template cho phép người dùng chọn loại môi trường (Staging/Prod), và tự động sinh ra tài nguyên Git Repository (cho ArgoCD) và tài nguyên Crossplane (cho hạ tầng).
Tạo thư mục Template mới
Tạo thư mục chứa template trong cấu trúc Backstage.
mkdir -p /opt/backstage/packages/app/src/components/catalog/templates/create-cluster
Viết file Template YAML
File này định nghĩa các bước (Steps) để tạo hạ tầng. Chúng ta sẽ sử dụng fetch để tạo file cấu hình và publish để push vào Git.
Tạo file /opt/backstage/packages/app/src/components/catalog/templates/create-cluster/template.yaml:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: create-k8s-cluster
title: Create Kubernetes Cluster via Crossplane
description: 'Creates a new Kubernetes cluster using Crossplane and sets up ArgoCD sync'
tags:
- crossplane
- kubernetes
- infrastructure
spec:
owner: group:dev-ops
type: service
parameters:
- title: 'Cluster Configuration'
required:
- name
- region
properties:
name:
title: 'Cluster Name'
type: string
description: 'Unique name for the cluster'
ui:autofocus: true
region:
title: 'Region'
type: string
enum: ['us-east-1', 'eu-west-1', 'ap-southeast-1']
default: 'us-east-1'
environment:
title: 'Environment'
type: string
enum: ['staging', 'production']
default: 'staging'
steps:
- id: fetch
name: Fetch
action: fetch:template
params:
url: ./cluster-template.yaml
values:
name: ${{ parameters.name }}
region: ${{ parameters.region }}
environment: ${{ parameters.environment }}
- id: publish
name: Publish
action: publish:github
params:
token: ${{ secrets.github_token }}
description: 'Cluster infrastructure for ${{ parameters.name }}'
repoUrl: github.com?repo=my-infra-repo&owner=my-org
branch: main
defaultBranch: main
onConflict: overwrite
- id: register
name: Register
action: catalog:register
params:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'
output:
links:
- title: 'Open in GitHub'
url: ${{ steps.publish.output.remoteUrl }}
- title: 'View in ArgoCD'
url: https://argocd-server.argocd.svc.cluster.local
- title: 'View in Backstage'
icon: home
entity: ${{ steps.register.output.entityName }}
Kết quả mong đợi: File template được tạo, định nghĩa rõ ràng các tham số đầu vào và các bước thực thi.
Viết file Template Source (Cluster Template)
File này là mẫu YAML sẽ được Backstage render để tạo ra tài nguyên Crossplane và ArgoCD Application.
Tạo file /opt/backstage/packages/app/src/components/catalog/templates/create-cluster/cluster-template.yaml:
apiVersion: kubernetes.crossplane.io/v1alpha1
kind: KubeCluster
metadata:
name: ${{ name }}
namespace: crossplane-system
annotations:
backstage.io/kubernetes-labels: |
app.kubernetes.io/name: ${{ name }}
argocd.argoproj.io/instance: ${{ name }}
spec:
provider:
name: aws
location: ${{ region }}
managed: true
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: ${{ name }}
namespace: argocd
annotations:
argocd.argoproj.io/sync-policy: automated
spec:
project: default
source:
repoURL: https://github.com/my-org/my-infra-repo
targetRevision: main
path: clusters/${{ name }}
destination:
server: https://kubernetes.default.svc
namespace: crossplane-system
syncPolicy:
automated:
prune: true
selfHeal: true
Kết quả mong đợi: File source template chứa các biến ${{ name }} và ${{ region }} để Backstage thay thế.
Register Template trong Backstage
Để Backstage nhận diện template mới, ta cần cập nhật app-config.yaml hoặc sử dụng file catalog-info.yaml trong thư mục template.
Cách tốt nhất là tạo file catalog-info.yaml trong thư mục template để Backstage tự động quét.
Tạo file /opt/backstage/packages/app/src/components/catalog/templates/create-cluster/catalog-info.yaml:
apiVersion: backstage.io/v1alpha1
kind: Template
metadata:
name: create-k8s-cluster
description: 'Template to create K8s cluster using Crossplane'
spec:
owner: group:dev-ops
Kết quả mong đợi: Template được Backstage nhận diện và hiển thị trong trang "Create" của Catalog.
Verify kết quả Template
Khởi động lại Backstage nếu cần (thường không cần nếu đã cấu hình đúng path).
Vào Backstage, chọn menu Catalog -> Tab Templates.
Chọn template Create Kubernetes Cluster via Crossplane.
Điền thông tin (Name: test-cluster, Region: us-east-1, Env: staging) và click Create.
Kiểm tra trong GitHub Repository: Có file YAML mới được tạo trong thư mục clusters/test-cluster.
Tích hợp workflow: Backstage -> Crossplane -> ArgoCD
Workflow này mô tả luồng tự động hóa: Người dùng tạo app qua Backstage -> Template sinh ra file YAML -> Git push -> ArgoCD phát hiện thay đổi -> Sync -> Crossplane tạo hạ tầng.
Cấu hình ArgoCD để Sync từ Git
ArgoCD đã được cài đặt ở Phần 4. Bây giờ cần cấu hình ApplicationSet hoặc đảm bảo Application được tạo bởi Backstage có thể sync.
Tuy nhiên, vì Template của chúng ta sinh ra file Application YAML trực tiếp, chúng ta chỉ cần đảm bảo ArgoCD có quyền đọc repo đó.
Trong file Application (được tạo bởi Backstage), đường dẫn path: clusters/${{ name }} trỏ đến file KubeCluster.
ArgoCD sẽ áp dụng file KubeCluster này vào cluster.
Quy trình hoạt động (Workflow Execution)
1. **Người dùng**: Mở Backstage, chọn Template, điền thông tin.
2. **Backstage Scaffolder**: Render file cluster-template.yaml -> Tạo file clusters/test-cluster/infra.yaml và catalog-info.yaml.
3. **Git**: Push file vào my-infra-repo trên GitHub.
4. **ArgoCD**: Phát hiện commit mới trên branch main, tự động sync file infra.yaml.
5. **Kubernetes/Crossplane**: Nhận file KubeCluster, Crossplane Controller kích hoạt và tạo tài nguyên AWS (EC2, VPC, EKS) thực tế.
Verify toàn bộ Workflow
Thực hiện tạo một Cluster mới qua Backstage (đã làm ở phần Verify Template).
Quay lại trang ArgoCD trong Backstage (hoặc truy cập UI ArgoCD trực tiếp).
Kiểm tra trạng thái của Application test-cluster:
- Status: Healthy
- Sync Status: Synced
Kiểm tra trên Kubernetes Cluster (qua kubectl hoặc Dashboard):
kubectl get kubeclasses -n crossplane-system
kubectl get pods -n crossplane-system | grep test-cluster
Kiểm tra trên AWS Console (hoặc provider tương ứng):
Xác nhận đã có tài nguyên VPC, EC2 hoặc EKS Cluster được tạo ra với tên tương ứng.
Về lại Backstage, vào Catalog -> Component test-cluster -> Tab Kubernetes Resources.
Xác nhận Backstage hiển thị trạng thái của các Pod/Service thuộc Cluster mới tạo.
Đ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 4: Xây dựng quy trình GitOps với ArgoCD
Phần 6: Tùy chỉnh trải nghiệm người dùng và bảo mật »