Crossplane

Plano de control de infraestructura como código nativo de Kubernetes para componer recursos en la nube.

Instalación

Crossplane Core

Comando	Descripción
helm repo add crossplane-stable https://charts.crossplane.io/stable	Agregar repositorio Helm de Crossplane
helm repo update	Actualizar repositorios Helm
helm install crossplane crossplane-stable/crossplane -n crossplane-system --create-namespace	Instalar Crossplane en Kubernetes
helm install crossplane crossplane-stable/crossplane -n crossplane-system --set args='{"--debug"}'	Instalar con registro de depuración
helm upgrade crossplane crossplane-stable/crossplane -n crossplane-system	Actualizar Crossplane
helm uninstall crossplane -n crossplane-system	Desinstalar Crossplane
kubectl get pods -n crossplane-system	Verificar que Crossplane está ejecutándose
kubectl get deployments -n crossplane-system	Comprobar estado del despliegue

Instalación del CLI

Comando	Descripción
curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh	Instalar CLI de Crossplane
brew install crossplane/tap/crossplane	Instalar CLI vía Homebrew
crossplane --version	Mostrar versión del CLI

Comandos del CLI

Gestión de Paquetes

Comando	Descripción
crossplane xpkg init my-config configuration	Inicializar nuevo paquete de configuración
crossplane xpkg init my-provider provider	Inicializar nuevo paquete de proveedor
crossplane xpkg build	Compilar un paquete de Crossplane
crossplane xpkg build --package-root=./package --examples-root=./examples	Compilar con directorios específicos
crossplane xpkg push index.docker.io/org/config:v1	Publicar paquete en registro
crossplane xpkg install provider index.docker.io/org/provider:v1	Instalar un paquete de proveedor
crossplane xpkg install configuration index.docker.io/org/config:v1	Instalar un paquete de configuración

Depuración y Validación

Comando	Descripción
crossplane beta validate schema.yaml resources/	Validar recursos contra esquema
crossplane beta trace kind/name	Trazar dependencias de recursos
crossplane beta trace kind/name -o wide	Trazar con salida extendida
crossplane beta convert composition comp.yaml	Convertir Composition a modo pipeline
crossplane beta render xr.yaml composition.yaml functions.yaml	Renderizar localmente recursos compuestos

Proveedores

Configuración de Proveedores

Comando	Descripción
kubectl apply -f provider-aws.yaml	Instalar proveedor de AWS
kubectl apply -f provider-gcp.yaml	Instalar proveedor de GCP
kubectl apply -f provider-azure.yaml	Instalar proveedor de Azure
kubectl apply -f provider-kubernetes.yaml	Instalar proveedor de Kubernetes
kubectl apply -f provider-helm.yaml	Instalar proveedor de Helm
kubectl get providers	Listar proveedores instalados
kubectl get provider.pkg provider-aws -o yaml	Mostrar detalles del proveedor
kubectl describe providerrevision	Mostrar estado de revisión del proveedor
kubectl get managed	Listar todos los recursos gestionados en la nube
kubectl get managed -o wide	Listar recursos gestionados con estado

ProviderConfig de AWS

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

Crear el secreto de credenciales:

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

ProviderConfig de 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 de Azure

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

Recursos Compuestos (XRDs)

Operaciones de XRD

Comando	Descripción
kubectl apply -f xrd.yaml	Crear CompositeResourceDefinition
kubectl get xrd	Listar todos los XRDs
kubectl describe xrd xdatabases.custom.example.com	Mostrar detalles del XRD
kubectl get composite	Listar todos los recursos compuestos
kubectl describe composite	Mostrar estado del recurso compuesto
kubectl delete xrd xdatabases.custom.example.com	Eliminar XRD
Establecer spec.claimNames en XRD	Habilitar claims con ámbito de namespace
Establecer spec.versions[].schema	Definir esquema OpenAPI para XRD
Establecer spec.connectionSecretKeys	Definir qué claves de conexión exponer

Ejemplo de Definición 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

Operaciones de Composition

Comando	Descripción
kubectl apply -f composition.yaml	Crear una Composition
kubectl get compositions	Listar todas las Compositions
kubectl describe composition	Mostrar detalles de la Composition
Establecer spec.compositeTypeRef en Composition	Vincular al XRD
Establecer spec.resources[] en Composition	Definir recursos compuestos
Usar patches en Composition	Mapear campos entre compuesto y recursos
patch: { type: FromCompositeFieldPath }	Parche desde compuesto hacia recurso
patch: { type: ToCompositeFieldPath }	Parche desde recurso hacia compuesto
patch: { type: CombineFromComposite }	Combinar múltiples campos en uno
Establecer spec.mode: Pipeline en Composition	Usar modo pipeline con funciones

