Actualizar el entorno de ejecución del clúster desde CLI de Azure

En este artículo se explica cómo realizar una actualización en tiempo de ejecución para un clúster de Operator Nexus.

Prerrequisitos

1. Instale la versión más reciente de las extensiones de la CLI adecuadas.
2. Acceso de suscripción para ejecutar los comandos de extensión de la CLI de nube de red (NC) y tejido de red (NF) de Azure Operator Nexus.
3. Recopile la siguiente información:
   • Identificador de suscripción (SUBSCRIPTION)
   • Nombre del clúster (CLUSTER)
   • Grupo de recursos (CLUSTER_RG)
4. El estado detallado del clúster debe ser Running.
5. La conectividad de Cluster-to-Cluster Manager debe ser Connected.
6. Deben validarse los requisitos previos de Azure (Área de trabajo de Log Analytics, Cuenta de Almacenamiento, Bóveda de Claves). Estos recursos se comprueban antes de que comience la actualización. Consulte Identidad administrada del clúster y recursos proporcionados por el usuario.
7. En Servidores de proceso de carga de trabajo > de clúster >
   • Requisitos de mantenimiento del nodo del plano de control antes de la actualización son:
     • Si no existe ningún nodo de respaldo del plano de control, todos los nodos del plano de control deben estar en buen estado: Estado de alimentación On, estado de cordon Uncordoned, estado Listo Yes y estado Degradado No.
     • Si existe un nodo de plano de control de reserva, solo el nodo de reserva puede estar en el estado de energía Off, el estado NoListo y NoDegradado. Todos los demás nodos del plano de control deben estar en buen estado: estado de energía On, estado de aislamiento Uncordoned, estado Listo Yes y Degradado No.

     Nota:

     Si la máquina de reserva del plano de control ya pasó por un proceso de aprovisionamiento, se espera que esté en estado CordonedCordon. Si no es así, debe estar en estado Cordon Uncordoned.

   • Los servidores del plano de administración se dividen en dos grupos en bastidores impares y pares. En cada grupo, más del 50 % de los servidores deben estar en estado correcto como mínimo: estado de alimentación On, estado de aislamiento Uncordoned, estado de preparación Yes y estado degradado No.
     • En ambos grupos de planos de administración, al menos 75% de las máquinas de administración deben estar en buen estado.
   • Los números de servidor del plano de proceso varían en función de la configuración del umbral de tiempo de ejecución del clúster individual. Los clientes deben determinar su número mínimo en función de su configuración, buscando el estado de energía On, estado de aislamiento Uncordoned, estado listo Yes y estado degradado No.
8. En Grupo de recursos administrados de clúster > , seleccione el nombre del grupo para ir a la página del grupo de recursos.
   • En el grupo de recursos, busque Kubernetes - Azure Arc para identificar la información de Azure Arc y selecciónela. El estado debe ser Connected.
     • En la página de Azure Arc, seleccione la opción Configuración > Extensiones.
       • nc-platform-extension debe estar en estado Succeeded.
       • nc-platform-runtime-extension debe estar en estado Succeeded.

Comprobación de la versión actual del entorno de ejecución

Compruebe la versión actual del entorno de ejecución del clúster antes de la actualización: consulte Comprobación de la versión actual del entorno de ejecución del clúster.

Búsqueda de las versiones en tiempo de ejecución disponibles

A través de Azure Portal

Para buscar las versiones en tiempo de ejecución actualizables disponibles, vaya al clúster de destino en el Azure portal. En el panel De información general del clúster, vaya a la pestaña Versiones de actualización disponibles .

En la pestaña versiones de actualización disponibles , puede ver las distintas versiones del clúster disponibles para actualizar. Seleccione la versión de tiempo de ejecución de destino de la lista y, a continuación, continúe con la actualización del clúster.

A través de CLI de Azure

Las actualizaciones disponibles se pueden recuperar mediante el CLI de Azure:

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A8 availableUpgradeVersions

En la salida, puede encontrar la propiedad availableUpgradeVersions y examinar el campo targetClusterVersion:

  "availableUpgradeVersions": [
    {
      "controlImpact": "True",
      "expectedDuration": "Upgrades may take up to 4 hours + 2 hours per rack",
      "impactDescription": "Workloads will be disrupted during rack-by-rack upgrade",
      "supportExpiryDate": "2023-07-31",
      "targetClusterVersion": "3.3.0",
      "workloadImpact": "True"
    }
  ],

Si no hay actualizaciones de clúster disponibles, la lista está vacía.

