Crossplane

Control plane per infrastructure as code nativo Kubernetes per la composizione di risorse cloud.

Installazione

Crossplane Core

Comando	Descrizione
helm repo add crossplane-stable https://charts.crossplane.io/stable	Aggiungi il repo Helm di Crossplane
helm repo update	Aggiorna i repository Helm
helm install crossplane crossplane-stable/crossplane -n crossplane-system --create-namespace	Installa Crossplane su Kubernetes
helm install crossplane crossplane-stable/crossplane -n crossplane-system --set args='{"--debug"}'	Installa con logging di debug
helm upgrade crossplane crossplane-stable/crossplane -n crossplane-system	Aggiorna Crossplane
helm uninstall crossplane -n crossplane-system	Disinstalla Crossplane
kubectl get pods -n crossplane-system	Verifica che Crossplane sia in esecuzione
kubectl get deployments -n crossplane-system	Controlla lo stato del deployment

Installazione della CLI

Comando	Descrizione
curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh	Installa la CLI di Crossplane
brew install crossplane/tap/crossplane	Installa la CLI tramite Homebrew
crossplane --version	Mostra la versione della CLI

Comandi CLI

Gestione dei Pacchetti

Comando	Descrizione
crossplane xpkg init my-config configuration	Inizializza nuovo pacchetto di configurazione
crossplane xpkg init my-provider provider	Inizializza nuovo pacchetto provider
crossplane xpkg build	Build di un pacchetto Crossplane
crossplane xpkg build --package-root=./package --examples-root=./examples	Build con directory specifiche
crossplane xpkg push index.docker.io/org/config:v1	Push del pacchetto nel registro
crossplane xpkg install provider index.docker.io/org/provider:v1	Installa un pacchetto provider
crossplane xpkg install configuration index.docker.io/org/config:v1	Installa un pacchetto di configurazione

Debug e Validazione

Comando	Descrizione
crossplane beta validate schema.yaml resources/	Valida risorse rispetto allo schema
crossplane beta trace kind/name	Traccia le dipendenze delle risorse
crossplane beta trace kind/name -o wide	Traccia con output esteso
crossplane beta convert composition comp.yaml	Converti Composition in modalita pipeline
crossplane beta render xr.yaml composition.yaml functions.yaml	Rendering locale delle risorse composte

Provider

Configurazione dei Provider

Comando	Descrizione
kubectl apply -f provider-aws.yaml	Installa il provider AWS
kubectl apply -f provider-gcp.yaml	Installa il provider GCP
kubectl apply -f provider-azure.yaml	Installa il provider Azure
kubectl apply -f provider-kubernetes.yaml	Installa il provider Kubernetes
kubectl apply -f provider-helm.yaml	Installa il provider Helm
kubectl get providers	Elenca i provider installati
kubectl get provider.pkg provider-aws -o yaml	Mostra dettagli del provider
kubectl describe providerrevision	Mostra lo stato della revisione del provider
kubectl get managed	Elenca tutte le risorse cloud gestite
kubectl get managed -o wide	Elenca risorse gestite con stato

ProviderConfig AWS

apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: aws-creds
      key: credentials

Crea il secret delle credenziali:

kubectl create secret generic aws-creds \
  -n crossplane-system \
  --from-file=credentials=./aws-credentials.txt

ProviderConfig GCP

apiVersion: gcp.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  projectID: my-gcp-project
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: gcp-creds
      key: credentials

ProviderConfig Azure

apiVersion: azure.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: azure-creds
      key: credentials

Risorse Composite (XRD)

Operazioni sulle XRD

Comando	Descrizione
kubectl apply -f xrd.yaml	Crea CompositeResourceDefinition
kubectl get xrd	Elenca tutte le XRD
kubectl describe xrd xdatabases.custom.example.com	Mostra dettagli della XRD
kubectl get composite	Elenca tutte le risorse composite
kubectl describe composite	Mostra stato della risorsa composita
kubectl delete xrd xdatabases.custom.example.com	Elimina XRD
Imposta spec.claimNames nella XRD	Abilita claim con scope namespace
Imposta spec.versions[].schema nella XRD	Definisci schema OpenAPI per la XRD
Imposta spec.connectionSecretKeys	Definisci quali chiavi di connessione esporre

Esempio di Definizione 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: Database
    plural: databases
  connectionSecretKeys:
    - endpoint
    - port
    - username
    - password
  versions:
    - name: v1alpha1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                parameters:
                  type: object
                  properties:
                    engine:
                      type: string
                      enum: ["postgres", "mysql", "mariadb"]
                      description: "Database engine type"
                    engineVersion:
                      type: string
                      description: "Engine version"
                    storageGB:
                      type: integer
                      default: 20
                      description: "Storage size in GB"
                    instanceSize:
                      type: string
                      enum: ["small", "medium", "large"]
                      default: "small"
                  required:
                    - engine
              required:
                - parameters

