Crossplane

Plano de controle de infraestrutura como código nativo do Kubernetes para composição de recursos em nuvem.

Instalação

Crossplane Core

Comando	Descrição
helm repo add crossplane-stable https://charts.crossplane.io/stable	Adicionar repositório Helm do Crossplane
helm repo update	Atualizar repositórios Helm
helm install crossplane crossplane-stable/crossplane -n crossplane-system --create-namespace	Instalar Crossplane no Kubernetes
helm install crossplane crossplane-stable/crossplane -n crossplane-system --set args='{"--debug"}'	Instalar com logging de depuração
helm upgrade crossplane crossplane-stable/crossplane -n crossplane-system	Atualizar Crossplane
helm uninstall crossplane -n crossplane-system	Desinstalar Crossplane
kubectl get pods -n crossplane-system	Verificar se o Crossplane está rodando
kubectl get deployments -n crossplane-system	Verificar status do deployment

Instalação da CLI

Comando	Descrição
curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh	Instalar CLI do Crossplane
brew install crossplane/tap/crossplane	Instalar CLI via Homebrew
crossplane --version	Mostrar versão da CLI

Comandos da CLI

Gerenciamento de Pacotes

Comando	Descrição
crossplane xpkg init my-config configuration	Inicializar novo pacote de configuração
crossplane xpkg init my-provider provider	Inicializar novo pacote de provider
crossplane xpkg build	Construir um pacote Crossplane
crossplane xpkg build --package-root=./package --examples-root=./examples	Construir com diretórios específicos
crossplane xpkg push index.docker.io/org/config:v1	Enviar pacote para registro
crossplane xpkg install provider index.docker.io/org/provider:v1	Instalar um pacote de provider
crossplane xpkg install configuration index.docker.io/org/config:v1	Instalar um pacote de configuração

Depuração e Validação

Comando	Descrição
crossplane beta validate schema.yaml resources/	Validar recursos contra esquema
crossplane beta trace kind/name	Rastrear dependências de recursos
crossplane beta trace kind/name -o wide	Rastrear com saída estendida
crossplane beta convert composition comp.yaml	Converter Composition para modo pipeline
crossplane beta render xr.yaml composition.yaml functions.yaml	Renderizar recursos compostos localmente

Providers

Configuração de Providers

Comando	Descrição
kubectl apply -f provider-aws.yaml	Instalar provider AWS
kubectl apply -f provider-gcp.yaml	Instalar provider GCP
kubectl apply -f provider-azure.yaml	Instalar provider Azure
kubectl apply -f provider-kubernetes.yaml	Instalar provider Kubernetes
kubectl apply -f provider-helm.yaml	Instalar provider Helm
kubectl get providers	Listar providers instalados
kubectl get provider.pkg provider-aws -o yaml	Mostrar detalhes do provider
kubectl describe providerrevision	Mostrar status da revisão do provider
kubectl get managed	Listar todos os recursos gerenciados na nuvem
kubectl get managed -o wide	Listar recursos gerenciados com status

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

Criar o secret de credenciais:

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

Recursos Compostos (XRDs)

Operações de XRD

Comando	Descrição
kubectl apply -f xrd.yaml	Criar CompositeResourceDefinition
kubectl get xrd	Listar todos os XRDs
kubectl describe xrd xdatabases.custom.example.com	Mostrar detalhes do XRD
kubectl get composite	Listar todos os recursos compostos
kubectl describe composite	Mostrar status do recurso composto
kubectl delete xrd xdatabases.custom.example.com	Deletar XRD
Definir spec.claimNames no XRD	Habilitar claims com escopo de namespace
Definir spec.versions[].schema no XRD	Definir esquema OpenAPI para XRD
Definir spec.connectionSecretKeys no XRD	Definir quais chaves de conexão expor

Exemplo de Definição 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: "Tipo do motor de banco de dados"
                    engineVersion:
                      type: string
                      description: "Versão do motor"
                    storageGB:
                      type: integer
                      default: 20
                      description: "Tamanho do armazenamento em GB"
                    instanceSize:
                      type: string
                      enum: ["small", "medium", "large"]
                      default: "small"
                  required:
                    - engine
              required:
                - parameters

Compositions

Operações de Composition

Comando	Descrição
kubectl apply -f composition.yaml	Criar uma Composition
kubectl get compositions	Listar todas as Compositions
kubectl describe composition	Mostrar detalhes da Composition
Definir spec.compositeTypeRef na Composition	Vincular ao XRD
Definir spec.resources[] na Composition	Definir recursos compostos
Usar patches na Composition	Mapear campos entre composto e recursos
patch: { type: FromCompositeFieldPath }	Patch do composto para o recurso
patch: { type: ToCompositeFieldPath }	Patch do recurso para o composto
patch: { type: CombineFromComposite }	Combinar múltiplos campos em um
Definir spec.mode: Pipeline na Composition	Usar modo pipeline com funções