Configurar parámetros de umbral de cómputo para la actualización en tiempo de ejecución mediante el clúster updateStrategy

El siguiente comando CLI de Azure se usa para configurar los parámetros de umbral de proceso para una actualización en tiempo de ejecución:

az networkcloud cluster update \
--name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" \
--update-strategy strategy-type="<strategyType>" threshold-type="<thresholdType>" \
threshold-value="<thresholdValue>" max-unavailable="<maxNodesOffline>" \
wait-time-minutes="<waitTimeBetweenRacks>"

Parámetros obligatorios:

• strategy-type: define la estrategia de actualización. La configuración usada es Rack (Rack-by-Rack) OR PauseAfterRack (Pausar para el usuario antes de que se inicie cada rack). El valor por defecto es Rack. Para realizar una actualización en tiempo de ejecución de clúster mediante la PauseAfterRack estrategia, siga los pasos descritos en Upgrade Cluster Runtime with PauseAfterRack Strategy (Actualizar tiempo de ejecución del clúster con PauseAfterRack Strategy).
• threshold-type: determina cómo se debe evaluar el umbral, aplicado en las unidades definidas por la estrategia. La configuración usada es PercentSuccess OR CountSuccess. El valor por defecto es PercentSuccess.
• threshold-value: valor numérico de umbral que se usa para evaluar una actualización. El valor por defecto es 80.

Parámetros opcionales:

• max-unavailable: el número máximo de nodos de trabajo que pueden estar a la vez sin conexión, es decir, el rack actualizado. El valor por defecto es 32767.
• wait-time-minutes: retraso o período de espera antes de actualizar un rack. El valor por defecto es 15.

Comportamiento de actualización basado en el tipo de umbral PercentSuccess

El ejemplo siguiente es para un cliente que usa la estrategia Rack-by-Rack con un porcentaje de éxito de 60% y una pausa de 1 minuto.

az networkcloud cluster update --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" \
threshold-value=60 wait-time-minutes=1 \
--subscription "<SUBSCRIPTION>"

