KubeBolt docs
ENES GitHub

Guías de despliegue

OpenShift

Desde KubeBolt 2.3.0 y el agente 1.4.2, KubeBolt se instala bajo la SCC restricted-v2 por defecto de OpenShift sin ajustes adicionales. Cómo instalarlo y exponerlo, qué cambió, qué sigue abierto y las soluciones provisionales para versiones anteriores.

En esta página
  1. Instalar en 2.3.0 y posteriores
  2. Lo que sigue abierto
  3. Lo que se reportó y por qué pasó
  4. Antes de 2.3.0: soluciones provisionales
  5. Reproducirlo sin un clúster de OpenShift
  6. Correcciones y en qué versión salieron
  7. Referencias

Estado: corregido en KubeBolt 2.3.0 y el agente 1.4.2, pendiente de volver a verificar en OpenShift. Los problemas se reportaron en KubeBolt 1.23.1 / OpenShift 4.20 / Kubernetes 1.33.6 (2026-08-16): el contenedor web no arrancaba bajo la SCC restricted-v2 por defecto, el chart del agente fijaba un UID que la SCC rechaza y, en un clúster con mucha actividad, la conexión in-cluster agotaba el tiempo de espera y culpaba a un agente que no existe. Una parte sigue abierta: consulta Lo que sigue abierto. En versiones anteriores a 2.3.0 / agente 1.4.2, usa las soluciones provisionales.

Instalar en 2.3.0 y posteriores

Una instalación estándar funciona bajo restricted-v2 sin conceder ninguna SCC y sin parches:

helm install kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --namespace kubebolt --create-namespace --wait

oc -n kubebolt get pods   # api, web y victoriametrics en Running

oc -n kubebolt get secret kubebolt-admin-password \
  -o jsonpath='{.data.password}' | base64 -d ; echo

El chart no incluye ninguna Route. Crea una delante del Service kubebolt, o define ingress.enabled=true y deja que el router de OpenShift convierta el Ingress en una Route:

oc -n kubebolt create route edge kubebolt --service=kubebolt
oc -n kubebolt get route kubebolt -o jsonpath='{.spec.host}{"\n"}'

La Route expone la UI y la API (el Service web hace de proxy de /api y /ws). Los agentes de otros clústeres se conectan al puerto gRPC, kubebolt-agent-ingest en el 9090, que expones por separado. En KubeBolt Cloud solo el agente corre en tu clúster, y la parte que aplica es El agente, más abajo.

Qué cambió para que una instalación estándar funcione bajo restricted-v2:

Dimensiona la API según sus Events

La API guarda en caché cada recurso que observa, Events incluidos. En un clúster de prueba con 161 MB de Events, la API ocupaba ~253 MiB una vez sincronizada, justo en el antiguo límite por defecto de 256Mi, así que nunca terminaba su primera sincronización y su liveness probe la reiniciaba cada ~80 s. Desde 2.3.0 el límite de memoria por defecto de la API es 1Gi (solicitud de 128Mi). En un clúster con Events todavía más grandes, súbelo:

helm upgrade kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  -n kubebolt --reset-then-reuse-values \
  --set api.resources.limits.memory=2Gi

Sin --version, esto también pasa la release al chart más reciente; añade --version con la versión que usas para quedarte en ella. Si fijas api.resources en tu propio archivo de values, revisa su límite de memoria al actualizar: tu valor prevalece sobre el valor por defecto.

El agente

Desde el agente 1.4.2, el chart detecta OpenShift (un clúster que sirve security.openshift.io/v1) y quita su runAsUser: 65532 por defecto, con lo que deja el UID en manos de la SCC. El USER de la imagen ahora es numérico (65532:65532, el mismo UID que antes), así que runAsNonRoot: true se sigue verificando. Si defines tú un runAsUser, se respeta.

Dos casos requieren un ajuste manual:

Nada más en el agente necesita privilegios elevados: el DaemonSet no declara hostPath, hostNetwork ni hostPID, y readOnlyRootFilesystem: true es compatible con restricted-v2 tal cual.

Lo que sigue abierto

