Instalação

Vamos instalar o Crossplane usando o Helm. Documentação oficial da instalação

Vamos levar em consideração que:

Já tenha um cluster criado
Já tenha o kubectl instalado
Já tenha o helm instalado versão 3 ou superior

Vamos baixar o helm chart

helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
# Vamos fazer o download de todos os templates
# O comando abaixo irá criar uma pasta chamado crossplane na raiz de onde foi aplicado o comando, caso necessário mova-se para o local correto.
helm pull crossplane-stable/crossplane --untar

Neste momento estamos em uma transição da versão v1 para v2 do Crossplane.

Quando uso o Helm eu gosto de baixar localmente todos os arquivos usados pela chart e ter o código fonte em minhas mãos para analisar localmente o que temos desenvolvido pela comunidade.

Uma boa sugestão é que crie um backup do values.yaml afim de deixá-lo para consulta futura caso precise.

cd crossplane
cp values.yaml values_bkp.yaml

Para aplicar este values.yaml vamos executar os comandos abaixo somente quando tudo tiver configurado.

# É bom criar um namespace dedicado ao antes ao invés de passar o parametro --create-namespace crossplane para criar junto no comando do helm.
kubectl create namespace crossplane-system
helm install crossplane . -n crossplane-system

Se você estiver instalando a primeira vez e está testando, depois de entender os recursos volte aqui e afine o values. Mas por enquanto, baby steps, vai no default

Com o comando acima podemos ver que foram criados 2 deployments, uma para o crossplane e um para o rbac-manager e seus respectivos pods e replicasets, bem com o service crossplane-webhook.

❯ kubectl get all --namespace crossplane-system  

NAME                                           READY   STATUS    RESTARTS   AGE
pod/crossplane-5d66b859db-jdfrp                1/1     Running   0          100s
pod/crossplane-rbac-manager-649488698b-r5sbm   1/1     Running   0          100s

NAME                          TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
service/crossplane-webhooks   ClusterIP   172.20.169.218   <none>        9443/TCP   101s

NAME                                      READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/crossplane                1/1     1            1           101s
deployment.apps/crossplane-rbac-manager   1/1     1            1           101s

NAME                                                 DESIRED   CURRENT   READY   AGE
replicaset.apps/crossplane-5d66b859db                1         1         1       101s
replicaset.apps/crossplane-rbac-manager-649488698b   1         1         1       101s

Boa prática

Acredito que o Crossplane poderia ter pelo menos 2 pods no seu replicaset e que cada um dos pods estivesse em nodes diferentes. Caso o seu cluster distribua nodes em mais de uma região seria bom garantir ainda que estejam em nodes diferentes e regiões diferentes, no caso de cloud.

Existem várias maneiras de resolver isso, mas uma delas é alterar o template do deployment e adicionar:

replicas: 2
topologySpreadConstraints:
- maxSkew: 1
  topologyKey: "kubernetes.io/hostname"
  whenUnsatisfiable: DoNotSchedule
  labelSelector:
    matchLabels:
      app.kubernetes.io/name: crossplane
- maxSkew: 1
topologyKey: "topology.kubernetes.io/region"
whenUnsatisfiable: DoNotSchedule
labelSelector:
    matchLabels:
    app: crossplane

Deployment Crossplane

O deployment principal do Crossplane é responsável por executar o Crossplane Core, que atua como o orquestrador central de toda a plataforma. Este deployment executa múltiplos controllers dentro de um único processo, cada um com responsabilidades específicas:

Package Manager Controller

Gerencia a instalação, atualização e remoção de providers e configurations
Resolve dependências automáticas entre packages
Monitora o status de saúde dos packages instalados
Controla o ciclo de vida completo dos components

Composition Controller

Processa CompositeResourceDefinitions (XRDs) e suas respectivas Compositions
Gerencia o ciclo de vida de Composite Resources (XRs) e Claims (XRCs)
Realiza transformações e mapeamentos entre recursos de alto nível e managed resources
Executa loops de reconciliação contínua para manter consistência

Revision Controller

Controla versioning de packages e compositions
Permite rollbacks seguros entre versões
Mantém histórico de revisões para auditoria

Deployment crossplane-rbac-manager

O crossplane-rbac-manager é um deployment dedicado que automatiza o gerenciamento de permissões RBAC para todos os componentes do Crossplane. Ele é instalado e habilitado por padrão, criando e mantendo automaticamente todas as ClusterRoles necessárias.

Responsabilidades Principais:

Gerenciamento de Service Accounts
- Cria e vincula funções RBAC específicas para contas de serviços dos providers
- Permite que providers controlem seus managed resources com permissões adequadas
- Configura a crossplaneServiceAccount com permissões para criar recursos gerenciados
Automação de ClusterRoles
- Gera automaticamente ClusterRoles baseadas nos CRDs instalados pelos providers
- Mantém sincronização entre novos providers e suas permissões necessárias
- Remove permissões obsoletas quando providers são desinstalados

Hierarquia de Roles Padrão

O Crossplane cria uma hierarquia bem definida de roles para diferentes níveis de acesso:

crossplane-admin
- Acesso completo a todos os recursos Crossplane
- Capacidade de gerenciar providers, compositions e managed resources
- Pode vincular roles RBAC a outras entidades (requer cuidado em produção)
crossplane-edit
- Criação e modificação de recursos Crossplane
- Acesso para desenvolvimento e operações cotidianas
- Sem capacidade de gerenciar permissões RBAC
crossplane-view
- Visualização de todos os recursos Crossplane
- Ideal para monitoramento e auditoria
- Acesso somente leitura aos recursos gerenciados
crossplane-browse
- Navegação básica pelos recursos Crossplane
- Acesso mais restritivo para usuários que precisam apenas visualizar informações básicas

Roles Específicas por Namespace

Além das ClusterRoles globais, o RBAC manager também cria roles específicas para namespaces, permitindo controle granular de acesso por projeto ou equipe.

Se quiser entender melhor verifique

❯ kubectl get clusterrole -l=app=crossplane

NAME                                        CREATED AT
crossplane                                  2023-07-30T18:21:36Z
crossplane-admin                            2023-07-30T18:21:36Z
crossplane-browse                           2023-07-30T18:21:36Z
crossplane-edit                             2023-07-30T18:21:36Z
crossplane-rbac-manager                     2023-07-30T18:21:36Z
crossplane-view                             2023-07-30T18:21:36Z
crossplane:aggregate-to-admin               2023-07-30T18:21:36Z
crossplane:aggregate-to-browse              2023-07-30T18:21:36Z
crossplane:aggregate-to-edit                2023-07-30T18:21:36Z
crossplane:aggregate-to-view                2023-07-30T18:21:36Z
crossplane:allowed-provider-permissions     2023-07-30T18:21:36Z
crossplane:system:aggregate-to-crossplane   2023-07-30T18:21:36Z

Personalizando a instalação

Em um segundo momento quando tiver tudo bem fundamentado veja tudo que pode ser personalizado na instalação.

https://docs.crossplane.io/v1.20/software/install/#customize-the-crossplane-helm-chart

Embora seja possível definir providers, functions e outras configurações diretamente no values.yaml do Helm chart durante a instalação do Crossplane, essa abordagem não é recomendada na prática. Manter manifestos separados para cada componente oferece maior flexibilidade, controle granular e facilita o versionamento e a manutenção dos recursos. Além disso, essa separação permite melhor rastreabilidade das mudanças e facilita a implementação de práticas de GitOps.

CRDs Overview

Antes de iniciar o contêiner Crossplane principal, um contêiner init é executado. O contêiner init instala os Custom Resource Definitions, configura os webhooks do Crossplane e instala quaisquer provedores ou configurações fornecidos, mas nós não fornecemos nenhum por enquanto durante a instalação. Poderíamos? sim, mas não fizemos.

Os CRDs são esses.

❯ kubectl api-resources  | grep crossplane
NAME                                SHORTNAMES   APIVERSION                            NAMESPACED   KIND
compositeresourcedefinitions        xrd,xrds     apiextensions.crossplane.io/v1        false        CompositeResourceDefinition
compositionrevisions                comprev      apiextensions.crossplane.io/v1        false        CompositionRevision
compositions                        comp         apiextensions.crossplane.io/v1        false        Composition
environmentconfigs                  envcfg       apiextensions.crossplane.io/v1beta1   false        EnvironmentConfig
usages                                           apiextensions.crossplane.io/v1beta1   false        Usage
configurationrevisions                           pkg.crossplane.io/v1                  false        ConfigurationRevision
configurations                                   pkg.crossplane.io/v1                  false        Configuration
controllerconfigs                                pkg.crossplane.io/v1alpha1            false        ControllerConfig
deploymentruntimeconfigs                         pkg.crossplane.io/v1beta1             false        DeploymentRuntimeConfig
functionrevisions                                pkg.crossplane.io/v1                  false        FunctionRevision
functions                                        pkg.crossplane.io/v1                  false        Function
imageconfigs                                     pkg.crossplane.io/v1beta1             false        ImageConfig
locks                                            pkg.crossplane.io/v1beta1             false        Lock
providerrevisions                                pkg.crossplane.io/v1                  false        ProviderRevision
providers                                        pkg.crossplane.io/v1                  false        Provider
storeconfigs                                     secrets.crossplane.io/v1alpha1        false        StoreConfig

