Guías de despliegue
Guía de Google GKE
Despliega KubeBolt en Google Kubernetes Engine, con Ingress de GCE, Autopilot y Google Managed Prometheus.
En esta página
En KubeBolt Cloud lo único que corre en tu clúster de GKE es el agente, y el asistente Add cluster imprime su comando. De esta página, la parte que puede aplicarse a tu caso es Google Managed Prometheus; el resto es para ejecutar KubeBolt por tu cuenta.
Instalación rápida
El chart funciona de serie en GKE: crea una ServiceAccount y un ClusterRole que dan a KubeBolt acceso de lectura al clúster, además de los verbos de escritura que usan sus acciones (exec, port-forward, scale, restart, edit, delete).
helm install kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace --wait
kubectl -n kubebolt get secret kubebolt-admin-password \
-o jsonpath='{.data.password}' | base64 -d ; echo
kubectl -n kubebolt port-forward svc/kubebolt 3000:80
Abre http://localhost:3000 e inicia sesión como admin con la contraseña
impresa (otras formas de obtenerla: Inicio rápido).
GKE incluye Metrics Server, así que las barras de CPU y memoria en vivo funcionan desde el primer momento.
Autenticación
KubeBolt en sí no necesita permisos de GCP: habla con la API de Kubernetes y con nada más. Workload Identity solo importa cuando la ServiceAccount también tiene que llegar a un servicio de Google Cloud, lo que en KubeBolt se reduce a un caso: leer Google Managed Prometheus con el agente, más abajo.
Ingress con GCE
El controlador de Ingress de GKE ignora ingressClassName: toma un Ingress
por la anotación kubernetes.io/ingress.class, y un Ingress que define
cualquier ingressClassName sin la anotación se queda sin balanceador de carga.
Así que deja ingress.className vacío (el API server rechaza un Ingress que
define ambos) y define la anotación, algo más fácil en un archivo de values que
con --set:
cat > kubebolt-gce.yaml <<'EOF'
ingress:
enabled: true
className: ""
annotations:
kubernetes.io/ingress.class: gce # gce-internal para un balanceador de carga interno
hosts:
- host: kubebolt.example.com
paths:
- path: /
pathType: Prefix
EOF
helm upgrade --install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace -f kubebolt-gce.yaml
kubectl -n kubebolt get ingress kubebolt # ADDRESS es la IP del balanceador de carga
gce-internal también necesita una subred de solo proxy en la región del
clúster. Los Services del chart son ClusterIP, que GKE sirve mediante
balanceo de carga nativo de contenedores (activo por defecto en los clústeres
nativos de la VPC en la mayoría de los casos); donde no lo está, anota el
Service con cloud.google.com/neg='{"ingress": true}'. En un clúster basado en
rutas, añade --set service.type=NodePort en su lugar.
Aumenta el tiempo de espera del backend. Por defecto, el balanceador de
carga espera 30 s a que llegue una respuesta completa, y Kobi envía cada
contestación en streaming dentro de una única respuesta larga, así que las que
tardan más se cortan. El chart no tiene ningún valor para anotaciones del
Service; asocia tú mismo un BackendConfig al Service kubebolt, como se
muestra abajo. Al actualizar, Helm deja en su sitio una anotación que no
gestiona.
kubectl -n kubebolt apply -f - <<'EOF'
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: kubebolt
spec:
timeoutSec: 600
EOF
kubectl -n kubebolt annotate service kubebolt \
cloud.google.com/backend-config='{"default": "kubebolt"}'
El Ingress 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: consulta
El agente no llega al backend.
En lugar de un Ingress, el chart puede crear un Gateway de Gateway API con un
HTTPRoute para la UI y un GRPCRoute para los agentes
(gatewayAPI.enabled=true, excluyente con ingress). Sus valores por defecto
apuntan a Envoy Gateway (GatewayClass eg, más una ClientTrafficPolicy de
Envoy); con otro controlador, define gatewayAPI.gatewayClassName y
gatewayAPI.forceHTTP1=false. Pasa también web.enabled=true, o la ruta se
salta la UI web y apunta solo a la API. El README del chart
tiene el comando completo.
GKE Autopilot
El chart kubebolt no necesita contenedores privilegiados, así que se instala
tal cual en clústeres Autopilot. Autopilot puede subir las solicitudes por
defecto del chart, que son pequeñas, hasta sus mínimos; es lo esperado.
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace
Donde Autopilot no permite ráfagas (bursting), fija los límites iguales a las
solicitudes. La API guarda en caché cada recurso que observa, Events incluidos,
y por eso su límite de memoria por defecto es 1Gi frente a una solicitud de
128Mi; en un clúster así, sube api.resources.requests.memory a lo que el
clúster necesite.
Google Managed Prometheus
Si tus métricas ya están en GMP, no necesitas un segundo pipeline de scraping. Despliega el agente opcional en modo promread y un Deployment aparte, de una sola réplica, consulta directamente la API compatible con Prometheus de GMP, autenticándose con GCP IAM mediante Workload Identity (sin archivo de clave de cuenta de servicio).
1. Localiza el endpoint
El endpoint de consulta de GMP es global por proyecto; el segmento
location/global es fijo y no hay ninguna región que pasar:
PROJECT_ID=$(gcloud config get-value project)
GMP_ENDPOINT="https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/location/global/prometheus"
TOKEN=$(gcloud auth print-access-token)
curl -s -H "Authorization: Bearer $TOKEN" \
"${GMP_ENDPOINT}/api/v1/query?query=count(up)"
Una respuesta con status: success indica que el endpoint y la autenticación
con token bearer funcionan.
2. Crea la cuenta de servicio de Google y vincúlala
GSA=kubebolt-promread
NAMESPACE=kubebolt-system # donde va el agente; el valor por defecto del asistente Add cluster
KSA=kubebolt-agent # la ServiceAccount del chart para una release llamada kubebolt-agent
gcloud iam service-accounts create $GSA \
--display-name="KubeBolt agent — reads from Google Managed Prometheus"
# monitoring.viewer es de solo lectura: sin ingesta ni administración.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${GSA}@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/monitoring.viewer" \
--condition=None
# La ServiceAccount de Kubernetes aún no existe: helm la crea en el
# paso 3. GKE resuelve este binding de forma diferida cuando aparece.
gcloud iam service-accounts add-iam-policy-binding \
${GSA}@${PROJECT_ID}.iam.gserviceaccount.com \
--role="roles/iam.workloadIdentityUser" \
--member="serviceAccount:${PROJECT_ID}.svc.id.goog[${NAMESPACE}/${KSA}]"
El namespace y la ServiceAccount de ese miembro deben ser los del agente. Si lo
instalas en otro sitio, cambia NAMESPACE antes de ejecutar esto.
Workload Identity tiene que estar activado en las dos capas en un clúster
Standard (Autopilot siempre lo tiene). Activarlo a nivel de clúster
(--workload-pool) no basta: cada grupo de nodos que ejecute el agente
también necesita --workload-metadata=GKE_METADATA. Sin eso, el pod hereda en
silencio la cuenta de servicio de Compute Engine del nodo y recibes
403 PERMISSION_DENIED on monitoring.timeSeries.list aunque el binding de
arriba sea correcto. Comprueba las dos capas con los comandos de abajo.
CLUSTER=my-gke-cluster
LOCATION=us-central1 # la región o zona del clúster
gcloud container clusters describe $CLUSTER --location=$LOCATION \
--format='value(workloadIdentityConfig.workloadPool)' # PROJECT_ID.svc.id.goog
gcloud container node-pools list --cluster=$CLUSTER --location=$LOCATION \
--format='table(name,config.workloadMetadataConfig.mode)' # GKE_METADATA en cada uno
3. Instala el agente en modo promread
El Secret kubebolt-agent-token lleva el token de ingesta (Administration →
Agents & Ingest → Agent Tokens, o el asistente), bajo la clave token:
BACKEND_URL=agent.kubebolt.io:443 # KubeBolt Cloud; autoalojado: tu host:port gRPC para agentes
CLUSTER_NAME=my-gke-cluster
INGEST_TOKEN='paste-the-token-here'
kubectl create namespace "$NAMESPACE" --dry-run=client -o yaml | kubectl apply -f -
kubectl -n "$NAMESPACE" create secret generic kubebolt-agent-token \
--from-literal=token="$INGEST_TOKEN" --dry-run=client -o yaml | kubectl apply -f -
helm upgrade --install kubebolt-agent \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
--namespace "$NAMESPACE" \
--set backendUrl="$BACKEND_URL" --set tls.enabled=true \
--set cluster.name="$CLUSTER_NAME" \
--set auth.mode=ingest-token \
--set auth.ingestToken.existingSecret=kubebolt-agent-token \
--set scrape.enabled=false \
--set agent.promRead.enabled=true \
--set agent.promRead.url="${GMP_ENDPOINT}" \
--set agent.promRead.auth.mode=gcpIam \
--set serviceAccount.annotations."iam\.gke\.io/gcp-service-account"="${GSA}@${PROJECT_ID}.iam.gserviceaccount.com"
Detalles en los que es fácil tropezar:
backendUrles un destino de conexión gRPC,host:port, sin esquema. Para un agente en el mismo clúster que un backend autoalojado, usa el Service interno del clúster (kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090) sin TLS.agent.promRead.urles el endpoint base: el agente añade/api/v1/query_rangepor su cuenta.scrape.enabled=falsemantiene apagado el sidecarvmagentincluido (él y promread son mutuamente excluyentes). No desactiva los colectores de kubelet del DaemonSet, que siguen complementando GMP con las métricas canónicas de KubeBolt.- Los matchers por defecto usan nombres de métrica explícitos en lugar de una
regex sobre
__name__, porque GMP rechaza los selectores{__name__=~"…"}. Si los sustituyes, mantén una lista explícita de nombres. - No pongas
agent.deferNodeStress=truecon GMP. La recolección gestionada de GMP no hace scraping de node-exporter, así que el colector propio del agente es la única fuente denode_load1/5/15y de las series de presión. Diferirlo deja vacío el panel Load average. (Ese flag es la opción correcta en Azure, no aquí.)
El asistente Add cluster también construye este comando: en sus opciones
avanzadas, elige Read from existing Prometheus en Prometheus integration,
con autenticación GCP IAM, y añade la anotación
iam.gke.io/gcp-service-account de la ServiceAccount. Consulta
Conectar clústeres y Métricas.
4. Verifica
kubectl -n "$NAMESPACE" get pods -l kubebolt.dev/role=promread # 1 pod, en Running
kubectl -n "$NAMESPACE" get lease kubebolt-promread # HOLDER es ese pod
kubectl -n "$NAMESPACE" logs -l kubebolt.dev/role=promread --tail=50 \
| grep -E "promread enabled|channel registered|matcher failed"
Lo que debes ver es promread enabled … auth_mode=gcpIam y
channel registered. promread matcher failed con 403 PERMISSION_DENIED
significa que Workload Identity no llega al pod (revisa las dos capas de
arriba); un 400 que menciona __name__ significa que un matcher
personalizado usó una regex. En KubeBolt, la tarjeta Prometheus (read) de
Administration → Agents & Ingest → Integrations pasa a Installed tras el
primer sondeo.
Solución de problemas
Pod de la API en CrashLoopBackOff. Revisa kubectl -n kubebolt logs -l app.kubernetes.io/component=api.
La causa habitual es que falta un ClusterRoleBinding; compruébalo con
kubectl get clusterrolebinding | grep kubebolt.
Binary Authorization bloquea las imágenes. Añade una exención para
ghcr.io/clm-cloud-solutions/kubebolt/*, o crea certificaciones (attestations)
para las imágenes con tu propia política.
403 en algunos recursos. Es lo esperado, y está contemplado: KubeBolt se degrada de forma controlada. Los recursos restringidos aparecen atenuados en la barra lateral, tras un banner “Limited access”. Consulta RBAC y permisos.