Un informer lento todavía retiene a los demás. El conector espera a toda la shared informer factory, así que en un clúster con una colección de Events muy grande, los Nodes y Pods que estaban listos en menos de dos segundos no se sirven hasta que los Events terminan de sincronizarse. Desde 2.3.0 esa espera dura hasta el Cluster connect timeout en lugar de cortarse a los 25 s, así que el clúster sí llega a levantarse, solo que tan tarde como su informer más lento. Si los Events de tu clúster tardan más que ese timeout, sube Cluster connect timeout en lugar del ajuste del agent-proxy.

La solución en seguimiento: acotar el informer de Events (un limit, un field selector o una ventana más corta), sincronizarlo de forma asíncrona o esperar por informer, para que uno lento degrade su propia pestaña en lugar de todo el contexto.

Lo que se reportó y por qué pasó

El resto de esta página documenta los problemas originales. Explica las soluciones provisionales de abajo y es útil si usas una versión anterior.

El contenedor web se reiniciaba en bucle

Una instalación estándar dejaba el contenedor web en CrashLoopBackOff mientras todo lo demás funcionaba:

NAME                            READY   STATUS             RESTARTS
kubebolt-api-...                1/1     Running            0
kubebolt-victoriametrics-0      1/1     Running            0
kubebolt-web-...                0/1     CrashLoopBackOff   7
/docker-entrypoint.sh: Launching /docker-entrypoint.d/40-api-backend.sh
sed: can't create temp file '/etc/nginx/conf.d/default.confXXXXXX': Permission denied

restricted-v2 asigna a cada pod un UID aleatorio del rango del namespace (openshift.io/sa.scc.uid-range) y siempre lo pone en el GID 0. La imagen web era entonces un nginx:1.27-alpine sin modificar, donde todos los directorios en los que escribe nginx eran root:root 0755: el grupo podía leerlos, pero no escribir en ellos. Se denegaba el acceso a cuatro rutas:

RutaQuién escribe
/etc/nginx/conf.del sed -i del entrypoint, que sustituye API_BACKEND
/var/cache/nginxel proceso maestro de nginx al arrancar (client_temp y similares)
/var/log/nginxel proceso maestro de nginx, antes de soltar privilegios
/runel archivo PID

Dos teorías plausibles que la evidencia descartó:

El contexto in-cluster agotaba el tiempo de espera

Independiente del problema de la SCC. La API detectó su configuración in-cluster, llegó al API server y terminó la sonda de permisos; luego, unos 25 segundos después:

connect timed out after 25s for context in-cluster — agent may be stuck

La UI mostraba Cluster unreachable aunque nada era inalcanzable. Quien lo reportó quitó solo events de la regla get/list/watch del ClusterRole kubebolt y reinició:

con eventssin events
Sonda de permisos26/3125/31
Cachés de los informersnunca se sincronizansincronizadas ~1.8 s después de la sonda
UICluster unreachableActive (5/5 nodos, 67/67 deployments, 77 namespaces)

En ese clúster oc get events -A tardaba ~32 s y GET /api/v1/events devolvía ~138 MiB, mientras que Nodes, Pods y Deployments respondían en menos de un segundo cada uno. Se sumaron tres cosas:

  1. Los Events crecen sin límite, a diferencia de todo lo demás. Todo lo demás está acotado por lo que está desplegado; los Events, por lo que ocurre.
  2. Un informer lento bloquea a todos los demás: es la parte que sigue abierta.
  3. El plazo externo era más corto que el presupuesto interno. El plazo de conexión del agent-proxy (25 s) también regía la conexión in-cluster directa, mientras que el presupuesto de sincronización de la caché era de 45 s, así que una sincronización que avanzaba con normalidad hacia los 30 s se cortaba a los 25. La 2.3.0 quitó ese plazo de las conexiones directas.

Antes de 2.3.0: soluciones provisionales

Solo para versiones anteriores a KubeBolt 2.3.0 / agente 1.4.2. Al actualizar, ya no hace falta ninguna.

web: concede la SCC anyuid

La vía más rápida. Necesita cluster-admin. El pod corre como root, exactamente igual que en Kubernetes estándar.

oc adm policy add-scc-to-user anyuid -z default -n kubebolt
oc rollout restart deployment/kubebolt-web -n kubebolt