Por exemplo vemos o CRD providers e poderíamos ter definido quais providers deveriam ser instalados usando o values.yaml no helm chart no ponto abaixo, ou simplesmente faríamos isso depois algum o manifesto de providers.

provider:
  # -- A list of Provider packages to install.
  packages: []
### Se fosse adicionar um provider da aws...
  # packages:
  #   xpkg.upbound.io/crossplane-contrib/provider-aws: v0.39.0

configuration:
  # -- A list of Configuration packages to install.
  packages: []

Os principais CRDs instalados pelo contêiner init incluem:

CompositeResourceDefinitions, Compositions, Configurations and Providers
Bloqueios para gerenciar dependências de pacotes
ControllerConfigs para aplicar configurações aos provedores instalados
StoreConfigs para conectar armazenamentos segredos externos como o HashiCorp Vault
DeploymentRuntimeConfigs para personalizar como os providers são executados (detalhado em RuntimeConfig)

O pod crossplane trabalha em loop de reconciliação, verificando constantemente o status dos recursos implantados e corrigindo qualquer diferença. Existe um tempo para isso que pode ser alterado.

O Crossplane monitora os recursos por meio de um relógio do Kubernetes ou por meio de pesquisas periódicas. Alguns recursos podem ser observados e pesquisados.

O Crossplane solicita que o kube-api-server do kubernetes que o notifique sobre quaisquer alterações nos objetos. Esta ferramenta de notificação é um Watch. O kube-api-server irá notificar dos mudanças nos recursos do crossplane, mas não dentro dos providers. Esta é uma função do crossplane, monitorar as diferenças entre o que ele deve fazer o que ele já tem de recurso no provider.

O pod do crossplane pode receber alguns argumentos, que são definidos dentro de arg, para alterar sua configuração. Embaixo um exemplo alterando algumas coisas.

args:
#pesquia periódica dos itens que a api do kubernetes não é responsável, mas sim o crossplane
- args:
- core
- start
- --sync-interval=60m # esse é o default
- --poll-interval=1m # esse é o default
- --max-reconcile-rate=10 # 10 vezes é o default

Agora que já tem um crossplane instalado, vamos criar nosso primeiro provider em provider

Uninstall

Para desinstalar o Crossplane completamente é necessário seguir uma ordem, pois existem dependências entre os recursos.

Além disso desinstalar um provider removerá todos os custom resources definitions que ele controla então o recurso ficará abandonado, ou seja, existente mas sem controle algum como se tivesse sido criado manualmente, pois não serão excluídos.

Remova todas as composições

# Para listar
kubectl get xrd
# kubectl delete xrd x
# kubectl delete xrd y
#  ...

Remova todos os recursos gerenciados

# Para listar
kubectl get managed
# kubectl delete x
# kubectl delete y
#  ...

Remova todos os providers

# Para listar
kubectl get providers
# kubectl delete provider x
# kubectl delete provider y
#  ...

Desinstale o usando o helm se vc instalou pelo helm

 helm uninstall crossplane --namespace crossplane-system
 ## Por ultimo delete o namespace
 kubectl delete namespace crossplane-system

Crossplane CLI

https://github.com/crossplane/crossplane-cli

Existe uma CLI do Crossplane que pode ser usada para instalar e configurar providers, mas nada que você não consiga fazer usando os manifestos. Essa CLI está mais para uso no desenvolvimento de providers.

Gerenciamento de Dependências

Como vimos anteriormente um pacote pode ter dependência de outros pacotes incluindo configurações e outros providers.

Logo ao instalar se isso não conseguir ser resolvido teremos o Health abaixo como False ao invés de true. Para ver o motivo faça um describe no recurso

❯ k get providers  
NAME                          INSTALLED   HEALTHY   PACKAGE                                               AGE
provider-aws-ec2              True        True      xpkg.upbound.io/upbound/provider-aws-ec2:v1           9h
provider-aws-s3               True        True      xpkg.upbound.io/upbound/provider-aws-s3:v1            9h
upbound-provider-family-aws   True        True      xpkg.upbound.io/upbound/provider-family-aws:v1.20.1   9h

Atualizar é simples, somente altere a versão do pacote.

Boa prática​

Deployment Crossplane​

Package Manager Controller​

Composition Controller​

Revision Controller​

Deployment crossplane-rbac-manager​

Hierarquia de Roles Padrão​

Roles Específicas por Namespace​

Personalizando a instalação​

CRDs Overview​

Uninstall​

Crossplane CLI​

Gerenciamento de Dependências​