Skip to main content

Instalación

Vamos a instalar Crossplane usando Helm. Documentación oficial de la instalación

Vamos a tomar en consideración que:

  • Ya tengas un clúster creado
  • Ya tengas kubectl instalado
  • Ya tengas helm instalado versión 3 o superior

Vamos a descargar el helm chart

helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
# Vamos a hacer la descarga de todos los templates
# El comando abajo creará una carpeta llamada crossplane en la raíz donde fue aplicado el comando, de ser necesario muévete a la ubicación correcta.
helm pull crossplane-stable/crossplane --untar

En este momento estamos en una transición de la versión v1 a v2 de Crossplane.

Cuando uso Helm me gusta descargar localmente todos los archivos usados por el chart y tener el código fuente en mis manos para analizar localmente lo que tenemos desarrollado por la comunidad.

Una buena sugerencia es que crees un respaldo del values.yaml a fin de dejarlo para consulta futura en caso de que lo necesites.

cd crossplane
cp values.yaml values_bkp.yaml

Para aplicar este values.yaml vamos a ejecutar los comandos abajo solamente cuando todo esté configurado.

# Es bueno crear un namespace dedicado antes en lugar de pasar el parámetro --create-namespace crossplane para crear junto en el comando de helm.
kubectl create namespace crossplane-system
helm install crossplane . -n crossplane-system

Si estás instalando por primera vez y estás probando, después de entender los recursos vuelve aquí y ajusta el values. Pero por ahora, baby steps, ve con el default

Con el comando arriba podemos ver que fueron creados 2 deployments, uno para el crossplane y uno para el rbac-manager y sus respectivos pods y replicasets, así como el 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

Buena práctica​

Creo que Crossplane podría tener al menos 2 pods en su replicaset y que cada uno de los pods estuviera en nodos diferentes. Caso tu clúster distribuya nodos en más de una región sería bueno garantizar aún que estén en nodos diferentes y regiones diferentes, en el caso de cloud.

Existen varias maneras de resolver esto, pero una de ellas es alterar el template del deployment y agregar:

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​

El deployment principal de Crossplane es responsable de ejecutar el Crossplane Core, que actúa como el orquestador central de toda la plataforma. Este deployment ejecuta múltiples controladores dentro de un único proceso, cada uno con responsabilidades específicas:

Package Manager Controller​

  • Gestiona la instalación, actualización y eliminación de providers y configurations
  • Resuelve dependencias automáticas entre packages
  • Monitorea el estado de salud de los packages instalados
  • Controla el ciclo de vida completo de los componentes

Composition Controller​

  • Procesa CompositeResourceDefinitions (XRDs) y sus respectivas Compositions
  • Gestiona el ciclo de vida de Composite Resources (XRs) y Claims (XRCs)
  • Realiza transformaciones y mapeos entre recursos de alto nivel y managed resources
  • Ejecuta loops de reconciliación continua para mantener consistencia

Revision Controller​

  • Controla versionado de packages y compositions
  • Permite rollbacks seguros entre versiones
  • Mantiene histórico de revisiones para auditoría

Deployment crossplane-rbac-manager​

El crossplane-rbac-manager es un deployment dedicado que automatiza la gestión de permisos RBAC para todos los componentes de Crossplane. Se instala y habilita por defecto, creando y manteniendo automáticamente todos los ClusterRoles necesarios.

Responsabilidades Principales:

  • Gestión de Service Accounts

    • Crea y vincula roles RBAC específicos para cuentas de servicios de los providers
    • Permite que providers controlen sus managed resources con permisos adecuados
    • Configura la crossplaneServiceAccount con permisos para crear recursos gestionados

  • Automatización de ClusterRoles

    • Genera automáticamente ClusterRoles basadas en los CRDs instalados por los providers
    • Mantiene sincronización entre nuevos providers y sus permisos necesarios
    • Elimina permisos obsoletos cuando providers son desinstalados

Jerarquía de Roles Por Defecto​

Crossplane crea una jerarquía bien definida de roles para diferentes niveles de acceso:

  • crossplane-admin

    • Acceso completo a todos los recursos Crossplane
    • Capacidad de gestionar providers, compositions y managed resources
    • Puede vincular roles RBAC a otras entidades (requiere cuidado en producción)

  • crossplane-edit

    • Creación y modificación de recursos Crossplane
    • Acceso para desarrollo y operaciones cotidianas
    • Sin capacidad de gestionar permisos RBAC

  • crossplane-view

    • Visualización de todos los recursos Crossplane
    • Ideal para monitoreo y auditoría
    • Acceso solo lectura a los recursos gestionados

  • crossplane-browse

    • Navegación básica por los recursos Crossplane
    • Acceso más restrictivo para usuarios que necesitan solo visualizar información básica