Exemplo 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: "Gerenciado pelo Crossplane"
  writeConnectionSecretsToNamespace: crossplane-system

Exemplo 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

Operações de Claims

Comando	Descrição
kubectl apply -f claim.yaml	Criar um claim de recurso
kubectl get claim	Listar todos os claims no namespace
kubectl get database	Listar claims do tipo Database
kubectl describe claim my-database	Mostrar status e eventos do claim
kubectl delete claim my-database	Deletar claim e recursos gerenciados
Definir spec.compositionRef.name no claim	Selecionar Composition específica
Definir spec.compositionSelector.matchLabels no claim	Selecionar Composition por labels
kubectl get events --field-selector involvedObject.name=my-db	Ver eventos do claim
kubectl get secret my-db-conn -o jsonpath='{.data.endpoint}'	Ler detalhes de conexão

Exemplo 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

Functions

Pipeline de Funções

Comando	Descrição
kubectl apply -f function.yaml	Instalar uma função de Composition
kubectl get functions	Listar funções instaladas
kubectl describe function function-patch-and-transform	Mostrar detalhes da função
crossplane beta render xr.yaml composition.yaml functions.yaml	Testar pipeline localmente

Funções Comuns

# 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

Configuração

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

Publicação de Secrets de Conexão

Comando	Descrição
kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./aws-creds.txt	Criar secret de credenciais do provider
Definir spec.credentials.source: Secret no ProviderConfig	Referenciar secret de credenciais
kubectl apply -f environmentconfig.yaml	Criar EnvironmentConfig
kubectl get storeconfig	Listar configurações de store
Definir spec.publishConnectionDetailsTo na Composition	Configurar publicação de secrets de conexão
Definir spec.writeConnectionSecretToRef no claim	Escrever detalhes de conexão em secret
kubectl get secrets -l crossplane.io/claim-name=my-db	Listar secrets de um claim

StoreConfig para Armazenamento Externo de Secrets

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

Resolução de Problemas

Diagnósticos

Comando	Descrição
kubectl get managed -o wide	Mostrar recursos gerenciados com status
kubectl describe managed	Mostrar informações detalhadas de recursos gerenciados
kubectl logs -n crossplane-system deploy/crossplane	Ver logs do controlador Crossplane
kubectl logs -n crossplane-system deploy/crossplane -f	Seguir logs do controlador
kubectl get events --sort-by='.lastTimestamp'	Ver eventos recentes do cluster
crossplane beta trace xdatabase my-db	Rastrear árvore completa de recursos
crossplane beta trace xdatabase my-db -o wide	Rastrear com status detalhado
kubectl get managed -l crossplane.io/composite=my-db	Encontrar recursos de um composto
kubectl annotate managed resource.api.example.com/name crossplane.io/paused=true	Pausar reconciliação do recurso
kubectl annotate managed resource.api.example.com/name crossplane.io/paused-	Retomar reconciliação do recurso

Problemas Comuns

Comando	Descrição
kubectl get providerrevision	Verificar se o provider está saudável
kubectl describe providerrevision	Ver erros de instalação do provider
kubectl get managed -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[*].reason}{"\n"}{end}'	Status rápido de todos os recursos gerenciados
kubectl patch managed resource.api.example.com/name --type merge -p '{"metadata":{"annotations":{"crossplane.io/paused":"true"}}}'	Pausar via patch
kubectl delete managed --all	Deletar todos os recursos gerenciados (use com cautela)

Melhores Práticas

1. Usar Claims em vez de Composites diretos — claims têm escopo de namespace e fornecem limites adequados de RBAC entre equipes.

2. Fixar versões de providers — sempre especifique versões exatas de providers para evitar mudanças inesperadas durante atualizações.

3. Usar modo Pipeline para novas Compositions — o modo Pipeline com funções é mais flexível e testável que o modo Resources.

4. Implementar EnvironmentConfigs — armazene dados compartilhados do ambiente como IDs de VPC e listas de subnets para evitar duplicação entre Compositions.

5. Configurar publicação de secrets de conexão — sempre defina writeConnectionSecretToRef nos claims para que as aplicações possam consumir detalhes de conexão.

6. Usar crossplane beta trace — esta é a forma mais rápida de depurar problemas visualizando a árvore completa de recursos do claim ao recurso gerenciado.

7. Rotular Compositions para seleção — use labels como provider: aws e engine: postgres para que claims possam selecionar Compositions por label em vez de por nome.

8. Testar localmente com crossplane beta render — renderize suas Compositions localmente antes de aplicá-las a um cluster.

9. Implementar verificações de prontidão — use function-auto-detect-ready ou verificações personalizadas para garantir que recursos compostos reportem status preciso.

10. Versionar seus XRDs — comece com v1alpha1 e promova através de v1beta1 até v1 conforme sua API estabiliza.