Triển khai Crossplane Controller và Runtime
Cài đặt Crossplane qua Helm
Chúng ta sẽ sử dụng Helm chart chính thức để triển khai Crossplane vào namespace crossplane-system. Đây là bước nền tảng để chạy các controller quản lý tài nguyên.
Thực hiện lệnh sau để thêm repo và cài đặt phiên bản mới nhất:
helm repo add crossplane https://charts.crossplane.io/stable
helm repo update
helm install crossplane crossplane/crossplane \
--namespace crossplane-system \
--create-namespace \
--version 1.15.0 \
--set crossplaneRuntime.config.clusterClaimNamespace=platform-ops
Kết quả mong đợi: Helm trả về thông báo "INSTALLATION SUCCEEDED". Các Pod trong namespace crossplane-system sẽ chuyển sang trạng thái Running sau 1-2 phút.
Verify trạng thái triển khai
Để đảm bảo Crossplane hoạt động đúng, chúng ta cần kiểm tra trạng thái của các Pod và API Server.
kubectl get pods -n crossplane-system
kubectl get crd | grep crossplane.io
Kết quả mong đợi: Tất cả Pod (crossplane-runtime, crossplane-controller) đều ở trạng thái Running. Danh sách Custom Resource Definitions (CRD) hiển thị các tài nguyên cơ bản của Crossplane như composition.crossplane.io, compositionrevision.crossplane.io.
Cấu hình Provider cho Cloud Provider
Triển khai AWS Provider
Chúng ta cần triển khai Provider cụ thể để Crossplane có thể giao tiếp với hạ tầng cloud. Ở đây chọn AWS làm ví dụ minh họa cho tài nguyên EC2 và S3.
Tạo file cấu hình Provider với đường dẫn /home/admin/crossplane-configs/provider-aws.yaml:
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v1.0.0
Áp dụng cấu hình này vào cluster:
kubectl apply -f /home/admin/crossplane-configs/provider-aws.yaml
Kết quả mong đợi: Resource Provider được tạo. Sau khoảng 2-3 phút, Crossplane sẽ tự động deploy các controller của AWS vào cluster. Bạn có thể check bằng lệnh kubectl get provider -n crossplane-system thấy trạng thái Active.
Cấu hình AWS Secret cho Provider
Provider cần thông tin xác thực (Access Key/Secret Key) để kết nối với AWS. Chúng ta sẽ tạo một Secret và liên kết nó với ProviderConfig.
Tạo file /home/admin/crossplane-configs/aws-secret.yaml:
apiVersion: v1
kind: Secret
metadata:
name: aws-creds
namespace: crossplane-system
type: Opaque
stringData:
region: us-east-1
access_key_id: "YOUR_AWS_ACCESS_KEY_ID"
secret_access_key: "YOUR_AWS_SECRET_ACCESS_KEY"
Tiếp theo, tạo file /home/admin/crossplane-configs/aws-providerconfig.yaml để ánh xạ Secret:
apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: aws-creds
key: access_key_id
Áp dụng cả hai file:
kubectl apply -f /home/admin/crossplane-configs/aws-secret.yaml
kubectl apply -f /home/admin/crossplane-configs/aws-providerconfig.yaml
Kết quả mong đợi: Resource ProviderConfig được tạo. Crossplane sẽ tự động sử dụng config này cho mọi tài nguyên AWS nếu không chỉ định khác.
Verify kết nối Provider
Kiểm tra xem Provider có thể đọc được Secret và kết nối với AWS không.
kubectl describe providerconfig default -n crossplane-system
Kết quả mong đợi: Trong phần Events hoặc Conditions không có lỗi Failed hay InvalidCredentials. Trạng thái Ready là True.
Tạo Composite Resource Definition (XRD)
Thiết kế XRD cho môi trường Dev
Chúng ta cần định nghĩa một tài nguyên trừu tượng (Composite Resource) mà Developer sẽ sử dụng, ví dụ: DevEnvironment. Tài nguyên này sẽ bao gồm các thông số như tên, kích thước instance, và số lượng replica.
Tạo file /home/admin/crossplane-configs/xrd-dev-environment.yaml:
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
name: devenvironments.platform.example.com
spec:
claimNames:
kind: DevEnvironmentClaim
singular: devenvironmentclaim
plural: devenvironmentclaims
group: platform.example.com
names:
kind: DevEnvironment
singular: devenvironment
plural: devenvironments
versions:
- name: v1alpha1
served: true
stored: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
region:
type: string
description: "AWS Region to deploy"
instanceType:
type: string
default: "t3.micro"
description: "EC2 Instance type"
replicas:
type: integer
default: 1
description: "Number of instances in ASG"
vpcId:
type: string
description: "Existing VPC ID"
environmentName:
type: string
description: "Logical name of the environment"
Áp dụng XRD vào cluster:
kubectl apply -f /home/admin/crossplane-configs/xrd-dev-environment.yaml
Kết quả mong đợi: CRD mới được tạo. Bạn có thể liệt kê bằng kubectl get xrd thấy devenvironments.platform.example.com ở trạng thái Established.
Viết Composition để ánh xạ tài nguyên
Xây dựng Composition Logic
Composition đóng vai trò "bộ não", chuyển đổi từ XRD (DevEnvironment) xuống các tài nguyên thực tế của AWS (EC2, VPC, SecurityGroup, ASG). Chúng ta sử dụng Patch and Transform để ánh xạ trường.
Tạo file /home/admin/crossplane-configs/composition-dev-env.yaml:
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: dev-environments.aws.platform.example.com
labels:
environment: dev
spec:
writeConnectionSecretsToNamespace: crossplane-system
compositeTypeRef:
apiVersion: platform.example.com/v1alpha1
kind: DevEnvironment
mode: Pipeline
pipeline:
- step: patch-and-transform
patchAndTransform:
- patches:
- fromFieldPath: spec.region
toFieldPath: spec.forProvider.region
- fromFieldPath: spec.instanceType
toFieldPath: spec.forProvider.instanceType
- fromFieldPath: spec.replicas
toFieldPath: spec.forProvider.desiredCapacity
- fromFieldPath: spec.vpcId
toFieldPath: spec.forProvider.vpcId
- fromFieldPath: spec.environmentName
toFieldPath: metadata.name
resources:
- name: ec2-instance
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: Instance
spec:
forProvider:
ami: "ami-0c55b159cbfafe1f0" # Amazon Linux 2
instanceType: "t3.micro"
tags:
Name: "dev-env-instance"
patches:
- fromFieldPath: spec.instanceType
toFieldPath: spec.forProvider.instanceType
- fromFieldPath: spec.region
toFieldPath: spec.forProvider.region
- fromFieldPath: spec.vpcId
toFieldPath: spec.forProvider.subnetId
transforms:
- type: parameter
string:
pattern: "subnet-.*"
input: "subnet-12345678" # Placeholder
- name: s3-bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
tags:
Environment: "dev"
patches:
- fromFieldPath: spec.environmentName
toFieldPath: metadata.name
- fromFieldPath: spec.region
toFieldPath: spec.forProvider.region
Áp dụng Composition:
kubectl apply -f /home/admin/crossplane-configs/composition-dev-env.yaml
Kết quả mong đợi: Resource Composition được tạo. Crossplane sẽ sử dụng logic này khi nhận được một DevEnvironmentClaim mới.
Test Composition bằng DevEnvironmentClaim
Tạo một Claim để kích hoạt quy trình Provisioning tự động.
Tạo file /home/admin/crossplane-configs/test-claim.yaml:
apiVersion: platform.example.com/v1alpha1
kind: DevEnvironmentClaim
metadata:
name: my-test-dev-env
namespace: default
spec:
compositionRef:
name: dev-environments.aws.platform.example.com
region: us-east-1
instanceType: t3.micro
replicas: 2
vpcId: vpc-123456789
environmentName: my-test-dev-env
Áp dụng Claim:
kubectl apply -f /home/admin/crossplane-configs/test-claim.yaml
Kết quả mong đợi: Crossplane tự động tạo ra DevEnvironment (Composite Resource) và các tài nguyên thực tế (EC2, S3) bên dưới. Trạng thái Ready của Claim sẽ chuyển thành True sau khi tài nguyên được tạo xong.
Kiểm tra trạng thái Sync và Debug
Giám sát quá trình Sync
Để theo dõi quá trình Crossplane đồng bộ Claim xuống tài nguyên Cloud, sử dụng lệnh describe trên Claim và Composite Resource.
kubectl get claim my-test-dev-env -n default
kubectl describe claim my-test-dev-env -n default
kubectl get devenvironment my-test-dev-env -n default
kubectl describe devenvironment my-test-dev-env -n default
Kết quả mong đợi: Trong phần Events của DevEnvironment, bạn thấy các dòng Reconcile, Connecting to AWS, Creating resources. Trạng thái cuối cùng là Ready = True.
Debug lỗi kết nối Provider
Nếu tài nguyên không được tạo, lỗi thường nằm ở việc Provider không thể kết nối với Cloud hoặc thiếu quyền IAM.
Kiểm tra logs của Pod Controller của Provider AWS:
kubectl logs -n crossplane-system -l control-plane=provider-aws --tail=50
Kiểm tra trạng thái của Resource bị lỗi:
kubectl get managed ec2instance -o wide
kubectl describe managed ec2instance -n crossplane-system
Kết quả mong đợi: Nếu có lỗi, phần Conditions sẽ hiển thị Synced = False và Reason chi tiết (ví dụ: AccessDenied, InvalidRegion). Hãy kiểm tra lại ProviderConfig và IAM Policy của Role/Key được sử dụng.
Verify tài nguyên thực tế trên Cloud
Xác nhận tài nguyên đã được tạo trên AWS Console hoặc CLI.
aws ec2 describe-instances --filters "Name=tag:Name,Values=dev-env-instance" --region us-east-1
aws s3 ls --region us-east-1
Kết quả mong đợi: Xuất hiện các Instance EC2 và Bucket S3 tương ứng với thông tin trong Claim đã tạo.
Đ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 1: Chuẩn bị môi trường và kiến trúc tổng quan
Phần 3: Xây dựng quy trình GitOps với ArgoCD và Crossplane »