Cài đặt và cấu hình plugin Backstage-Crossplane
Triển khai plugin Crossplane trong Backstage
Chúng ta cần tích hợp plugin backstage-plugin-crossplane vào ứng dụng Backstage đã chạy. Plugin này đóng vai trò cầu nối, cho phép Backstage giao tiếp với API của Crossplane để thao tác tài nguyên hạ tầng.
Tại thư mục gốc của dự án Backstage, chạy lệnh sau để cài đặt package:
cd /opt/backstage
yarn add @backstage/plugin-crossplane
Kết quả mong đợi: Terminal hiển thị thông báo cài đặt thành công, package @backpace/plugin-crossplane xuất hiện trong package.json.
Cấu hình đường dẫn đến Crossplane API
Sau khi cài đặt, Backstage cần biết địa chỉ API của Crossplane Controller. Chúng ta sẽ cấu hình trong file app-config.yaml. Giả sử Crossplane đang chạy trong namespace crossplane-system và đã expose qua Service crossplane-api.
Chỉnh sửa file /opt/backstage/app-config.yaml, thêm block crossplane vào cuối file:
---
# ... nội dung config cũ giữ nguyên ...
crossplane:
serviceUrl: http://crossplane-api.crossplane-system:80
# Nếu dùng HTTPS hoặc mTLS, cần cấu hình thêm certPath nếu có
Kết quả mong đợi: File config được lưu, Backstage có thể resolve được endpoint API của Crossplane.
Chạy lại Backstage và Verify
Tái khởi động container Backstage để nạp plugin mới:
cd /opt/backstage
yarn tsc
yarn build
docker-compose up -d
Kiểm tra bằng cách truy cập giao diện Backstage, vào menu "TechDocs" hoặc "Software Catalog" (tùy cấu hình), bạn sẽ thấy mục mới Crossplane hoặc biểu tượng Crossplane xuất hiện trong sidebar. Nếu chưa thấy, hãy check tab "Add-ons" trong Backstage để bật plugin.
Tạo Template mới trong Backstage để tạo môi trường Dev
Tạo thư mục Template
Backstage quản lý template thông qua hệ thống file trong thư mục app/catalog-info.yaml và các file YAML tương ứng. Chúng ta sẽ tạo một template mới cho việc provision môi trường Dev.
Tạo thư mục mới trong cấu trúc app/catalog-info.yaml:
mkdir -p /opt/backstage/app/templates/dev-environment
Kết quả mong đợi: Thư mục dev-environment được tạo thành công.
Thiết kế UI Form trong Backstage
File chính của template là dev-environment.yaml. File này định nghĩa các trường nhập liệu (parameters) mà developer sẽ thấy trên UI, như region và instanceSize.
Tạo file /opt/backstage/app/templates/dev-environment/dev-environment.yaml với nội dung hoàn chỉnh:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: dev-environment
title: Create Dev Environment
description: Tự động tạo môi trường Dev bằng Crossplane Composition
tags:
- crossplane
- kubernetes
- dev
spec:
owner: default-group
type: service
params:
- title: "Cấu hình Hạ tầng"
required:
- region
- instanceSize
properties:
region:
title: "Vùng (Region)"
type: string
description: "Chọn vùng AWS/GCP để triển khai"
enum:
- us-east-1
- ap-southeast-1
ui:
widget: dropdown
instanceSize:
title: "Kích thước Instance"
type: string
description: "Chọn kích thước máy ảo"
enum:
- small
- medium
- large
ui:
widget: dropdown
steps:
- id: fetch-parameters
name: "Nhận thông số"
action: fetch:parameters
input:
url: ./template.yaml
values:
region: ${{ parameters.region }}
instanceSize: ${{ parameters.instanceSize }}
- id: apply-crossplane
name: "Provision qua Crossplane"
action: crossplane:apply
input:
composition: aws-ec2-composition
compositionNamespace: crossplane-system
values:
region: ${{ parameters.region }}
instanceSize: ${{ parameters.instanceSize }}
- id: register
name: "Ghi nhận vào Catalog"
action: catalog:register
input:
catalogInfoPath: ./catalog-info.yaml
output:
links:
- title: "Xem Environment"
icon: "dashboard"
url: ${{ parameters.environmentUrl }}
Kết quả mong đợi: File YAML hợp lệ, định nghĩa rõ các tham số dropdown cho region và instanceSize.
Tạo file Template YAML nội dung
File template.yaml được tham chiếu trong bước fetch:parameters sẽ chứa nội dung YAML thực tế để tạo tài nguyên Crossplane (Claim). File này sẽ được render với các biến từ form.
Tạo file /opt/backstage/app/templates/dev-environment/template.yaml:
apiVersion: v1
kind: Namespace
metadata:
name: dev-env-${{ parameters.environmentName }}
---
apiVersion: compute.aws.crossplane.io/v1alpha1
kind: InstanceClaim
metadata:
name: dev-instance-${{ parameters.environmentName }}
namespace: crossplane-system
spec:
compositionRef:
name: aws-ec2-composition
compositionNamespace: crossplane-system
forProvider:
region: ${{ parameters.region }}
instanceType: ${{ parameters.instanceSize }}
tags:
managed-by: "backstage"
environment: "dev"
Kết quả mong đợi: File YAML chứa cấu trúc InstanceClaim chuẩn Crossplane, sử dụng biến ${{ ... }} để động thay thế giá trị.
Tạo file Catalog Info
File catalog-info.yaml dùng để ghi nhận môi trường vừa tạo vào hệ thống Catalog của Backstage để quản lý vòng đời.
Tạo file /opt/backstage/app/templates/dev-environment/catalog-info.yaml:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: dev-env-${{ parameters.environmentName }}
description: "Môi trường Dev được tạo tự động bởi Backstage + Crossplane"
tags:
- dev
- crossplane
spec:
type: service
owner: default-group
lifecycle: experimental
Kết quả mong đợi: File catalog-info.yaml chuẩn bị sẵn để Backstage register vào catalog.
Liên kết Template Backstage với Composition của Crossplane
Xác định Composition hiện có
Template Backstage ở trên đã tham chiếu đến Composition có tên aws-ec2-composition nằm trong namespace crossplane-system. Chúng ta cần đảm bảo Composition này đã tồn tại trong Kubernetes (đã tạo ở Phần 2).
Verify sự tồn tại của Composition:
kubectl get composition -n crossplane-system | grep aws-ec2
Kết quả mong đợi: Xuất hiện dòng chứa aws-ec2-composition. Nếu không có, Backstage sẽ báo lỗi Composition not found khi chạy template.
Cấu hình Action trong Template
Trong file dev-environment.yaml ở phần trước, bước apply-crossplane sử dụng action crossplane:apply. Đây là action đặc thù của plugin Crossplane, nó sẽ:
- Render file
template.yaml với giá trị từ form.
- Gửi manifest YAML đó đến API Crossplane.
- Crossplane Composition sẽ tự động resolve các tài nguyên cụ thể (AWS EC2, S3, VPC) dựa trên Claim.
Đảm bảo tên composition trong phần input của action khớp chính xác với metadata.name của Composition trong K8s.
Minh họa: Click nút 'Create Environment' và xem hạ tầng được tạo
Thực hiện tạo Environment trên Backstage
Truy cập Backstage UI. Vào tab Templates (hoặc Create tùy giao diện). Bạn sẽ thấy card Create Dev Environment.
Click vào card, form xuất hiện. Thực hiện các bước:
- Chọn Region:
ap-southeast-1.
- Chọn Instance Size:
medium.
- Click nút Create.
Kết quả mong đợi: Backstage hiển thị quá trình chạy các bước (Fetch parameters -> Provision qua Crossplane -> Register). Khi hoàn tất, hiện thông báo Success và link đến Component mới.
Verify hạ tầng được tạo trên Kubernetes
Quay lại terminal, kiểm tra xem Crossplane đã tạo tài nguyên Claim chưa:
kubectl get instanceclaim -n crossplane-system
Kết quả mong đợi: Xuất hiện dòng mới với trạng thái Reconciling hoặc Ready.
Verify tài nguyên hạ tầng thực tế (AWS EC2)
Crossplane Composition đã tạo tài nguyên thực tế. Kiểm tra Instance EC2 trên AWS hoặc qua Kubernetes nếu dùng Provider AWS:
kubectl get instance -n crossplane-system
Kết quả mong đợi: Xuất hiện Instance EC2 với instanceType khớp với medium đã chọn và tag managed-by: backstage.
Verify trong Backstage Catalog
Vào tab Software Catalog trên Backstage. Tìm component có tên dev-env-....
Click vào component, bạn sẽ thấy thẻ Crossplane hiển thị trạng thái của tài nguyên hạ tầng (số lượng Instance, Region, v.v.) được đồng bộ từ Crossplane.
Đ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 4: Cài đặt và tùy chỉnh Backstage để tạo Developer Portal
Phần 6: Quản lý vòng đời môi trường và phân quyền RBAC »