crossplane

Crossplane 기본 — 설치, Provider, Managed Resources, Compositions, Terraform 과 비교. Use when Kubernetes 로 클라우드 인프라를 선언적으로 관리하려고 Crossplane 을 도입할 때.

SKILL.md

GitHub

Crossplane 멀티클라우드 가이드

Kubernetes-native 인프라 관리: Provider 설정, Compositions, 멀티클라우드 패턴

Quick Reference (결정 트리)

IaC 도구 선택?
    |
    +-- Kubernetes 네이티브 우선 ----> Crossplane
    |       |
    |       +-- 자동 Drift 수정 -----> Crossplane (권장)
    |       +-- GitOps 통합 ---------> Crossplane + ArgoCD
    |
    +-- 기존 Terraform 자산 ---------> Terraform
    |       |
    |       +-- 점진적 전환 ---------> Crossplane + Terraform Provider
    |
    +-- 멀티클라우드 복잡 ------------> Crossplane Compositions
            |
            +-- 표준화된 추상화 -----> XRDs + Compositions

Crossplane vs Terraform?
    |
    +-- Drift 자동 복구 필요 --------> Crossplane
    +-- K8s 리소스와 동일 관리 ------> Crossplane
    +-- 기존 .tf 파일 재사용 --------> Terraform
    +-- 상태 파일 중앙화 ------------> Terraform Cloud

CRITICAL: Crossplane vs Terraform 비교

항목 Crossplane Terraform
패러다임 Kubernetes-native 독립 CLI/상태 파일
Drift 감지 자동 (Reconciliation) 수동 (terraform plan)
Drift 수정 자동 수동 (terraform apply)
상태 관리 etcd (K8s) .tfstate (S3, etc.)
GitOps 네이티브 추가 도구 필요
학습 곡선 K8s 경험 필요 HCL 학습
성숙도 발전 중 (CNCF) 검증됨 (10년+)
모듈 생태계 Compositions 풍부한 모듈

Crossplane 장점

Kubernetes Control Plane 활용
    |
    +-- 자동 Reconciliation (Drift 자동 수정)
    +-- RBAC 통합 (K8s 권한 모델)
    +-- GitOps 네이티브 (ArgoCD/Flux)
    +-- 단일 API 서버 (kubectl로 모든 관리)
    +-- 시크릿 관리 통합 (K8s Secrets)

Crossplane 설치

Helm 설치

# Crossplane 설치
helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update

helm install crossplane crossplane-stable/crossplane \
  --namespace crossplane-system \
  --create-namespace \
  --set args='{"--enable-usages"}'

# 설치 확인
kubectl get pods -n crossplane-system
kubectl get providers

Provider 설치

# AWS Provider
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws
spec:
  package: xpkg.upbound.io/upbound/provider-family-aws:v1.14.0
  controllerConfigRef:
    name: aws-config
---
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
metadata:
  name: aws-config
spec:
  args:
    - --debug
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 256Mi
---
# GCP Provider
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-gcp
spec:
  package: xpkg.upbound.io/upbound/provider-family-gcp:v1.8.0
---
# Azure Provider
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-azure
spec:
  package: xpkg.upbound.io/upbound/provider-family-azure:v1.3.0

Provider 설정

AWS ProviderConfig

# Secret for AWS credentials
apiVersion: v1
kind: Secret
metadata:
  name: aws-creds
  namespace: crossplane-system
type: Opaque
stringData:
  credentials: |
    [default]
    aws_access_key_id = AKIA...
    aws_secret_access_key = ...
---
# ProviderConfig
apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: aws-creds
      key: credentials
---
# IRSA (권장 - EKS 환경)
apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: irsa
spec:
  credentials:
    source: IRSA

Managed Resources

AWS S3 Bucket

apiVersion: s3.aws.upbound.io/v1beta2
kind: Bucket
metadata:
  name: my-bucket
  labels:
    environment: production
spec:
  forProvider:
    region: ap-northeast-2
    tags:
      Environment: production
      ManagedBy: crossplane
  providerConfigRef:
    name: default

AWS RDS Instance

apiVersion: rds.aws.upbound.io/v1beta2
kind: Instance
metadata:
  name: my-postgres
spec:
  forProvider:
    region: ap-northeast-2
    allocatedStorage: 20
    engine: postgres
    engineVersion: "15.4"
    instanceClass: db.t3.micro
    dbName: mydb
    username: admin
    passwordSecretRef:
      name: db-password
      namespace: crossplane-system
      key: password
    skipFinalSnapshot: true
    publiclyAccessible: false
    vpcSecurityGroupIdSelector:
      matchLabels:
        app: my-app
  providerConfigRef:
    name: default
  writeConnectionSecretToRef:
    name: db-connection
    namespace: default

GCP CloudSQL

apiVersion: sql.gcp.upbound.io/v1beta2
kind: DatabaseInstance
metadata:
  name: my-cloudsql
spec:
  forProvider:
    region: asia-northeast3
    databaseVersion: POSTGRES_15
    settings:
      - tier: db-f1-micro
        ipConfiguration:
          - ipv4Enabled: false
            privateNetworkRef:
              name: my-vpc
    deletionProtection: false
  providerConfigRef:
    name: default

Compositions (추상화)

아키텍처