Composition

Operazioni sulle Composition

Comando	Descrizione
kubectl apply -f composition.yaml	Crea una Composition
kubectl get compositions	Elenca tutte le Composition
kubectl describe composition	Mostra dettagli della Composition
Imposta spec.compositeTypeRef nella Composition	Collega alla XRD
Imposta spec.resources[] nella Composition	Definisci risorse composte
Usa patches nella Composition	Mappa campi tra composita e risorse
patch: { type: FromCompositeFieldPath }	Patch dalla composita alla risorsa
patch: { type: ToCompositeFieldPath }	Patch dalla risorsa alla composita
patch: { type: CombineFromComposite }	Combina piu campi in uno
Imposta spec.mode: Pipeline nella Composition	Usa modalita pipeline con funzioni

Esempio di Composition (Modalita Resources)

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
  resources:
    - name: rds-instance
      base:
        apiVersion: rds.aws.upbound.io/v1beta1
        kind: Instance
        spec:
          forProvider:
            engine: postgres
            instanceClass: db.t3.micro
            allocatedStorage: 20
            publiclyAccessible: false
            skipFinalSnapshot: true
            region: us-east-1
      patches:
        - type: FromCompositeFieldPath
          fromFieldPath: spec.parameters.engineVersion
          toFieldPath: spec.forProvider.engineVersion
        - type: FromCompositeFieldPath
          fromFieldPath: spec.parameters.storageGB
          toFieldPath: spec.forProvider.allocatedStorage
        - type: FromCompositeFieldPath
          fromFieldPath: spec.parameters.instanceSize
          toFieldPath: spec.forProvider.instanceClass
          transforms:
            - type: map
              map:
                small: db.t3.micro
                medium: db.t3.medium
                large: db.t3.large
      connectionDetails:
        - type: FromFieldPath
          name: endpoint
          fromFieldPath: status.atProvider.endpoint
        - type: FromFieldPath
          name: port
          fromFieldPath: status.atProvider.port
    - name: subnet-group
      base:
        apiVersion: rds.aws.upbound.io/v1beta1
        kind: SubnetGroup
        spec:
          forProvider:
            region: us-east-1
            description: "Managed by Crossplane"
  writeConnectionSecretsToNamespace: crossplane-system

Esempio di Composition (Modalita Pipeline)

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: xdatabase-pipeline
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:
          - name: rds-instance
            base:
              apiVersion: rds.aws.upbound.io/v1beta1
              kind: Instance
              spec:
                forProvider:
                  engine: postgres
                  instanceClass: db.t3.micro
                  region: us-east-1
            patches:
              - type: FromCompositeFieldPath
                fromFieldPath: spec.parameters.storageGB
                toFieldPath: spec.forProvider.allocatedStorage
    - step: auto-ready
      functionRef:
        name: function-auto-detect-ready

Claim

Operazioni sui Claim

Comando	Descrizione
kubectl apply -f claim.yaml	Crea un claim per una risorsa
kubectl get claim	Elenca tutti i claim nel namespace
kubectl get database	Elenca claim di tipo Database
kubectl describe claim my-database	Mostra stato ed eventi del claim
kubectl delete claim my-database	Elimina claim e risorse gestite
Imposta spec.compositionRef.name nel claim	Seleziona Composition specifica
Imposta spec.compositionSelector.matchLabels nel claim	Seleziona Composition per label
kubectl get events --field-selector involvedObject.name=my-db	Visualizza eventi del claim
kubectl get secret my-db-conn -o jsonpath='{.data.endpoint}'	Leggi dettagli di connessione

Esempio di Claim

apiVersion: platform.example.com/v1alpha1
kind: Database
metadata:
  name: my-app-db
  namespace: default
spec:
  parameters:
    engine: postgres
    engineVersion: "15"
    storageGB: 50
    instanceSize: medium
  compositionSelector:
    matchLabels:
      provider: aws
      engine: postgres
  writeConnectionSecretToRef:
    name: my-app-db-conn

Funzioni

Pipeline di Funzioni

Comando	Descrizione
kubectl apply -f function.yaml	Installa una funzione di Composition
kubectl get functions	Elenca le funzioni installate
kubectl describe function function-patch-and-transform	Mostra dettagli della funzione
crossplane beta render xr.yaml composition.yaml functions.yaml	Testa pipeline localmente

Funzioni Comuni

