KubeBolt docs
ENES GitHub

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
  1. Instalación rápida
  2. Autenticación
  3. Ingress con GCE
  4. GKE Autopilot
  5. Google Managed Prometheus
  6. Solución de problemas

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:

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.