Crossplane

Plan de contrôle Kubernetes-natif d’infrastructure as code pour composer des ressources cloud.

Installation

Crossplane Core

Commande	Description
helm repo add crossplane-stable https://charts.crossplane.io/stable	Ajouter le dépôt Helm Crossplane
helm repo update	Mettre à jour les dépôts Helm
helm install crossplane crossplane-stable/crossplane -n crossplane-system --create-namespace	Installer Crossplane sur Kubernetes
helm install crossplane crossplane-stable/crossplane -n crossplane-system --set args='{"--debug"}'	Installer avec la journalisation de débogage
helm upgrade crossplane crossplane-stable/crossplane -n crossplane-system	Mettre à jour Crossplane
helm uninstall crossplane -n crossplane-system	Désinstaller Crossplane
kubectl get pods -n crossplane-system	Vérifier que Crossplane fonctionne
kubectl get deployments -n crossplane-system	Vérifier le statut du déploiement

Installation du CLI

Commande	Description
curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh	Installer le CLI Crossplane
brew install crossplane/tap/crossplane	Installer le CLI via Homebrew
crossplane --version	Afficher la version du CLI

Commandes CLI

Gestion des paquets

Commande	Description
crossplane xpkg init my-config configuration	Initialiser un nouveau paquet de configuration
crossplane xpkg init my-provider provider	Initialiser un nouveau paquet de provider
crossplane xpkg build	Compiler un paquet Crossplane
crossplane xpkg build --package-root=./package --examples-root=./examples	Compiler avec des répertoires spécifiques
crossplane xpkg push index.docker.io/org/config:v1	Pousser un paquet vers un registre
crossplane xpkg install provider index.docker.io/org/provider:v1	Installer un paquet de provider
crossplane xpkg install configuration index.docker.io/org/config:v1	Installer un paquet de configuration

Débogage et validation

Commande	Description
crossplane beta validate schema.yaml resources/	Valider les ressources contre un schéma
crossplane beta trace kind/name	Tracer les dépendances des ressources
crossplane beta trace kind/name -o wide	Tracer avec une sortie étendue
crossplane beta convert composition comp.yaml	Convertir une Composition en mode pipeline
crossplane beta render xr.yaml composition.yaml functions.yaml	Rendre localement les ressources composées

Providers

Configuration des providers

Commande	Description
kubectl apply -f provider-aws.yaml	Installer le provider AWS
kubectl apply -f provider-gcp.yaml	Installer le provider GCP
kubectl apply -f provider-azure.yaml	Installer le provider Azure
kubectl apply -f provider-kubernetes.yaml	Installer le provider Kubernetes
kubectl apply -f provider-helm.yaml	Installer le provider Helm
kubectl get providers	Lister les providers installés
kubectl get provider.pkg provider-aws -o yaml	Afficher les détails du provider
kubectl describe providerrevision	Afficher le statut de révision du provider
kubectl get managed	Lister toutes les ressources cloud gérées
kubectl get managed -o wide	Lister les ressources gérées avec le statut

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

Créer le secret d’identifiants :

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

Ressources composites (XRDs)

Opérations XRD

Commande	Description
kubectl apply -f xrd.yaml	Créer une CompositeResourceDefinition
kubectl get xrd	Lister toutes les XRDs
kubectl describe xrd xdatabases.custom.example.com	Afficher les détails d’une XRD
kubectl get composite	Lister toutes les ressources composites
kubectl describe composite	Afficher le statut des ressources composites
kubectl delete xrd xdatabases.custom.example.com	Supprimer une XRD
Définir spec.claimNames dans la XRD	Activer les claims à portée namespace
Définir spec.versions[].schema dans la XRD	Définir le schéma OpenAPI pour la XRD
Définir spec.connectionSecretKeys dans la XRD	Définir les clés de connexion à exposer

Exemple de définition 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

Compositions

Opérations sur les Compositions

Commande	Description
kubectl apply -f composition.yaml	Créer une Composition
kubectl get compositions	Lister toutes les Compositions
kubectl describe composition	Afficher les détails d’une Composition
Définir spec.compositeTypeRef dans la Composition	Lier à une XRD
Définir spec.resources[] dans la Composition	Définir les ressources composées
Utiliser patches dans la Composition	Mapper les champs entre composite et ressources
patch: { type: FromCompositeFieldPath }	Patcher du composite vers la ressource
patch: { type: ToCompositeFieldPath }	Patcher de la ressource vers le composite
patch: { type: CombineFromComposite }	Combiner plusieurs champs en un seul
Définir spec.mode: Pipeline dans la Composition	Utiliser le mode pipeline avec des fonctions

