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
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:
- La imagen
webcorre con cualquier UID del grupo 0, que es lo que asignarestricted-v2. Todos los directorios en los que escriben nginx y su entrypoint pertenecen al grupo root y el grupo tiene permiso de escritura. Como root se comporta igual que antes, así que la misma imagen sigue funcionando en Kubernetes estándar y en Docker Compose. - El Deployment
webcorre con su propia ServiceAccount,<release>-web, que no está vinculada a nada, y no monta su token: nginx nunca llama a la API de Kubernetes. Es así desde 2.5.2; de 2.3.0 a 2.5.1 compartía la ServiceAccount del chart. No necesita ninguna SCC aparte derestricted-v2, y una SCC concedida a la ServiceAccount de la API ya no le llega. api.podSecurityContext/api.securityContext, y sus equivalentes paraweb, están disponibles y vacíos por defecto. En OpenShift dejarunAsUsersin definir:restricted-v2asigna un UID del rango del namespace y rechaza un pod que pida uno fuera de él.- El sidecar del conector de Azure de Kobi
(
mcpConnectors.azure.sidecar.enabled, desactivado por defecto) es el único contenedor que fija un UID,1654. En OpenShift añade--set mcpConnectors.azure.sidecar.securityContext.runAsUser=null. - Las conexiones in-cluster y por kubeconfig ya no se cortan a los 25 s. Ese
plazo es un ajuste del agent-proxy, pensado para un agente atascado; ahora
solo se aplica a los clústeres con agent-proxy. Las conexiones directas están
limitadas por Cluster connect timeout (Administration → System → General,
o
KUBEBOLT_CACHE_SYNC_TIMEOUT_SECONDS; 45 s por defecto), y “agent may be stuck” ya no aparece donde no hay agente.
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:
- Renderizar sin acceso al clúster (
helm template, algunas herramientas de GitOps): el chart no puede ver el grupo de API, así que pasa--api-versions security.openshift.io/v1, o define--set podSecurityContext.runAsUser=nullcomo antes. - Mantén la imagen tan nueva como el chart (lo predeterminado: la propia
versión del chart, hoy 1.4.10). El chart 1.4.2 o posterior en OpenShift con
una imagen anterior a 1.4.2 fijada mediante
image.tagno pasa la comprobación derunAsNonRoot, porque el usuario de la imagen antigua no es numérico.
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:
| Ruta | Quién escribe |
|---|---|
/etc/nginx/conf.d | el sed -i del entrypoint, que sustituye API_BACKEND |
/var/cache/nginx | el proceso maestro de nginx al arrancar (client_temp y similares) |
/var/log/nginx | el proceso maestro de nginx, antes de soltar privilegios |
/run | el archivo PID |
Dos teorías plausibles que la evidencia descartó:
- No eran los volúmenes. Los PersistentVolumeClaims no se ven afectados:
restricted-v2aporta unfsGroupdel rango del namespace y el kubelet cambia el propietario del volumen a ese grupo. El PVC de VictoriaMetrics y el PVC/datade la API funcionaron sin tocar nada, y por eso esos dos pods estaban enRunning. - Un
securityContexten el chart no podía arreglarlo, y añadirrunAsUserlo rompe de hecho:restricted-v2usa la estrategiaMustRunAsRange, así que un pod que pide un UID fuera del rango del namespace se rechaza en la admisión. La corrección tenía que ir en la imagen, que es donde la puso 2.3.0.
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 events | sin events | |
|---|---|---|
| Sonda de permisos | 26/31 | 25/31 |
| Cachés de los informers | nunca se sincronizan | sincronizadas ~1.8 s después de la sonda |
| UI | Cluster unreachable | Active (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:
- 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.
- Un informer lento bloquea a todos los demás: es la parte que sigue abierta.
- 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
- Quita
eventsdel ClusterRole. El clúster se levanta de inmediato; el costo es que la pestaña Events y cualquier insight que lea Events se quedan vacíos, y la sonda informa con honestidad de un tipo de recurso menos. - Sube el connect timeout del agent-proxy
(
KUBEBOLT_AGENT_PROXY_CONNECT_TIMEOUT, por defecto60sdesde la 2.6.7 y25santes), o Connect deadline en Agent-proxy resilience, dentro de Administration → Agents & Ingest → Configuration. Funciona, pero es el ajuste equivocado por partida doble: es un ajuste de resiliencia del agent-proxy, y relajarlo debilita la protección para la que existe en los clústeres que sí usan agentes.
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ón | Desde |
|---|---|
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 token | 2.3.0 |
web corre con su propia ServiceAccount (<release>-web), que no está vinculada a nada | 2.5.2 |
podSecurityContext y securityContext opcionales para api / web, vacíos por defecto | 2.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 agente | 2.3.0 |
| Límite de memoria por defecto de la API de 1Gi (solicitud de 128Mi); antes era 256Mi | 2.3.0 |
El chart del agente quita su runAsUser por defecto en OpenShift; el USER de la imagen del agente es numérico | agente 1.4.2 |
| Un informer lento ya no retiene a los demás | abierto |
Referencias
- Managing security context constraints: la estrategia
MustRunAsRangey el rango de UID del namespace - Pod Security Standards in OpenShift 4.11+