Compruebe la actualización:

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A5 updateStrategy

  "updateStrategy": {
    "maxUnavailable": 32767,
      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 60,
      "waitTimeMinutes": 1

En este ejemplo, una vez que se actualizan correctamente 60% de las máquinas de un bastidor, el sistema considera que se cumple el umbral y continúa actualizando el siguiente bastidor, al tiempo que continúa aprovisionando las máquinas restantes en el bastidor actual. Si no se alcanza el umbral —es decir, si menos del 60 % de las máquinas del bastidor pudieron actualizarse y en su lugar fallaron—, se pone en pausa la actualización del clúster. Cuando se pausa una actualización, el sistema proporciona un mensaje de estado detallado en el clúster que explica el motivo. En ese momento, las máquinas problemáticas del rack deben repararse, y se debe iniciar una operación para continuar con la versión de actualización del clúster, para reanudar y completar la actualización.

Para ver el estado de actualización a través del Azure portal, vaya al recurso clúster de destino. En la pantalla Información general del clúster, el estado detallado se proporciona junto con un mensaje de estado detallado.

La actualización del clúster está en curso cuando detailedStatus está establecido en Updating y detailedStatusMessage muestra el progreso de la actualización. Algunos ejemplos de progreso de actualización, que se muestran en detailedStatusMessage, son Waiting for control plane upgrade to complete..., Waiting for nodepool "<rack-id>" to finish upgrading..., etc.

La actualización del clúster se completa cuando detailedStatus se establece en Running y detailedStatusMessage muestra el mensaje Cluster is up and running.

Si el mensaje de estado detallado muestra que la actualización está en pausa, el mensaje es similar al siguiente: Cluster is deployed but the upgrade has been paused. Machines in rack "<rack-id>" are unhealthy. Fix the machines and perform cluster continue-update-version action to finish the upgrade

Para reanudar la actualización en tiempo de ejecución, ejecute el siguiente comando az networkcloud cli.

az networkcloud cluster continue-update-version --cluster-name "<CLUSTER>" \
--resource-group="<CLUSTER_RG>" \
--subscription="<SUBSCRIPTION>" \
--safeguard-mode <SAFEGUARD_MODE>

Parámetros opcionales:

• --safeguard-mode: especifica cómo se aplican las medidas de seguridad durante la operación continue-update-version. Use All para ejecutar todas las comprobaciones de validación de preoperación. Use None para omitir las medidas de seguridad que bloquean la actualización cuando detectan problemas. El valor por defecto es All.

Comportamiento de actualización según el tipo de umbral de CountSuccess

El ejemplo siguiente es para un cliente que usa la estrategia "Rack-by-Rack" con un tipo de umbral CountSuccess de 10 nodos por bastidor y una pausa de 1 minuto.

az networkcloud cluster update --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--update-strategy strategy-type="Rack" threshold-type="CountSuccess" \
threshold-value=10 wait-time-minutes=1 \
--subscription "<SUBSCRIPTION>"

Compruebe la actualización:

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A5 updateStrategy

  "updateStrategy": {
    "maxUnavailable": 32767,
      "strategyType": "Rack",
      "thresholdType": "CountSuccess",
      "thresholdValue": 10,
      "waitTimeMinutes": 1

En este ejemplo, si se actualizan correctamente al menos 10 nodos, la actualización pasa al siguiente bastidor mientras continúa aprovisionando las máquinas restantes del bastidor actual. Si al menos 10 máquinas del bastidor no se pueden actualizar, la actualización del clúster se pausa. Cuando esto sucede, el hardware necesario debe repararse antes de ejecutar la acción continue-update-version para reanudar y completar la actualización.

Para solucionar problemas con servidores bare metal, consulte Solución de problemas del servidor Azure Operator Nexus

Validaciones que pueden bloquear la actualización en tiempo de ejecución del clúster

Cuando inicia una actualización del entorno de ejecución del clúster, el proceso ejecuta una serie de validaciones previas a la actualización antes de que comience la actualización del entorno de ejecución en las máquinas bare metal del clúster. Estas validaciones confirman que la actualización en tiempo de ejecución puede realizarse correctamente según el estado actual del clúster. Para obtener más información, consulte Validaciones previas a la actualización del entorno de ejecución del clúster.

Actualización del entorno de ejecución del clúster mediante la CLI

Para actualizar la versión del entorno de ejecución del clúster, use el siguiente comando CLI de Azure:

az networkcloud cluster update-version\
--cluster-name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" \
--target-cluster-version "<versionNumber>" \
--safeguard-mode "<SAFEGUARD_MODE>"

Parámetros obligatorios:

• --target-cluster-version: la versión que se va a aplicar al clúster durante la actualización.

Parámetros opcionales:

• --safeguard-mode: especifica cómo se aplican las medidas de seguridad durante la operación de la versión de actualización. Use All para ejecutar todas las comprobaciones de validación de preoperación. Use None para omitir las medidas de seguridad que bloquean la actualización cuando detectan problemas. El valor por defecto es All.

Este comando inicia el proceso de actualización en tiempo de ejecución para el clúster especificado. Normalmente, el propio comando finaliza en unos cinco minutos, pero solo inicia el proceso de actualización una vez que las validaciones se realizan correctamente. La actualización en tiempo de ejecución real continúa ejecutándose en segundo plano y puede tardar varias horas en completarse, ya que actualiza los nodos en bastidor e instala la nueva versión del sistema operativo.

El estado detallado y la información de diagnóstico del paso de inicio están disponibles en Azure portal en el JSON View del recurso Cluster (Operator Nexus). La siguiente información se incluye en la updateVersion entrada del properties.actionStates campo cuando se usa la versión 2025-07-01-preview de API o superior.

• Hora de inicio y finalización de la acción.
• Estado actual (Succeeded, Failedo InProgress).
• Cualquier mensaje de error o contexto adicional asociado al estado actual.
• El Id. de correlación de la operación original cluster update-version, tal como se muestra en el registro de actividad de Azure.
• Lista ordenada de pasos individuales y su estado, por ejemplo Validate Cluster conditions and upgrade versions, y Initiate Platform Runtime Extension update.

Ejemplo JSON View de salida para el recurso Cluster (Operador Nexus):

{
  "properties": {
    "actionStates": [
      {
        "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "status": "Completed",
        "actionType": "Microsoft.NetworkCloud/clusters/updateVersion",
        "endTime": "2025-08-01T03:46:13Z",
        "message": "Cluster upgrade to 4.6.0 successfully initiated - monitor progress via cluster detailed status",
        "startTime": "2025-08-01T03:42:08Z",
        "stepStates": [
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:42:08Z",
            "message": "Cluster validation and version checks passed",
            "startTime": "2025-08-01T03:42:08Z",
            "stepName": "Validate Cluster conditions and upgrade versions"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:11Z",
            "message": "Platform Runtime Extension deployment initiated",
            "startTime": "2025-08-01T03:42:39Z",
            "stepName": "Initiate Platform Runtime Extension update"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:11Z",
            "message": "Platform Runtime Extension installation completed",
            "startTime": "2025-08-01T03:46:11Z",
            "stepName": "Monitor Platform Runtime Extension readiness"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:13Z",
            "message": "Platform Cluster version updated successfully",
            "startTime": "2025-08-01T03:46:13Z",
            "stepName": "Update Platform Cluster version specification"
          }
        ]
      }
    ]
  }
}

Cuando este comando finaliza, comienza el proceso de actualización completa del entorno de ejecución. Este proceso puede tardar varias horas en completarse, en función del número de bastidores del clúster y del número de nodos de trabajo de cada bastidor.

• La actualización actualiza primero los nodos del plano de control, después los nodos de administración y, a continuación, los nodos de trabajo de forma secuencial, bastidor por bastidor.
• Los servidores de administración se separan en dos grupos, que se actualizan por separado. Este enfoque permite a los componentes que se ejecutan en los servidores de administración garantizar la resistencia durante la actualización en tiempo de ejecución aplicando reglas de afinidad.
• Las redes de servicio en la nube (CSN) también usan esta funcionalidad colocando una instancia en cada grupo de administración.
• No hay ninguna interacción del cliente con esta funcionalidad. Sin embargo, es posible que haya otras etiquetas en los nodos de administración para identificar los grupos.

La actualización se considera finalizada cuando se cumplen los umbrales configurados por el clúster updateStrategy para los bastidores de nodos de trabajo y se actualizan correctamente al menos 50% de nodos de administración de cada grupo. Es posible que las cargas de trabajo se vean afectadas mientras se actualizan los nodos de trabajo de un bastidor, pero las cargas de trabajo de todos los demás bastidores no se ven afectadas. Se recomienda tener en cuenta la colocación de cargas de trabajo a la luz de este diseño de implementación.

Supervise el progreso mediante el estado detallado del clúster, disponible a través del portal de Azure o CLI de Azure.

Para ver el estado de actualización a través del CLI de Azure, use az networkcloud cluster show.

az networkcloud cluster show --cluster-name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>"

La salida incluye la información del clúster de destino junto con su estado detallado y el mensaje de estado detallado. Para obtener información más detallada sobre el progreso de la actualización, se puede comprobar el estado de los nodos individuales en cada bastidor. En la sección de referencia se proporciona un ejemplo en Roles de BareMetal Machine.

Para ver el estado de actualización a través del portal de Azure, vaya al recurso de clúster de destino. En la pantalla Información general del clúster, puede ver el estado detallado junto con un mensaje de estado detallado.

La actualización del clúster está en curso cuando detailedStatus se establece en Updating y detailedStatusMessage muestra el progreso de la actualización. Algunos ejemplos de progreso de actualización que se muestran en detailedStatusMessage son Waiting for control plane upgrade to complete... y Waiting for nodepool "<rack-id>" to finish upgrading....

La actualización del clúster se ha completado cuando detailedStatus se establece en Running y detailedStatusMessage muestra Cluster is up and running.

La actualización del clúster queda en pausa cuando detailedStatus se establece en Updating y detailedStatusMessage muestra el motivo o el componente que causó que la actualización se pusiera en pausa.

Actualización del entorno de ejecución de un clúster en pausa

La actualización se detiene cuando se produce alguna de las siguientes acciones:

1. Todas las máquinas del plano de control no se pueden actualizar correctamente y no se aprovisionan ni están listas.
2. Más del 50 % de las máquinas de un grupo del plano de administración no se pueden actualizar y no están aprovisionadas ni listas. Los servidores del plano de administración se dividen en dos grupos en bastidores impares y pares.
3. Las máquinas de nodo de proceso o de trabajo configuradas según el umbral no se pueden actualizar y no están aprovisionadas ni listas.

Revise el mensaje de estado detallado del clúster para identificar qué componente provocó que la actualización entrara en un estado en pausa. Los ejemplos siguientes muestran mensajes de estado detallados para cada componente.

Mensaje de estado detallado del plano de control (KCP)

• "El clúster se implementa, pero la actualización se ha pausado. La actualización del plano de control ha fallado porque capiCluster <clusterName> no está en buen estado. MachineHealthCheck puede estar sustituyendo máquinas KCP no saludables por máquinas del plano de administración para restablecer el cuórum. Espere a que se complete la corrección y, a continuación, ejecute la acción continue-update-version para completar la actualización".

Mensaje detallado de estado del error del grupo del plano de cómputo o de administración

• "El clúster se implementa, pero la actualización se ha pausado. Las máquinas del bastidor "<rack-id>" no funcionan correctamente. Repare las máquinas y ejecute la acción continue-update-version en el clúster para completar la actualización.

Una vez identificado el componente afectado (plano de control, administración o proceso), haga lo siguiente:

Paso 1: Compruebe el estado de cada una de las máquinas sin sistema operativo del componente afectado.

En la sección de referencia se proporciona un ejemplo en Roles de BareMetal Machine.

Después de identificar las máquinas bare metal correspondientes al componente afectado, compruebe el estado de cada máquina y realice las siguientes acciones en función de su estado.

Paso 2: Comprobar los registros de estado de acción para BMM.

Para comprobar los registros del estado de las acciones de un BMM, vaya al recurso BMM >Operaciones>Registro de acciones.

Una vez resuelto el problema y la máquina baremetal está aprovisionada y lista, ejecute la acción del clúster continue-update-version para reanudar y completar la actualización.

az networkcloud cluster continue-update-version \
-g <CLUSTER_RG> \
-n <CLUSTER_NAME> \
--subscription <CUSTOMER_SUB_ID> \
--safeguard-mode <SAFEGUARD_MODE>

Parámetros opcionales:

• --safeguard-mode: especifica cómo se aplican las medidas de seguridad durante la operación continue-update-version. Use All para ejecutar todas las comprobaciones de validación de preoperación. Use None para omitir las medidas de seguridad que bloquean la actualización cuando detectan problemas. El valor por defecto es All.

Preguntas más frecuentes

Identificación de que la actualización del clúster está detenida o bloqueada

Durante una actualización en tiempo de ejecución, el clúster entra en un estado en pausa una vez que el proceso de actualización determina que la actualización no puede continuar sin intervención manual. Sin embargo, es posible que el proceso de actualización a veces no avance mientras el estado detallado sigue reflejando la actualización como en curso. Dado que la actualización en tiempo de ejecución puede tardar mucho tiempo en finalizar correctamente, no hay ningún tiempo de espera establecido especificado actualmente. Compruebe el estado detallado del clúster y los registros periódicamente para determinar si la actualización está intentando actualizar indefinidamente.

Puede identificar una actualización bloqueada indefinidamente examinando los registros del clúster, el mensaje detallado y el mensaje de estado detallado. Si se da esta condición, verá que el clúster reconcilia continuamente el mismo estado sin avanzar. Compruebe los registros del clúster o el área de trabajo de Log Analytics (LAW) configurada para ver si hay algún fallo o un paso específico que esté causando la falta de progreso.

Identificación de la actualización de equipos sin sistema operativo detenidos o bloqueados

Se proporciona una guía para la identificación de problemas con los nodos de trabajo en Solución de problemas de aprovisionamiento de equipos sin sistema operativo.

Si el error es de hardware, no es preciso volver a ejecutar la actualización

Aunque se haya ha producido un error de hardware durante una actualización, la actualización del runtime continúa, siempre que se cumplan los umbrales establecidos para los nodos de proceso y de administración o control. Una vez que la máquina se corrige o se reemplaza, se aprovisiona con el sistema operativo del runtime de la plataforma actual, que contiene la versión de destino del runtime. Si un bastidor se actualizó antes de un error, se usaría la versión del runtime actualizada cuando se vuelvan a aprovisionar los nodos. Si la especificación del rack no se ha actualizado a la nueva versión del runtime antes del error de hardware, la máquina se aprovisiona con la versión anterior del runtime. La máquina se actualiza junto con el bastidor cuando el bastidor inicia su actualización.

Después de una actualización en tiempo de ejecución, el clúster muestra el estado de aprovisionamiento "fallido"

Durante una actualización en tiempo de ejecución, el clúster entra en un estado de Upgrading. Si se produce un error en la actualización de runtime, el clúster entra en un estado de aprovisionamiento de Failed. Los componentes de infraestructura (por ejemplo, el dispositivo de almacenamiento) pueden provocar errores durante la actualización. En algunos casos, puede ser necesario diagnosticar el fallo con el soporte técnico de Microsoft.

La máquina sin sistema operativo se muestra degradada después de la actualización durante tiempo de ejecución

Determinadas situaciones pueden provocar que un nodo vuelva a un estado Degraded. Este estado se produce si se cumple alguna de las condiciones que se describen en Solucionar errores de estado degradado. El estado degradado significa que el nodo se acordona automáticamente para evitar que se programen nuevas cargas de trabajo en el nodo hasta que se resuelva el problema subyacente.