Exemple de Composition (mode 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

Exemple de Composition (mode 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

Claims

Opérations sur les claims

Commande	Description
kubectl apply -f claim.yaml	Créer un claim de ressource
kubectl get claim	Lister tous les claims dans le namespace
kubectl get database	Lister les claims de type Database
kubectl describe claim my-database	Afficher le statut et les événements du claim
kubectl delete claim my-database	Supprimer le claim et les ressources gérées
Définir spec.compositionRef.name dans le claim	Sélectionner une Composition spécifique
Définir spec.compositionSelector.matchLabels dans le claim	Sélectionner une Composition par labels
kubectl get events --field-selector involvedObject.name=my-db	Voir les événements du claim
kubectl get secret my-db-conn -o jsonpath='{.data.endpoint}'	Lire les détails de connexion

Exemple de 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

Fonctions

Pipeline de fonctions

Commande	Description
kubectl apply -f function.yaml	Installer une fonction de Composition
kubectl get functions	Lister les fonctions installées
kubectl describe function function-patch-and-transform	Afficher les détails d’une fonction
crossplane beta render xr.yaml composition.yaml functions.yaml	Tester le pipeline localement

Fonctions courantes

# Installer 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
---
# Installer 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
---
# Installer 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

Configuration

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

Publication des secrets de connexion

Commande	Description
kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./aws-creds.txt	Créer le secret d’identifiants du provider
Définir spec.credentials.source: Secret dans le ProviderConfig	Référencer le secret d’identifiants
kubectl apply -f environmentconfig.yaml	Créer un EnvironmentConfig
kubectl get storeconfig	Lister les configurations de stockage
Définir spec.publishConnectionDetailsTo dans la Composition	Configurer la publication des secrets de connexion
Définir spec.writeConnectionSecretToRef dans le claim	Écrire les détails de connexion dans un secret
kubectl get secrets -l crossplane.io/claim-name=my-db	Lister les secrets pour un claim

StoreConfig pour un magasin de secrets externe

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

Dépannage

Diagnostics

Commande	Description
kubectl get managed -o wide	Afficher les ressources gérées avec le statut
kubectl describe managed	Afficher les informations détaillées des ressources gérées
kubectl logs -n crossplane-system deploy/crossplane	Voir les journaux du contrôleur Crossplane
kubectl logs -n crossplane-system deploy/crossplane -f	Suivre les journaux du contrôleur
kubectl get events --sort-by='.lastTimestamp'	Voir les événements récents du cluster
crossplane beta trace xdatabase my-db	Tracer l’arbre complet des ressources
crossplane beta trace xdatabase my-db -o wide	Tracer avec un statut détaillé
kubectl get managed -l crossplane.io/composite=my-db	Trouver les ressources pour un composite
kubectl annotate managed resource.api.example.com/name crossplane.io/paused=true	Mettre en pause la réconciliation d’une ressource
kubectl annotate managed resource.api.example.com/name crossplane.io/paused-	Reprendre la réconciliation d’une ressource

Problèmes courants

Commande	Description
kubectl get providerrevision	Vérifier si le provider est en bonne santé
kubectl describe providerrevision	Voir les erreurs d’installation du provider
kubectl get managed -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[*].reason}{"\n"}{end}'	Statut rapide de toutes les ressources gérées
kubectl patch managed resource.api.example.com/name --type merge -p '{"metadata":{"annotations":{"crossplane.io/paused":"true"}}}'	Mettre en pause via patch
kubectl delete managed --all	Supprimer toutes les ressources gérées (à utiliser avec précaution)

Bonnes pratiques

1. Utiliser les Claims plutôt que les Composites directs — les claims ont une portée namespace et fournissent des limites RBAC appropriées entre les équipes.

2. Fixer les versions des providers — spécifiez toujours des versions exactes de providers pour éviter des changements inattendus lors des mises à jour.

3. Utiliser le mode Pipeline pour les nouvelles Compositions — le mode Pipeline avec des fonctions est plus flexible et testable que le mode Resources.

4. Implémenter les EnvironmentConfigs — stockez les données d’environnement partagées comme les IDs de VPC et les listes de sous-réseaux pour éviter la duplication entre les Compositions.

5. Configurer la publication des secrets de connexion — définissez toujours writeConnectionSecretToRef dans les claims pour que les applications puissent consommer les détails de connexion.

6. Utiliser crossplane beta trace — c’est le moyen le plus rapide de déboguer les problèmes en visualisant l’arbre complet des ressources du claim à la ressource gérée.

7. Étiqueter les Compositions pour la sélection — utilisez des labels comme provider: aws et engine: postgres pour que les claims puissent sélectionner les Compositions par label plutôt que par nom.

8. Tester localement avec crossplane beta render — rendez vos Compositions localement avant de les appliquer sur un cluster.

9. Implémenter les vérifications de disponibilité — utilisez function-auto-detect-ready ou des vérifications personnalisées pour que les ressources composites rapportent un statut précis.

10. Versionner vos XRDs — commencez avec v1alpha1 et progressez vers v1beta1 puis v1 à mesure que votre API se stabilise.