Skip to main content

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.