Este documento ha sido traducido utilizando tecnología de traducción automática. Si bien nos esforzamos por proporcionar traducciones precisas, no ofrecemos garantías sobre la integridad, precisión o confiabilidad del contenido traducido. En caso de discrepancia, la versión original en inglés prevalecerá y constituirá el texto autorizado.

Actualización a CAPI v1beta2

La versión v0.26.0 de Rancher Turtles adopta el contrato CAPI v1beta2, que viene con CAPI kernel v1.12.2. Si está utilizando aprovisionamiento basado en CAPI, hay algunas cosas que revisar antes de actualizar.

Los cambios se dividen en tres áreas:

Lea las secciones que se aplican a su configuración antes de realizar cualquier cambio.

Una nota sobre la compatibilidad hacia atrás

CAPI v1.12 sigue sirviendo v1beta1 recursos junto a v1beta2. Los recursos existentes en su clúster seguirán funcionando sin una migración inmediata, ya que el servidor API convierte entre las dos versiones de forma transparente. Dicho esto, cualquier nuevo manifiesto que escriba debe dirigirse a v1beta2, y debe planear migrar los existentes con el tiempo. La API v1beta1 está programada para ser eliminada en una futura versión de CAPI (agosto de 2026) una vez que el ecosistema haya tenido tiempo para asentarse en v1beta2.

Recomendación: primero evalúe si está listo para adoptar v1beta2 y actúe en consecuencia. Si elige no migrar de inmediato, cree un plan para cambiar al uso de la nueva API para evitar interrupciones en el futuro.

Además, la comunidad upstream proporciona una guía oficial de migración:

  • CAPI v1.10 a v1.11: esto cubre todos los cambios de v1beta1 a v1beta2 en el kernel de CAPI.

  • CAPI v1.11 a v1.12: la mayoría de los cambios en CAPI v1.12 pueden considerarse menores.

ClusterClass

Referencias de plantillas

En v1beta1, el campo que apunta a los objetos de plantilla ClusterClass se llamaba ref. En v1beta2 se llama templateRef. Esto se aplica a spec.infrastructure, spec.controlPlane y spec.controlPlane.machineInfrastructure.

Antes:

spec:
  infrastructure:
    ref:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: DockerClusterTemplate
      name: my-cluster-template

Después del:

spec:
  infrastructure:
    templateRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
      kind: DockerClusterTemplate
      name: my-cluster-template

Sección de trabajadores

En v1beta1, las referencias de iniciar e infraestructura para las ampliaciones de máquinas estaban anidadas bajo un campo template. Esta clave raíz ha desaparecido en v1beta2. bootstrap y infrastructure son ahora hijos directos de la entrada de ampliación de máquina.

Antes:

workers:
  machineDeployments:
    - class: default-worker
      template:
        bootstrap:
          ref:
            apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
            kind: KubeadmConfigTemplate
            name: my-bootstrap-template
        infrastructure:
          ref:
            apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
            kind: DockerMachineTemplate
            name: my-worker-template

Después del:

workers:
  machineDeployments:
    - class: default-worker
      bootstrap:
        templateRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
          kind: KubeadmConfigTemplate
          name: my-bootstrap-template
      infrastructure:
        templateRef:
          apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
          kind: DockerMachineTemplate
          name: my-worker-template

Clúster

El recurso Cluster ahora hace referencia a su ClusterClass a través de un objeto estructurado en lugar de una cadena en línea. En v1beta1, el nombre de la clase y el espacio de nombres se especificaron como spec.topology.class y spec.topology.classNamespace. En v1beta2, ambos campos son reemplazados por un único objeto spec.topology.classRef.

Antes:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
spec:
  topology:
    class: my-clusterclass
    classNamespace: capi-system

Después del:

apiVersion: cluster.x-k8s.io/v1beta2
kind: Cluster
spec:
  topology:
    classRef:
      name: my-clusterclass
      namespace: capi-system

El resto de la especificación de Cluster (configuraciones de red, controlPlane.replicas, workers.machineDeployments, variables, version, etc.) permanece sin cambios.

Proveedor RKE2 (CAPRKE2)

Esta versión incluye CAPRKE2 v0.23.1, en lugar de v0.22.1. La API v1beta2 para los recursos de iniciar y plano de control de RKE2 se introdujo en v0.22.0 junto con el soporte para CAPI v1.11, y v0.23.0 completó ese trabajo al actualizar a CAPI v1.12.2. Tanto v0.22.1 como v0.23.1 son versiones de parche sobre esas versiones menores respectivas.

Nota: lee la documentación del proveedor sobre los cambios de API del libro del proveedor CAPI RKE2

Nueva API v1beta2

CAPRKE2 ahora ofrece su propia API v1beta2 para RKE2ControlPlane, RKE2ControlPlaneTemplate y RKE2Config/RKE2ConfigTemplate. La API v1beta1 sigue disponible, pero varios campos que habían sido marcados como obsoletos en v1beta1 ahora se han eliminado en v1beta2.

Campos eliminados en RKE2ControlPlane

Los siguientes campos han sido eliminados de RKE2ControlPlane.spec en v1beta2:

  • infrastructureRef — utiliza spec.machineTemplate.spec.infrastructureRef en su lugar.

  • nodeDrainTimeout — utiliza spec.machineTemplate.spec.deletion.nodeDrainTimeout en su lugar.

Se han renombrado los campos de tiempo de espera.

Los campos de tiempo de espera en RKE2ControlPlaneMachineTemplate se han movido bajo un subobjeto deletion y se han renombrado. También han cambiado de tipo de metav1.Duration a int32, y ahora esperan valores expresados en segundos en lugar de una cadena de duración.

v1beta1 v1beta2

nodeDrainTimeout

deletion.nodeDrainTimeoutSeconds

nodeVolumeDetachTimeout

deletion.nodeVolumeDetachTimeoutSeconds

nodeDeletionTimeout

deletion.nodeDeletionTimeoutSeconds

El objeto RKE2ControlPlaneMachineTemplate ahora también requiere un campo spec.

Deprecación de v1alpha1

La API v1alpha1 quedó obsoleta en CAPRKE2 v0.22.0. Si todavía está utilizando recursos v1alpha1, ahora es un buen momento para migrar a al menos v1beta1.

Pasos recomendados a seguir antes de actualizar

  1. Actualice cualquier manifiesto ClusterClass que mantenga: renombre ref a templateRef, elimine el wrapper template en la sección de trabajadores y actualice las cadenas CAPI apiVersion a v1beta2.

  2. Actualice cualquier manifiesto Cluster: reemplace spec.topology.class y spec.topology.classNamespace por spec.topology.classRef.name y spec.topology.classRef.namespace.

  3. Si utiliza recursos CAPRKE2 v1beta2, elimine cualquier campo directo infrastructureRef o nodeDrainTimeout de RKE2ControlPlane.spec y muévalos a spec.machineTemplate.spec.

  4. Consulte los ejemplos actualizados en examples/clusterclasses/ para obtener manifiestos completos y funcionales para cada proveedor CAPI certificado.