+------------------------------------------------------------------+
|                     Application Developer                          |
|                     (Claim: DatabaseClaim)                         |
+------------------------------------------------------------------+
                               |
                               v
+------------------------------------------------------------------+
|                     Platform Team                                  |
|                     (XRD: XDatabase)                               |
+------------------------------------------------------------------+
                               |
          +--------------------+--------------------+
          |                    |                    |
          v                    v                    v
+------------------+  +------------------+  +------------------+
| Composition      |  | Composition      |  | Composition      |
| (AWS RDS)        |  | (GCP CloudSQL)   |  | (Azure SQL)      |
+------------------+  +------------------+  +------------------+
          |                    |                    |
          v                    v                    v
+------------------+  +------------------+  +------------------+
| Managed Resource |  | Managed Resource |  | Managed Resource |
| (RDS Instance)   |  | (CloudSQL)       |  | (Azure SQL DB)   |
+------------------+  +------------------+  +------------------+

CompositeResourceDefinition (XRD)

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.platform.example.com
spec:
  group: platform.example.com
  names:
    kind: XDatabase
    plural: xdatabases

  claimNames:
    kind: DatabaseClaim
    plural: databaseclaims

  versions:
    - name: v1alpha1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required:
                - parameters
              properties:
                parameters:
                  type: object
                  required:
                    - size
                    - engine
                  properties:
                    size:
                      type: string
                      enum: ["small", "medium", "large"]
                      description: "Database size"
                    engine:
                      type: string
                      enum: ["postgres", "mysql"]
                      description: "Database engine"
                    version:
                      type: string
                      default: "15"
                    highAvailability:
                      type: boolean
                      default: false
            status:
              type: object
              properties:
                connectionSecret:
                  type: string
                endpoint:
                  type: string

Composition (AWS)

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: xdatabase-aws
  labels:
    provider: aws
    engine: postgres
spec:
  compositeTypeRef:
    apiVersion: platform.example.com/v1alpha1
    kind: XDatabase

  mode: Pipeline
  pipeline:
    - step: patch-and-transform
      functionRef:
        name: function-patch-and-transform
      input:
        apiVersion: pt.fn.crossplane.io/v1beta1
        kind: Resources
        resources:
          # RDS Instance
          - name: rds-instance
            base:
              apiVersion: rds.aws.upbound.io/v1beta2
              kind: Instance
              spec:
                forProvider:
                  region: ap-northeast-2
                  engine: postgres
                  skipFinalSnapshot: true
                  publiclyAccessible: false
                providerConfigRef:
                  name: default
            patches:
              # Size 매핑
              - type: FromCompositeFieldPath
                fromFieldPath: spec.parameters.size
                toFieldPath: spec.forProvider.instanceClass
                transforms:
                  - type: map
                    map:
                      small: db.t3.micro
                      medium: db.t3.small
                      large: db.t3.medium

              # Storage 매핑
              - type: FromCompositeFieldPath
                fromFieldPath: spec.parameters.size
                toFieldPath: spec.forProvider.allocatedStorage
                transforms:
                  - type: map
                    map:
                      small: 20
                      medium: 50
                      large: 100

              # Engine Version
              - type: FromCompositeFieldPath
                fromFieldPath: spec.parameters.version
                toFieldPath: spec.forProvider.engineVersion

              # HA 설정
              - type: FromCompositeFieldPath
                fromFieldPath: spec.parameters.highAvailability
                toFieldPath: spec.forProvider.multiAz

              # Connection Secret
              - type: ToCompositeFieldPath
                fromFieldPath: status.atProvider.endpoint
                toFieldPath: status.endpoint

            connectionDetails:
              - type: FromFieldPath
                fromFieldPath: status.atProvider.endpoint
                name: endpoint
              - type: FromFieldPath
                fromFieldPath: status.atProvider.username
                name: username
              - type: FromConnectionSecretKey
                fromConnectionSecretKey: password
                name: password

Claim 사용

# 개발자가 요청하는 간단한 인터페이스
apiVersion: platform.example.com/v1alpha1
kind: DatabaseClaim
metadata:
  name: my-app-db
  namespace: production
spec:
  parameters:
    size: medium
    engine: postgres
    version: "15"
    highAvailability: true

  compositionSelector:
    matchLabels:
      provider: aws

  writeConnectionSecretToRef:
    name: my-app-db-connection

Anti-Patterns

실수 문제 해결
Provider 버전 미고정 예기치 않은 변경 버전 명시
모든 리소스 직접 정의 유지보수 어려움 Compositions 활용
Drift 수정 비활성화 구성 불일치 기본값 유지
Connection Secret 미사용 시크릿 하드코딩 writeConnectionSecretToRef
XRD 과도한 복잡성 사용성 저하 간단한 인터페이스

체크리스트

설치

  • Crossplane Helm 설치
  • Provider 설치 (AWS/GCP/Azure)
  • ProviderConfig 설정
  • IRSA/Workload Identity 설정

XRD/Compositions

  • XRD 정의 (간단한 인터페이스)
  • Composition 작성 (Provider별)
  • Function 설치

참조 스킬

  • /infra:crossplane-advanced - 멀티클라우드 패턴, GitOps 통합, Drift Detection
  • /infra:terraform-modules - Terraform 모듈
  • /cicd:gitops-argocd - ArgoCD GitOps