Roles Específicos por Namespace​

Además de los ClusterRoles globales, el RBAC manager también crea roles específicas para namespaces, permitiendo control granular de acceso por proyecto o equipo.

Si quieres entender mejor verifica

❯ 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 la instalación​

En un segundo momento cuando tengas todo bien fundamentado ve todo lo que puede ser personalizado en la instalación.

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

Aunque sea posible definir providers, functions y otras configuraciones directamente en el values.yaml del Helm chart durante la instalación de Crossplane, este enfoque no es recomendado en la práctica. Mantener manifiestos separados para cada componente ofrece mayor flexibilidad, control granular y facilita el versionado y el mantenimiento de los recursos. Además, esta separación permite mejor trazabilidad de los cambios y facilita la implementación de prácticas de GitOps.

CRDs Overview​

Antes de iniciar el contenedor Crossplane principal, un contenedor init es ejecutado. El contenedor init instala los Custom Resource Definitions, configura los webhooks de Crossplane e instala cualesquiera proveedores o configuraciones proporcionados, pero nosotros no proporcionamos ninguno por ahora durante la instalación. ¿Podríamos? sí, pero no lo hicimos.

Los CRDs son estos.

❯ 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 ejemplo vemos el CRD providers y podríamos haber definido qué providers deberían ser instalados usando el values.yaml en el helm chart en el punto abajo, o simplemente haríamos eso después con el manifiesto de providers.

provider:
  # -- A list of Provider packages to install.
  packages: []
### Si fuera a agregar un provider de aws...
  # packages:
  #   xpkg.upbound.io/crossplane-contrib/provider-aws: v0.39.0

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

Los principales CRDs instalados por el contenedor init incluyen:

  • CompositeResourceDefinitions, Compositions, Configurations and Providers
  • Bloqueos para gestionar dependencias de paquetes
  • ControllerConfigs para aplicar configuraciones a los proveedores instalados
  • StoreConfigs para conectar almacenamientos de secretos externos como HashiCorp Vault
  • DeploymentRuntimeConfigs para personalizar cómo los providers son ejecutados (detallado en RuntimeConfig)

El pod crossplane trabaja en loop de reconciliación, verificando constantemente el estado de los recursos desplegados y corrigiendo cualquier diferencia. Existe un tiempo para esto que puede ser alterado.

Crossplane monitorea los recursos por medio de un watch de Kubernetes o por medio de sondeos periódicos. Algunos recursos pueden ser observados y sondeados.

Crossplane solicita que el kube-api-server de kubernetes lo notifique sobre cualesquiera alteraciones en los objetos. Esta herramienta de notificación es un Watch. El kube-api-server notificará de los cambios en los recursos de crossplane, pero no dentro de los providers. Esta es una función de crossplane, monitorear las diferencias entre lo que debe hacer y lo que ya tiene de recurso en el provider.

El pod de crossplane puede recibir algunos argumentos, que son definidos dentro de arg, para alterar su configuración. Abajo un ejemplo alterando algunas cosas.

args:
# Sondeo periódico de los ítems que la api de kubernetes no es responsable, sino crossplane
- args:
- core
- start
- --sync-interval=60m # este es el default
- --poll-interval=1m # este es el default
- --max-reconcile-rate=10 # 10 veces es el default

Ahora que ya tienes un crossplane instalado, vamos a crear nuestro primer provider en provider

Uninstall​

Para desinstalar Crossplane completamente es necesario seguir un orden, pues existen dependencias entre los recursos.

Además desinstalar un provider eliminará todos los custom resources definitions que controla entonces el recurso quedará abandonado, es decir, existente pero sin control alguno como si hubiera sido creado manualmente, pues no serán eliminados.

  • Elimina todas las composiciones

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

  • Elimina todos los recursos gestionados

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

  • Elimina todos los providers

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

  • Desinstala usando helm si lo instalaste por helm

 helm uninstall crossplane --namespace crossplane-system
 ## Por último elimina el namespace
 kubectl delete namespace crossplane-system

Crossplane CLI​

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

Existe un CLI de Crossplane que puede ser usado para instalar y configurar providers, pero nada que no puedas hacer usando los manifiestos. Este CLI está más para uso en el desarrollo de providers.

Gestión de Dependencias​

Como vimos anteriormente un paquete puede tener dependencia de otros paquetes incluyendo configuraciones y otros providers.

Luego al instalar si esto no puede ser resuelto tendremos el Health abajo como False en lugar de true. Para ver el motivo haz un describe en el 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

Actualizar es simple, solamente altera la versión del paquete.