-z default es lo correcto para esas versiones: el Deployment web no definía serviceAccountName, así que corría con la ServiceAccount default del namespace. Esto debilita la postura de seguridad del namespace; prefiere la siguiente opción si tu equipo de plataforma no va a conceder anyuid.

web: mantén restricted-v2

Un initContainer renderiza la configuración de nginx en un emptyDir, el contenedor principal se salta los scripts del entrypoint y las tres rutas de escritura restantes pasan a ser montajes emptyDir, con permiso de escritura porque se les aplica el fsGroup de la SCC.

oc patch deployment/kubebolt-web -n kubebolt --type=strategic -p '
spec:
  template:
    spec:
      initContainers:
        - name: render-config
          image: ghcr.io/clm-cloud-solutions/kubebolt/web:2.2.1
          command: ["/bin/sh", "-c"]
          args:
            - sed "s|api:8080|${API_BACKEND}|g" /etc/nginx/conf.d/default.conf > /mnt/conf/default.conf
          env:
            - name: API_BACKEND
              value: kubebolt-api:8080
          volumeMounts:
            - name: nginx-conf
              mountPath: /mnt/conf
      containers:
        - name: web
          command: ["nginx", "-g", "daemon off;"]
          volumeMounts:
            - name: nginx-conf
              mountPath: /etc/nginx/conf.d
            - name: nginx-cache
              mountPath: /var/cache/nginx
            - name: nginx-log
              mountPath: /var/log/nginx
            - name: nginx-run
              mountPath: /run
      volumes:
        - name: nginx-conf
          emptyDir: {}
        - name: nginx-cache
          emptyDir: {}
        - name: nginx-log
          emptyDir: {}
        - name: nginx-run
          emptyDir: {}
'

Fija la imagen del initContainer al tag que instalaste y define API_BACKEND como <release-name>-api:8080.

Un helm upgrade revierte este parche. Vuelve a aplicarlo después de cada actualización, o mantenlo en una kustomization de post-render.

Agente 1.4.1 y anteriores: quita el UID fijado

helm upgrade --install kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt \
  --set podSecurityContext.runAsUser=null \
  --set backendUrl=<host:port>

runAsNonRoot: true se sigue cumpliendo, porque el UID que asigna OpenShift nunca es 0. --set-json 'podSecurityContext={}' no funciona: Helm fusiona los mapas, así que un mapa vacío deja el UID fijado en su sitio. Solo =null elimina la clave.

El timeout in-cluster

Reproducirlo sin un clúster de OpenShift

Ejecuta la imagen como lo haría restricted-v2 (sirve cualquier UID siempre que no esté en /etc/passwd y el GID sea 0, que es todo lo que OpenShift hace distinto):

docker run --rm --user 1000700000:0 --entrypoint /bin/sh \
  ghcr.io/clm-cloud-solutions/kubebolt/web:2.3.0 -c '
    sed -i "s|api:8080|x:1|g" /etc/nginx/conf.d/default.conf
    ls -ld /etc/nginx/conf.d /var/cache/nginx /var/log/nginx /run
  '

En 2.3.0 el sed funciona y las cuatro rutas pertenecen al grupo 0, con permiso de escritura para el grupo. En 2.2.1 y anteriores el mismo comando falla con Permission denied.

Correcciones y en qué versión salieron

CorrecciónDesde
La imagen web tolera un UID arbitrario (chgrp 0 + chmod g=u en las cuatro rutas)2.3.0
El Deployment web corre con la ServiceAccount del chart, sin montar el token2.3.0
web corre con su propia ServiceAccount (<release>-web), que no está vinculada a nada2.5.2
podSecurityContext y securityContext opcionales para api / web, vacíos por defecto2.3.0
El plazo de conexión del agent-proxy ya no se aplica a las conexiones in-cluster / kubeconfig, y “agent may be stuck” no aparece donde no hay agente2.3.0
Límite de memoria por defecto de la API de 1Gi (solicitud de 128Mi); antes era 256Mi2.3.0
El chart del agente quita su runAsUser por defecto en OpenShift; el USER de la imagen del agente es numéricoagente 1.4.2
Un informer lento ya no retiene a los demásabierto

Referencias