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.

Problemas de instalación

Las siguientes secciones contienen consejos para solucionar problemas o recibir asistencia con instalaciones fallidas.

Inicio de sesión en el instalador (un sistema operativo en vivo)

Los usuarios pueden presionar la combinación de teclas CTRL + ALT + F2 para cambiar a otro TTY e iniciar sesión con las siguientes credenciales:

Usuario: rancher
Contraseña: rancher

Cumpliendo con los requisitos de hardware

Verifica que tu hardware cumpla con los requisitos mínimos para completar la instalación.

Atascado en `Loading images. This may take a few minutes…`

Debido a que el sistema no tiene una ruta predeterminada, tu instalador puede quedar "atascado" en este estado. Puedes comprobar el estado de tu ruta ejecutando el siguiente comando:

$ ip route
default via 10.10.0.10 dev mgmt-br proto dhcp        <-- Does a default route exist?
10.10.0.0/24 dev mgmt-br proto kernel scope link src 10.10.0.15

Verifica que tu servidor DHCP ofrezca una opción de ruta predeterminada. Adjuntar contenido de /run/cos/target/rke2.log también es útil.

Para más información, consulta Configuración del servidor DHCP.

Modificando el token del clúster en nodos de agente

Cuando un nodo de agente no puede unirse al clúster, puede estar relacionado con que el token del clúster no sea idéntico al token del nodo del servidor. Para confirmar el problema, conéctate a tu nodo de agente (es decir, con SSH) y revisa el registro del servicio rancherd con el siguiente comando:

sudo journalctl -b -u rancherd

Si la configuración del token del clúster en el nodo de agente no coincide con el token del nodo del servidor, encontrarás varias entradas del siguiente mensaje:

msg="Bootstrapping Rancher (v2.7.5/v1.25.9+rke2r1)"
msg="failed to bootstrap system, will retry: generating plan: response 502: 502  Bad Gateway getting cacerts: <html>\r\n<head><title>502 Bad Gateway</title></head>\r\n<body>\r\n<center><h1>502 Bad Gateway</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n"

Ten en cuenta que la versión Rancher y la dirección IP dependen de tu entorno y pueden diferir del mensaje anterior.

Para solucionar el problema, necesitas actualizar el valor del token en el archivo de configuración rancherd /etc/rancher/rancherd/config.yaml.

Por ejemplo, si la configuración del token del clúster en el nodo del servidor es ThisIsTheCorrectOne, actualizarás el valor del token de la siguiente manera:

token: 'ThisIsTheCorrectOne'

Para asegurar que el cambio sea persistente después de reiniciar, actualiza el valor token del archivo de configuración del sistema operativo /oem/90_custom.yaml:

name: Harvester Configuration
stages:
  ...
  initramfs:
  - commands:
    - ...
    files:
    - path: /etc/rancher/rancherd/config.yaml
      permissions: 384
      owner: 0
      group: 0
      content: |
        server: https://$cluster-vip:443
        role: agent
        token: "ThisIsTheCorrectOne"
        kubernetesVersion: v1.25.9+rke2r1
        rancherVersion: v2.7.5
        rancherInstallerImage: rancher/system-agent-installer-rancher:v2.7.5
        labels:
         - harvesterhci.io/managed=true
        extraConfig:
          disable:
          - rke2-snapshot-controller
          - rke2-snapshot-controller-crd
          - rke2-snapshot-validation-webhook
      encoding: ""
      ownerstring: ""

Para ver cuál es el valor actual del token del clúster, inicia sesión en tu nodo del servidor (es decir, con SSH) y busca en el archivo /etc/rancher/rancherd/config.yaml. Por ejemplo, puedes ejecutar el siguiente comando para mostrar únicamente el valor del token:

$ sudo yq eval .token /etc/rancher/rancherd/config.yaml

Comprobando el estado de los componentes

Antes de comprobar el estado de los componentes SUSE Virtualization, obtén una copia del archivo kubeconfig del clúster utilizando cualquiera de los siguientes métodos:

En la SUSE Virtualization interfaz de usuario, ve a la pantalla Soporte y luego haz clic en Descargar KubeConfig.
Ejecuta los siguientes comandos en cualquiera de los nodos de gestión:
```
$ sudo su
$ cat /etc/rancher/rke2/rke2.yaml
```

Después de obtener una copia del archivo kubeconfig, ejecuta el siguiente script contra el clúster para comprobar la disponibilidad de cada componente.

Componentes de SUSE Virtualization

  #!/bin/bash
  cluster_ready() {
    namespaces=("cattle-system" "kube-system" "harvester-system" "longhorn-system")
    for ns in "${namespaces[@]}"; do
      pod_statuses=($(kubectl -n "${ns}" get pods \
        --field-selector=status.phase!=Succeeded \
        -ojsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name},{.status.conditions[?(@.type=="Ready")].status}{"\n"}{end}'))
      for status in "${pod_statuses[@]}"; do
        name=$(echo "${status}" | cut -d ',' -f1)
        ready=$(echo "${status}" | cut -d ',' -f2)
        if [ "${ready}" != "True" ]; then
          echo "pod ${name} is not ready"
          false
          return
        fi
      done
    done
  }
  if cluster_ready; then
    echo "cluster is ready"
  else
    echo "cluster is not ready"
  fi

API
```
$ curl -fk https://<VIP>/version
```
Debes reemplazar <VIP> con el VIP actual, que es el valor de kube-vip.io/requestedIP.

Recopilación de información de resolución de problemas

Por favor, incluye la siguiente información en un informe de errores al reportar una instalación fallida:

Una captura de pantalla de la instalación fallida.
Información del sistema y registros.

Por favor, sigue la guía en [Logging into the Installer (a live OS)] para iniciar sesión. Y ejecuta el comando para generar un tarball que contenga información de resolución de problemas:
```
  supportconfig -k -c
```
Los mensajes de salida del comando contienen la ruta del tarball generado. Por ejemplo, la ruta es /var/loq/scc_aaa_220520_1021 804d65d-c9ba-4c54-b12d-859631f892c5.txz en el siguiente ejemplo:

Una instalación fallida de arranque PXE genera automáticamente un tarball si el campo install.debug está configurado en true en el archivo de configuración.

Comprobando el estado de los charts

SUSE Virtualization utiliza los siguientes CRDs de charts:

HelmChart: Mantiene los charts de RKE2.
- rke2-runtimeclasses
- rke2-multus
- rke2-metrics-server
- rke2-ingress-nginx
- rke2-coredns
- rke2-cannal
ManagedChart: Gestiona Rancher los charts y SUSE Virtualization.
- rancher-monitoring-crd
- rancher-logging-crd
- kubeovn-operator-crd
- harvester-crd
- harvester

Puedes usar helm list -A el comando para recuperar una lista de charts instalados.

Ejemplo de salida:

NAME                                           NAMESPACE                          REVISION    UPDATED                                    STATUS      CHART                                                                                       APP VERSION
fleet                                          cattle-fleet-system                4           2025-09-24 09:07:10.801764068 +0000 UTC    deployed    fleet-107.0.0+up0.13.0                                                                      0.13.0
fleet-agent-local                              cattle-fleet-local-system          1           2025-09-24 08:59:28.686781982 +0000 UTC    deployed    fleet-agent-local-v0.0.0+s-d4f65a6f642cca930c78e6e2f0d3f9bbb7d3ba47cf1cce34ac3d6b8770ce5
fleet-crd                                      cattle-fleet-system                1           2025-09-24 08:58:28.396419747 +0000 UTC    deployed    fleet-crd-107.0.0+up0.13.0                                                                  0.13.0
harvester                                      harvester-system                   1           2025-09-24 08:59:37.718646669 +0000 UTC    deployed    harvester-0.0.0-master-ac070598                                                             master-ac070598
harvester-crd                                  harvester-system                   1           2025-09-24 08:59:35.341316526 +0000 UTC    deployed    harvester-crd-0.0.0-master-ac070598                                                         master-ac070598
kubeovn-operator-crd                           kube-system                        1           2025-09-24 08:59:34.783356576 +0000 UTC    deployed    kubeovn-operator-crd-1.13.13                                                                v1.13.13
mcc-local-managed-system-upgrade-controller    cattle-system                      1           2025-09-24 08:59:10.656784284 +0000 UTC    deployed    system-upgrade-controller-107.0.0                                                           v0.16.0
rancher                                        cattle-system                      1           2025-09-24 08:57:20.690330683 +0000 UTC    deployed    rancher-2.12.0                                                                              8815e66-dirty
rancher-logging-crd                            cattle-logging-system              1           2025-09-24 08:59:36.262080367 +0000 UTC    deployed    rancher-logging-crd-107.0.1+up4.10.0-rancher.10
rancher-monitoring-crd                         cattle-monitoring-system           1           2025-09-24 08:59:35.287099045 +0000 UTC    deployed    rancher-monitoring-crd-107.1.0+up69.8.2-rancher.15
rancher-provisioning-capi                      cattle-provisioning-capi-system    1           2025-09-24 08:59:00.561162307 +0000 UTC    deployed    rancher-provisioning-capi-107.0.0+up0.8.0                                                   1.10.2
rancher-webhook                                cattle-system                      2           2025-09-24 09:02:38.774660489 +0000 UTC    deployed    rancher-webhook-107.0.0+up0.8.0                                                             0.8.0
rke2-canal                                     kube-system                        1           2025-09-24 08:57:25.248839867 +0000 UTC    deployed    rke2-canal-v3.30.2-build2025071100                                                          v3.30.2
rke2-coredns                                   kube-system                        1           2025-09-24 08:57:25.341016864 +0000 UTC    deployed    rke2-coredns-1.42.302                                                                       1.12.2
rke2-ingress-nginx                             kube-system                        3           2025-09-24 09:01:31.331647555 +0000 UTC    deployed    rke2-ingress-nginx-4.12.401                                                                 1.12.4
rke2-metrics-server                            kube-system                        1           2025-09-24 08:57:42.162046899 +0000 UTC    deployed    rke2-metrics-server-3.12.203                                                                0.7.2
rke2-multus                                    kube-system                        1           2025-09-24 08:57:25.341560394 +0000 UTC    deployed    rke2-multus-v4.2.106                                                                        4.2.1
rke2-runtimeclasses                            kube-system                        1           2025-09-24 08:57:40.137168056 +0000 UTC    deployed    rke2-runtimeclasses-0.1.000                                                                 0.1.0

HelmChart CRD

HelmChart Se instalan elementos mediante trabajos. Puedes determinar el nombre y el estado de cada trabajo ejecutando el siguiente comando en el nodo SUSE Virtualization:

$ kubectl get helmcharts -A -o jsonpath='{range .items[*]}{"Namespace: "}{.metadata.namespace}{"\nName: "}{.metadata.name}{"\nStatus:\n"}{range .status.conditions[*]}{"  - Type: "}{.type}{"\n    Status: "}{.status}{"\n    Reason: "}{.reason}{"\n    Message: "}{.message}{"\n"}{end}{"JobName: "}{.status.jobName}{"\n\n"}{end}'

Ejemplo de salida:

Namespace: kube-system
Name: rke2-canal
Status:
  - Type: JobCreated
    Status: True
    Reason: Job created
    Message: Applying HelmChart using Job kube-system/helm-install-rke2-canal
  - Type: Failed
    Status: False
    Reason:
    Message:
JobName: helm-install-rke2-canal
Namespace: kube-system
Name: rke2-coredns
Status:
  - Type: JobCreated
    Status: True
    Reason: Job created
    Message: Applying HelmChart using Job kube-system/helm-install-rke2-coredns
  - Type: Failed
    Status: False
    Reason:
    Message:
JobName: helm-install-rke2-coredns
Namespace: kube-system
Name: rke2-ingress-nginx
Status:
  - Type: JobCreated
    Status: True
    Reason: Job created
    Message: Applying HelmChart using Job kube-system/helm-install-rke2-ingress-nginx
  - Type: Failed
    Status: False
    Reason:
    Message:
JobName: helm-install-rke2-ingress-nginx
Namespace: kube-system
Name: rke2-metrics-server
Status:
  - Type: JobCreated
    Status: True
    Reason: Job created
    Message: Applying HelmChart using Job kube-system/helm-install-rke2-metrics-server
  - Type: Failed
    Status: False
    Reason:
    Message:
JobName: helm-install-rke2-metrics-server
Namespace: kube-system
Name: rke2-multus
Status:
  - Type: JobCreated
    Status: True
    Reason: Job created
    Message: Applying HelmChart using Job kube-system/helm-install-rke2-multus
  - Type: Failed
    Status: False
    Reason:
    Message:
JobName: helm-install-rke2-multus
Namespace: kube-system
Name: rke2-runtimeclasses
Status:
  - Type: JobCreated
    Status: True
    Reason: Job created
    Message: Applying HelmChart using Job kube-system/helm-install-rke2-runtimeclasses
  - Type: Failed
    Status: False
    Reason:
    Message:
JobName: helm-install-rke2-runtimeclasses

Puedes usar la información de las siguientes maneras:

Determina la causa de un trabajo fallido: Verifica los valores Reason y Message de la condición Failed.
Vuelve a ejecutar un trabajo: Elimina el campo Status para ese trabajo específico del HelmChart CRD. El controlador despliega un nuevo trabajo.

ManagedChart CRD

Rancher utiliza SUSE® Rancher Prime: Continuous Delivery para instalar charts en clusters objetivo. SUSE Virtualization tiene solo un cluster objetivo (fleet-local/local).

SUSE® Rancher Prime: Continuous Delivery despliega un agente en cada cluster objetivo a través de helm install, por lo que puedes encontrar el chart fleet-agent-local usando el comando helm list -A. El cluster.fleet.cattle.io CRD contiene el estado del agente.

apiVersion: fleet.cattle.io/v1alpha1
kind: Cluster
metadata:
  name: local
  namespace: fleet-local
spec:
  agentAffinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - preference:
          matchExpressions:
          - key: fleet.cattle.io/agent
            operator: In
            values:
            - "true"
        weight: 1
  agentNamespace: cattle-fleet-local-system
  clientID: xd8cgpm2gq5w25qf46r8ml6qxvhsg858g64s5k7wj5h947vs5sxbwd
  kubeConfigSecret: local-kubeconfig
  kubeConfigSecretNamespace: fleet-local
  redeployAgentGeneration: 1
status:
  agent:
    lastSeen: "2025-09-01T07:09:28Z"
    namespace: cattle-fleet-local-system
  agentAffinityHash: f50425c0999a8e18c2d104cdb8cb063762763f232f538b5a7c8bdb61
  agentDeployedGeneration: 1
  agentMigrated: true
  agentNamespaceMigrated: true
  agentTLSMode: system-store
  apiServerCAHash: 158866807fdf372a1f1946bb72d0fbcdd66e0e63c4799f9d4df0e18b
  apiServerURL: https://10.53.0.1:443
  cattleNamespaceMigrated: true
  conditions:
  - lastUpdateTime: "2025-08-28T04:43:02Z"
    status: "True"
    type: Processed
  - lastUpdateTime: "2025-08-28T10:08:31Z"
    status: "True"
    type: Imported
  - lastUpdateTime: "2025-08-28T10:08:30Z"
    status: "True"
    type: Reconciled
  - lastUpdateTime: "2025-08-28T10:09:30Z"
    status: "True"
    type: Ready

Rancher convierte el ManagedChart CRD en un recurso Bundle con un prefijo mcc-. El SUSE® Rancher Prime: Continuous Delivery agente observa los recursos Bundle y los despliega en el cluster objetivo. El BundleDeployment recurso contiene el estado de la ampliación.

El SUSE® Rancher Prime: Continuous Delivery controlador no envía datos al agente. En su lugar, el agente consulta Bundle los datos de recursos del clúster en el que está instalado el SUSE® Rancher Prime: Continuous Delivery controlador. En SUSE Virtualization, el SUSE® Rancher Prime: Continuous Delivery controlador y el agente están en el mismo clúster, por lo que los problemas de red no son una preocupación.

$ kubectl get bundledeployments -A -o jsonpath='{range .items[*]}{"Namespace: "}{.metadata.namespace}{"\nName: "}{.metadata.name}{"\nStatus:\n"}{range .status.conditions[*]}{"  - Type: "}{.type}{"\n    Status: "}{.status}{"\n    Reason: "}{.reason}{"\n    Message: "}{.message}{"\n"}{end}{"\n"}{end}'
Namespace: cluster-fleet-local-local-1a3d67d0a899
Name: fleet-agent-local
Status:
  - Type: Installed
    Status: True
    Reason:
    Message:
  - Type: Deployed
    Status: True
    Reason:
    Message:
  - Type: Ready
    Status: True
    Reason:
    Message:
  - Type: Monitored
    Status: True
    Reason:
    Message:
Namespace: cluster-fleet-local-local-1a3d67d0a899
Name: mcc-harvester
Status:
  - Type: Installed
    Status: True
    Reason:
    Message:
  - Type: Deployed
    Status: True
    Reason:
    Message:
  - Type: Ready
    Status: True
    Reason:
    Message:
  - Type: Monitored
    Status: True
    Reason:
    Message:
Namespace: cluster-fleet-local-local-1a3d67d0a899
Name: mcc-harvester-crd
Status:
  - Type: Installed
    Status: True
    Reason:
    Message:
  - Type: Deployed
    Status: True
    Reason:
    Message:
  - Type: Ready
    Status: True
    Reason:
    Message:
  - Type: Monitored
    Status: True
    Reason:
    Message:
Namespace: cluster-fleet-local-local-1a3d67d0a899
Name: mcc-kubeovn-operator-crd
Status:
  - Type: Installed
    Status: True
    Reason:
    Message:
  - Type: Deployed
    Status: True
    Reason:
    Message:
  - Type: Ready
    Status: True
    Reason:
    Message:
  - Type: Monitored
    Status: True
    Reason:
    Message:
Namespace: cluster-fleet-local-local-1a3d67d0a899
Name: mcc-rancher-logging-crd
Status:
  - Type: Installed
    Status: True
    Reason:
    Message:
  - Type: Deployed
    Status: True
    Reason:
    Message:
  - Type: Ready
    Status: True
    Reason:
    Message:
  - Type: Monitored
    Status: True
    Reason:
    Message:
Namespace: cluster-fleet-local-local-1a3d67d0a899
Name: mcc-rancher-monitoring-crd
Status:
  - Type: Installed
    Status: True
    Reason:
    Message:
  - Type: Deployed
    Status: True
    Reason:
    Message:
  - Type: Ready
    Status: True
    Reason:
    Message:
  - Type: Monitored
    Status: True
    Reason:
    Message:

Si cambias la imagen de ampliación del harvester-system/harvester, el agente SUSE® Rancher Prime: Continuous Delivery detecta el cambio y actualiza el estado correspondiente en el recurso BundleDeployment.

Ejemplo:

status:
  appliedDeploymentID: s-89f9ce3f33c069befb4ebdceaa103af7b71db0e70a39760cb6653366964e5:1cd9188211e318033f89b77acf7b996
e5bb3d9a25319528c47dc052528056f78
  conditions:
  - lastUpdateTime: "2025-08-28T04:44:18Z"
    status: "True"
    type: Installed
  - lastUpdateTime: "2025-08-28T04:44:18Z"
    status: "True"
    type: Deployed
  - lastUpdateTime: "2025-09-01T07:40:28Z"
    message: deployment.apps harvester-system/harvester modified {"spec":{"template":{"spec":{"containers":[{"env":[{"
name":"HARVESTER_SERVER_HTTPS_PORT","value":"8443"},{"name":"HARVESTER_DEBUG","value":"false"},{"name":"HARVESTER_SERV
ER_HTTP_PORT","value":"0"},{"name":"HCI_MODE","value":"true"},{"name":"RANCHER_EMBEDDED","value":"true"},{"name":"HARV
ESTER_SUPPORT_BUNDLE_IMAGE_DEFAULT_VALUE","value":"{\"repository\":\"rancher/support-bundle-kit\",\"tag\":\"master-hea
d\",\"imagePullPolicy\":\"IfNotPresent\"}"},{"name":"NAMESPACE","valueFrom":{"fieldRef":{"apiVersion":"v1","fieldPath"
:"metadata.namespace"}}}],"image":"frankyang/harvester:fix-renovate-head","imagePullPolicy":"IfNotPresent","name":"api
server","ports":[{"containerPort":8443,"name":"https","protocol":"TCP"},{"containerPort":6060,"name":"profile","protoc
ol":"TCP"}],"resources":{"requests":{"cpu":"250m","memory":"256Mi"}},"securityContext":{"appArmorProfile":{"type":"Unc
onfined"},"capabilities":{"add":["SYS_ADMIN"]}},"terminationMessagePath":"/dev/termination-log","terminationMessagePol
icy":"File"}]}}}}

La consola muestra `Setting up Harvester` después de la instalación del día 0.

Descripción del problema

Después de una instalación exitosa, la consola muestra persistentemente Setting up Harvester. Mientras que la mayoría de las operaciones de UI y CLI permanecen sin afectar, los intentos de iniciar una actualización de versión están bloqueados.

La siguiente información se muestra después de ejecutar el comando kubectl get managedchart -n fleet-local harvester -oyaml:

...
status:
  conditions:
  - lastUpdateTime: "2025-10-22T08:01:18Z"
    message: 'NotReady(1) [Cluster fleet-local/local]; daemonset.apps harvester-system/harvester-network-controller
      modified {"spec":{"template":{"spec":{"containers":[{"args":["agent"],"command":["harvester-network-controller"],
      "env":[{"name":"NODENAME","valueFrom":{"fieldRef":{"apiVersion":"v1","fieldPath":"spec.nodeName"}}},
      {"name":"NAMESPACE","valueFrom":{"fieldRef":{"apiVersion":"v1","fieldPath":"metadata.namespace"}}}],
      "image":"rancher/harvester-network-controller:master-head","imagePullPolicy":"IfNotPresent","name":"harvester-network",
      "resources":{"limits":{"cpu":"100m","memory":"128Mi"},"requests":{"cpu":"10m","memory":"64Mi"}},
      "securityContext":{"privileged":true},"terminationMessagePath":"/dev/termination-log","terminationMessagePolicy":"File",
      "volumeMounts":[{"mountPath":"/dev","name":"dev"},{"mountPath":"/lib/modules","name":"modules"}]}]}}}};'
    status: "False"
    type: Ready

Causa raíz

La consola ejecuta el siguiente comando para determinar si el estado del harvester ManagedChart (en el espacio de nombres fleet-local) es Ready.

cmd := exec.Command("/bin/sh", "-c", kubectl -n fleet-local get ManagedChart harvester -o jsonpath='{.status.conditions}' |
jq 'map(select(.type == "Ready" and .status == "True")) | length')

El ManagedChart CRD es utilizado por SUSE® Rancher Prime: Continuous Delivery para gestionar recursos a través de GitOps. Si alguno de esos recursos se modifica directamente, ManagedChart registra y señala las desviaciones. En el ejemplo anterior, el error ocurrió porque se aplicó directamente una etiqueta de imagen personalizada al harvester-system/harvester-network-controller DaemonSet.

Para recuperar la lista completa de ManagedChart recursos, ejecuta el comando kubectl get bundle -n fleet-local mcc-harvester -oyaml.

apiVersion: fleet.cattle.io/v1alpha1
kind: Bundle
metadata:
  name: mcc-harvester
  namespace: fleet-local
spec:
  resources:
  - content: H4s...===
    encoding: base64+gz
    charts/harvester-network-controller/templates/daemonset.yaml
  - content: ...

Solución

Puedes realizar cualquiera de las siguientes acciones:

Revertir los cambios directos realizados en los recursos afectados.
Actualizar el ManagedChart CRD con la configuración personalizada deseada utilizando kubectl edit managedchart -n fleet-local harvester.

Problema relacionado

#8655