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.

Actualizaciones Automatizadas

Descripción general

Puedes gestionar las actualizaciones del clúster K3s utilizando el Upgrade Controller de Rancher. Este es un enfoque nativo de Kubernetes para las actualizaciones de clúster. Aprovecha un Plan Recurso Personalizado para describir de manera declarativa qué nodos actualizar y a qué versión.

El plan define políticas y requisitos de actualización. También define qué nodos deben ser actualizados a través de un selector de etiquetas. Consulta a continuación los planes con valores predeterminados apropiados para actualizar un clúster K3s. Para opciones de configuración de planes más avanzadas, consulta la documentación del Plan enlazada arriba.

El Upgrade Controller programa actualizaciones al monitorizar los planes y seleccionar nodos en los cuales ejecutar Jobs. Cuando un trabajo se ha completado con éxito, el controlador etiquetará el nodo en el que se ejecutó en consecuencia.

Si el clúster K3s es gestionado por Rancher, deberías utilizar la interfaz de usuario de Rancher para gestionar las actualizaciones.

Si el clúster K3s está importado (registrado) en Rancher, Rancher gestiona por defecto la ampliación del Upgrade Controller y los planes. No sigas los pasos en esta página a menos que hayas desactivado la gestión de versiones en Rancher. Consulta Configuración de la Gestión de Versiones para Clústeres RKE2 y K3s para más información.
Si el clúster K3s es provisionado por Rancher, Rancher utiliza el agente del sistema para gestionar las actualizaciones de versión. No sigas los pasos en esta página.
Si el clúster K3s no es gestionado por Rancher, puedes seguir los pasos a continuación.

Usando el Controlador de Actualización del Sistema

Para automatizar actualizaciones, debes hacer lo siguiente:

Instala el Upgrade Controller en tu clúster
Crea planes que describan qué grupos de nodos actualizar y cómo.

Para más detalles sobre el diseño y la arquitectura del Upgrade Controller o su integración con K3s, consulta los siguientes repositorios de Git:

Al intentar actualizar a una nueva versión de K3s, se aplica la política de desajuste de versión de Kubernetes. Asegúrate de que tu plan no omita versiones menores intermedias al actualizar. El controlador de actualización del sistema en sí no protegerá contra cambios no soportados en la versión de Kubernetes.

Instalación

El manifiesto del Upgrade Controller instala una definición de recurso personalizado, un despliegue, una cuenta de servicio, un enlace de rol de clúster y un configmap. Para instalar estos componentes, ejecuta el siguiente comando:

kubectl apply -f https://github.com/rancher/system-upgrade-controller/releases/latest/download/crd.yaml -f https://github.com/rancher/system-upgrade-controller/releases/latest/download/system-upgrade-controller.yaml

El controlador puede ser configurado y personalizado a través del configmap mencionado anteriormente, pero el pod del controlador debe ser eliminado para que los cambios se apliquen.

Configuración

Los nodos de servidor siempre deben actualizarse antes que los nodos de agente. Por esta razón, se recomienda que crees al menos dos planes: un plan para actualizar los nodos de servidor (control-plane) y un plan para actualizar los nodos de agente. Puedes crear planes adicionales según sea necesario para controlar el despliegue de la actualización en los nodos. Después de que se crean los planes, el controlador los recoge y comienza a actualizar tu clúster.

Los siguientes dos planes de ejemplo mantienen continuamente tu clúster actualizado a la versión estable actual, apuntando al canal de lanzamiento estable:

# Server plan
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
  name: server-plan
  namespace: system-upgrade
spec:
  concurrency: 1
  cordon: true
  nodeSelector:
    matchExpressions:
    - key: node-role.kubernetes.io/control-plane
      operator: In
      values:
      - "true"
  serviceAccountName: system-upgrade
  upgrade:
    image: rancher/k3s-upgrade
  channel: https://update.k3s.io/v1-release/channels/stable
---
# Agent plan
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
  name: agent-plan
  namespace: system-upgrade
spec:
  concurrency: 1
  cordon: true
  nodeSelector:
    matchExpressions:
    - key: node-role.kubernetes.io/control-plane
      operator: DoesNotExist
  prepare:
    args:
    - prepare
    - server-plan
    image: rancher/k3s-upgrade
  serviceAccountName: system-upgrade
  upgrade:
    image: rancher/k3s-upgrade
  channel: https://update.k3s.io/v1-release/channels/stable

Hay algunas cosas importantes a destacar respecto a estos planes:

Los planes deben ser creados en el mismo espacio de nombres donde se despliega el controlador.
El campo concurrency indica cuántos nodos pueden ser actualizados al mismo tiempo.
El plan del servidor dirige a los nodos del servidor especificando un selector de etiquetas que selecciona nodos con la etiqueta node-role.kubernetes.io/control-plane. El plan del agente dirige los nodos del agente especificando un selector de etiquetas que selecciona nodos sin esa etiqueta.
El prepare paso en el plan del agente hace que los trabajos de actualización para ese plan esperen a que el plan del servidor se complete antes de ejecutarse. Esta lógica está integrada en la imagen utilizada para el paso de preparación, y no forma parte del controlador de actualización del sistema en sí.
Ambos planes tienen el campo channel configurado a la URL del canal de lanzamiento estable. Esto provoca que el controlador monitorice esa URL y actualice el clúster cada vez que se resuelva a un nuevo lanzamiento. Esto funciona bien con los canales de lanzamiento. Así, puedes configurar tus planes con el siguiente canal para asegurar que tu clúster se actualice automáticamente a la versión estable más nueva de K3s. Alternativamente, puedes omitir el campo channel y establecer el campo version a una versión específica de K3s:
```
apiVersion: upgrade.cattle.io/v1
kind: Plan
# ...
spec:
  # ...
  version: v1.33.4+k3s1
```

La actualización comienza tan pronto como el controlador detecta que la versión objetivo para un plan ha sido resuelta, ya sea desde el campo de versión o consultando el servidor del canal. Modificar un plan provoca que el controlador reevalúe el plan y determine si se necesita otra actualización. Si se ha configurado un canal, la URL también se consulta periódicamente para verificar nuevas versiones.

Puedes monitorizar el progreso de una actualización viendo el plan y los trabajos a través de kubectl:

kubectl -n system-upgrade get plans -o wide
kubectl -n system-upgrade get jobs

Programación de Actualizaciones

Los planes pueden ser restringidos a ocurrir dentro de una ventana de tiempo específica configurando el campo window dentro de la especificación del plan. Los campos de la ventana de tiempo son compatibles y tienen el mismo formato que opciones de programación de kured. Por ejemplo:

apiVersion: upgrade.cattle.io/v1
kind: Plan
# ...
spec:
  # ...
  window:
    days:
      - monday
      - tuesday
      - wednesday
      - thursday
      - friday
    startTime: 19:00
    endTime: 21:00
    timeZone: UTC

Los trabajos para ejecutar actualizaciones para un plan no se crean fuera de la ventana de tiempo. Después de que se crean los trabajos, los planes pueden seguir ejecutándose después de que la ventana se haya cerrado.

Prevención de degradación

Puerta de Versión

Comenzando con los lanzamientos de 2023-07 (v1.27.4+k3s1, v1.26.7+k3s1, v1.25.12+k3s1, v1.24.16+k3s1)

Kubernetes no soporta degradaciones de los componentes del plano de control. La imagen de k3s-upgrade utilizada por los planes de actualización se negará a degradar K3s, fallando el plan. Los nodos con cordon: true configurado en su plan permanecerán aislados tras el fallo.

Aquí hay un clúster de ejemplo, mostrando pods de actualización fallidos y nodos aislados:

$ kubectl get pods -n system-upgrade
NAME                                                              READY   STATUS    RESTARTS   AGE
apply-k3s-server-on-ip-172-31-0-16-with-7af95590a5af8e8c3-2cdc6   0/1     Error     0          9m25s
apply-k3s-server-on-ip-172-31-10-23-with-7af95590a5af8e8c-9xvwg   0/1     Error     0          14m
apply-k3s-server-on-ip-172-31-13-213-with-7af95590a5af8e8-8j72v   0/1     Error     0          18m
system-upgrade-controller-7c4b84d5d9-kkzr6                        1/1     Running   0          20m
$ kubectl get nodes
NAME               STATUS                     ROLES                       AGE   VERSION
ip-172-31-0-16     Ready,SchedulingDisabled   control-plane,etcd,master   19h   v1.27.4+k3s1
ip-172-31-10-23    Ready,SchedulingDisabled   control-plane,etcd,master   19h   v1.27.4+k3s1
ip-172-31-13-213   Ready,SchedulingDisabled   control-plane,etcd,master   19h   v1.27.4+k3s1
ip-172-31-2-13     Ready                      <none>                      19h   v1.27.4+k3s1

Puedes devolver tus nodos aislados al servicio mediante cualquiera de los siguientes métodos:

Cambia la versión o canal en tu plan para apuntar a una versión que sea la misma o más nueva que la que se está ejecutando actualmente en el clúster, de modo que el plan tenga éxito.
Elimina el plan y desaisla manualmente los nodos. Usa kubectl get plan -n system-upgrade para encontrar el nombre del plan, luego kubectl delete plan -n system-upgrade PLAN_NAME para eliminarlo. Una vez que el plan ha sido eliminado, usa kubectl uncordon NODE_NAME para desaislar cada uno de los nodos.

Seguridad

El trabajo de actualización que se lanza debe tener privilegios elevados para poder realizar cambios en los nodos subyacentes. Por defecto, está configurado con lo siguiente:

Espacios de nombres del host: IPC, NET y PID
La capacidad CAP_SYS_BOOT
Host root montado en /host con permisos de lectura y escritura