Ejemplo de Composition (Modo 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

Ejemplo de Composition (Modo 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

Operaciones de Claims

Comando	Descripción
kubectl apply -f claim.yaml	Crear un claim de recurso
kubectl get claim	Listar todos los claims en el namespace
kubectl get database	Listar claims de tipo Database
kubectl describe claim my-database	Mostrar estado y eventos del claim
kubectl delete claim my-database	Eliminar claim y recursos gestionados
Establecer spec.compositionRef.name en claim	Seleccionar Composition específica
Establecer spec.compositionSelector.matchLabels en claim	Seleccionar Composition por etiquetas
kubectl get events --field-selector involvedObject.name=my-db	Ver eventos del claim
kubectl get secret my-db-conn -o jsonpath='{.data.endpoint}'	Leer detalles de conexión

Ejemplo 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

Funciones

Pipeline de Funciones

Comando	Descripción
kubectl apply -f function.yaml	Instalar una función de Composition
kubectl get functions	Listar funciones instaladas
kubectl describe function function-patch-and-transform	Mostrar detalles de la función
crossplane beta render xr.yaml composition.yaml functions.yaml	Probar pipeline localmente

Funciones Comunes

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

Configuración

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

Publicación de Secretos de Conexión

Comando	Descripción
kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./aws-creds.txt	Crear secreto de credenciales del proveedor
Establecer spec.credentials.source: Secret en ProviderConfig	Referenciar secreto de credenciales
kubectl apply -f environmentconfig.yaml	Crear EnvironmentConfig
kubectl get storeconfig	Listar configuraciones de almacenamiento
Establecer spec.publishConnectionDetailsTo en Composition	Configurar publicación de secretos de conexión
Establecer spec.writeConnectionSecretToRef en claim	Escribir detalles de conexión en secreto
kubectl get secrets -l crossplane.io/claim-name=my-db	Listar secretos de un claim

StoreConfig para Almacén de Secretos Externo

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

Solución de Problemas

Diagnósticos

Comando	Descripción
kubectl get managed -o wide	Mostrar recursos gestionados con estado
kubectl describe managed	Mostrar información detallada de recursos gestionados
kubectl logs -n crossplane-system deploy/crossplane	Ver registros del controlador de Crossplane
kubectl logs -n crossplane-system deploy/crossplane -f	Seguir registros del controlador
kubectl get events --sort-by='.lastTimestamp'	Ver eventos recientes del clúster
crossplane beta trace xdatabase my-db	Trazar árbol completo de recursos
crossplane beta trace xdatabase my-db -o wide	Trazar con estado detallado
kubectl get managed -l crossplane.io/composite=my-db	Encontrar recursos de un compuesto
kubectl annotate managed resource.api.example.com/name crossplane.io/paused=true	Pausar reconciliación de recursos
kubectl annotate managed resource.api.example.com/name crossplane.io/paused-	Reanudar reconciliación de recursos

Problemas Comunes

Comando	Descripción
kubectl get providerrevision	Verificar si el proveedor está saludable
kubectl describe providerrevision	Ver errores de instalación del proveedor
kubectl get managed -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[*].reason}{"\n"}{end}'	Estado rápido de todos los recursos gestionados
kubectl patch managed resource.api.example.com/name --type merge -p '{"metadata":{"annotations":{"crossplane.io/paused":"true"}}}'	Pausar vía patch
kubectl delete managed --all	Eliminar todos los recursos gestionados (usar con precaución)

Mejores Prácticas

1. Usa Claims en lugar de Composites directos — los claims tienen ámbito de namespace y proporcionan límites RBAC adecuados entre equipos.

2. Fija versiones de proveedores — siempre especifica versiones exactas de proveedores para prevenir cambios inesperados durante actualizaciones.

3. Usa modo Pipeline para nuevas Compositions — el modo Pipeline con funciones es más flexible y testeable que el modo Resources.

4. Implementa EnvironmentConfigs — almacena datos de entorno compartidos como IDs de VPC y listas de subredes para evitar duplicación entre Compositions.

5. Configura la publicación de secretos de conexión — siempre define writeConnectionSecretToRef en claims para que las aplicaciones puedan consumir los detalles de conexión.

6. Usa crossplane beta trace — esta es la forma más rápida de depurar problemas visualizando todo el árbol de recursos desde el claim hasta el recurso gestionado.

7. Etiqueta las Compositions para selección — usa etiquetas como provider: aws y engine: postgres para que los claims seleccionen Compositions por etiqueta en lugar de por nombre.

8. Prueba localmente con crossplane beta render — renderiza tus Compositions localmente antes de aplicarlas a un clúster.

9. Implementa verificaciones de disponibilidad — usa function-auto-detect-ready o verificaciones personalizadas para asegurar que los recursos compuestos reporten un estado preciso.

10. Versiona tus XRDs — comienza con v1alpha1 y promueve a través de v1beta1 hasta v1 a medida que tu API se estabiliza.