# Installa function-patch-and-transform
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-patch-and-transform
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.7.0
---
# Installa function-auto-detect-ready
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-auto-detect-ready
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-auto-detect-ready:v0.2.1
---
# Installa function-go-templating
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-go-templating
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-go-templating:v0.6.0

Configurazione

EnvironmentConfig

apiVersion: apiextensions.crossplane.io/v1alpha1
kind: EnvironmentConfig
metadata:
  name: production
data:
  region: us-east-1
  environment: production
  vpcId: vpc-0abc123def456
  subnetIds:
    - subnet-0abc123
    - subnet-0def456
    - subnet-0ghi789
  tags:
    team: platform
    costCenter: engineering

Pubblicazione dei Secret di Connessione

Comando	Descrizione
kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./aws-creds.txt	Crea secret delle credenziali del provider
Imposta spec.credentials.source: Secret nel ProviderConfig	Referenzia secret delle credenziali
kubectl apply -f environmentconfig.yaml	Crea EnvironmentConfig
kubectl get storeconfig	Elenca configurazioni dello store
Imposta spec.publishConnectionDetailsTo nella Composition	Configura pubblicazione dei secret di connessione
Imposta spec.writeConnectionSecretToRef nel claim	Scrivi dettagli di connessione nel secret
kubectl get secrets -l crossplane.io/claim-name=my-db	Elenca secret per un claim

StoreConfig per Secret Store Esterno

apiVersion: secrets.crossplane.io/v1alpha1
kind: StoreConfig
metadata:
  name: vault
spec:
  type: Vault
  defaultScope: crossplane-system
  vault:
    mountPath: secret
    version: v2
    auth:
      method: Token
      token:
        source: Secret
        secretRef:
          namespace: crossplane-system
          name: vault-token
          key: token

Risoluzione dei Problemi

Diagnostica

Comando	Descrizione
kubectl get managed -o wide	Mostra risorse gestite con stato
kubectl describe managed	Mostra informazioni dettagliate sulle risorse gestite
kubectl logs -n crossplane-system deploy/crossplane	Visualizza log del controller Crossplane
kubectl logs -n crossplane-system deploy/crossplane -f	Segui i log del controller
kubectl get events --sort-by='.lastTimestamp'	Visualizza eventi recenti del cluster
crossplane beta trace xdatabase my-db	Traccia l’intero albero delle risorse
crossplane beta trace xdatabase my-db -o wide	Traccia con stato dettagliato
kubectl get managed -l crossplane.io/composite=my-db	Trova risorse per una composita
kubectl annotate managed resource.api.example.com/name crossplane.io/paused=true	Metti in pausa la riconciliazione della risorsa
kubectl annotate managed resource.api.example.com/name crossplane.io/paused-	Riprendi la riconciliazione della risorsa

Problemi Comuni

Comando	Descrizione
kubectl get providerrevision	Controlla se il provider e in salute
kubectl describe providerrevision	Visualizza errori di installazione del provider
kubectl get managed -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[*].reason}{"\n"}{end}'	Stato rapido di tutte le risorse gestite
kubectl patch managed resource.api.example.com/name --type merge -p '{"metadata":{"annotations":{"crossplane.io/paused":"true"}}}'	Metti in pausa tramite patch
kubectl delete managed --all	Elimina tutte le risorse gestite (usa con cautela)

Buone Pratiche

1. Usa i Claim invece dei Composite diretti — i claim hanno scope a livello di namespace e forniscono confini RBAC appropriati tra i team.

2. Fissa le versioni dei provider — specifica sempre versioni esatte dei provider per prevenire modifiche inaspettate durante gli aggiornamenti.

3. Usa la modalita Pipeline per le nuove Composition — la modalita Pipeline con funzioni e piu flessibile e testabile della modalita Resources.

4. Implementa gli EnvironmentConfig — archivia dati ambientali condivisi come ID VPC e liste di subnet per evitare duplicazioni tra le Composition.

5. Configura la pubblicazione dei secret di connessione — definisci sempre writeConnectionSecretToRef nei claim cosi le applicazioni possono consumare i dettagli di connessione.

6. Usa crossplane beta trace — e il modo piu veloce per fare debug visualizzando l’intero albero delle risorse dal claim alla risorsa gestita.

7. Etichetta le Composition per la selezione — usa label come provider: aws e engine: postgres cosi i claim possono selezionare le Composition per label invece che per nome.

8. Testa localmente con crossplane beta render — renderizza le tue Composition localmente prima di applicarle a un cluster.

9. Implementa i controlli di readiness — usa function-auto-detect-ready o controlli di readiness personalizzati per assicurarti che le risorse composite riportino uno stato accurato.

10. Versiona le tue XRD — inizia con v1alpha1 e promuovi attraverso v1beta1 fino a v1 man mano che la tua API si stabilizza.