KubeBolt docs
ENES GitHub

Guías de despliegue

Guía de Azure AKS

Despliega KubeBolt en Azure Kubernetes Service, con ingress de AGIC y Azure Monitor managed Prometheus.

En esta página
  1. Instalación rápida
  2. Autenticación
  3. Ingress
  4. Azure Monitor managed Prometheus
  5. Solución de problemas

En KubeBolt Cloud lo único que corre en tu clúster de AKS es el agente, y el asistente Add cluster imprime su comando. De esta página, la parte que puede aplicarse a tu caso es Azure Monitor managed Prometheus; el resto es para ejecutar KubeBolt por tu cuenta.

Instalación rápida

El chart funciona de serie en AKS: 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).

AKS activa Metrics Server por defecto. Confírmalo con kubectl get apiservice v1beta1.metrics.k8s.io.

Autenticación

KubeBolt no necesita permisos de Azure para mostrar y operar el clúster, porque todo eso pasa por la API de Kubernetes. Workload Identity solo importa en un caso: leer Azure Monitor managed Prometheus con el agente, más abajo.

El conector de Azure de Kobi (open source) tampoco usa Workload Identity: lee Azure a través del Azure MCP Server, un segundo contenedor en el pod de la API (mcpConnectors.azure.sidecar.enabled) que inicia sesión como una entidad de servicio de solo lectura guardada en un Secret.

Azure RBAC para Kubernetes. Si el clúster autoriza mediante Azure RBAC en lugar del RBAC nativo de Kubernetes, el ClusterRole del chart sigue aplicándose: los dos conviven, y la ServiceAccount del chart usa el RBAC nativo de Kubernetes.

Red. Tanto kubenet como Azure CNI funcionan sin configuración adicional.

Ingress

Con Application Gateway Ingress Controller:

helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --namespace kubebolt --create-namespace \
  --set ingress.enabled=true \
  --set ingress.className=azure-application-gateway \
  --set ingress.hosts[0].host=kubebolt.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=Prefix

Con otro controlador, cambia la clase: nginx para ingress-nginx, o webapprouting.kubernetes.azure.com para el complemento de enrutamiento de aplicaciones de AKS:

  --set ingress.className=nginx

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.

Azure Monitor managed Prometheus

Si tus métricas ya están en un Azure Monitor Workspace, despliega el agente opcional en modo promread y un Deployment aparte, de una sola réplica, lee las familias de métricas directamente del workspace, autenticándose con Azure Workload Identity: sin un segundo pipeline de scraping y sin ningún secreto que rotar.

El clúster necesita tres cosas activadas: --enable-oidc-issuer, --enable-workload-identity y --enable-azure-monitor-metrics (que aprovisiona el workspace y los scrapers ama-metrics, node-exporter y kube-state-metrics incluidos). Cada una se puede activar más tarde con az aks update. Compruébalas:

RG=my-aks-resource-group
CLUSTER=my-aks-cluster

az aks show -g "$RG" -n "$CLUSTER" --query oidcIssuerProfile.issuerUrl -o tsv                    # una URL https
az aks show -g "$RG" -n "$CLUSTER" --query securityProfile.workloadIdentity.enabled -o tsv       # true
az aks show -g "$RG" -n "$CLUSTER" --query azureMonitorProfile.metrics.enabled -o tsv            # true

1. Localiza el endpoint

Los endpoints dependen del workspace y de la región, y llevan un sufijo aleatorio que Azure elige al aprovisionar, así que búscalo en lugar de adivinarlo:

# El primer workspace de la suscripción; elige el tuyo si hay varios
AMW_ID=$(az resource list \
  --resource-type "Microsoft.Monitor/accounts" \
  --query "[0].id" -o tsv)

AMW_ENDPOINT=$(az resource show --ids $AMW_ID \
  --query "properties.metrics.prometheusQueryEndpoint" -o tsv)

TOKEN=$(az account get-access-token \
  --resource "https://prometheus.monitor.azure.com" \
  --query accessToken -o tsv)

curl -s -H "Authorization: Bearer $TOKEN" \
  "${AMW_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 identidad administrada y la credencial federada

De las tres nubes, Azure es la que más piezas hay que conectar, porque cada una vive en un plano de control distinto:

LOCATION=$(az aks show -g "$RG" -n "$CLUSTER" --query location -o tsv)
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
UAMI=kubebolt-promread

# 1. La identidad administrada asignada por el usuario.
az identity create --name "$UAMI" --resource-group "$RG" --location "$LOCATION"

UAMI_CLIENT_ID=$(az identity show -g "$RG" -n "$UAMI" --query clientId -o tsv)
UAMI_PRINCIPAL_ID=$(az identity show -g "$RG" -n "$UAMI" --query principalId -o tsv)

# 2. Acceso de solo lectura al workspace.
az role assignment create \
  --assignee-object-id "$UAMI_PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Monitoring Data Reader" \
  --scope "$AMW_ID"

# 3. Confiar en el emisor OIDC del clúster para esa ServiceAccount.
OIDC_ISSUER=$(az aks show -g "$RG" -n "$CLUSTER" \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name "${UAMI}-fed" \
  --identity-name "$UAMI" \
  --resource-group "$RG" \
  --issuer "$OIDC_ISSUER" \
  --subject "system:serviceaccount:${NAMESPACE}:${KSA}" \
  --audience api://AzureADTokenExchange

El sujeto (subject) debe nombrar el namespace y la ServiceAccount del agente; si lo instalas en otro sitio, cambia NAMESPACE antes de ejecutar esto. Verifica antes de seguir: si falta el rol, lo verás más adelante como 403 Forbidden, y si el sujeto no coincide, como 401 Unauthorized:

az role assignment list --assignee "$UAMI_PRINCIPAL_ID" --scope "$AMW_ID" \
  --query "[].roleDefinitionName" -o tsv          # → Monitoring Data Reader

az identity federated-credential show \
  --name "${UAMI}-fed" --identity-name "$UAMI" -g "$RG" \
  --query "{subject:subject,issuer:issuer,audiences:audiences}"

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-aks-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="${AMW_ENDPOINT}" \
  --set agent.promRead.auth.mode=azureWorkloadIdentity \
  --set serviceAccount.annotations."azure\.workload\.identity/client-id"="${UAMI_CLIENT_ID}" \
  --set-string podLabels."azure\.workload\.identity/use"="true"

Detalles en los que es fácil tropezar:

El asistente Add cluster construye la mayor parte de este comando: en sus opciones avanzadas, elige Read from existing Prometheus en Prometheus integration, con autenticación Azure Workload Identity, y añade la anotación azure.workload.identity/client-id de la ServiceAccount. No tiene ningún campo para etiquetas del pod, así que añade tú la línea --set-string podLabels…. 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|promread init failed|channel registered|matcher failed"

Lo que debes ver es promread enabled … auth_mode=azureWorkloadIdentity y channel registered. promread matcher failed con 401 apunta al sujeto de la credencial federada; con 403, a la asignación de rol. 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.

Errores al descargar imágenes con un ACR privado. Permite ghcr.io (y docker.io para VictoriaMetrics), o replica las imágenes. Los tags de abajo son los que descargan el chart 2.7.0 y el chart del agente 1.4.10; ajústalos a los charts que instales:

ACR=myacr
az acr import --name $ACR --source ghcr.io/clm-cloud-solutions/kubebolt/api:2.7.0 --image kubebolt/api:2.7.0
az acr import --name $ACR --source ghcr.io/clm-cloud-solutions/kubebolt/web:2.7.0 --image kubebolt/web:2.7.0
az acr import --name $ACR --source docker.io/victoriametrics/victoria-metrics:v1.156.0-scratch \
  --image victoriametrics/victoria-metrics:v1.156.0-scratch
az acr import --name $ACR --source ghcr.io/clm-cloud-solutions/kubebolt/agent:1.4.10 --image kubebolt/agent:1.4.10

Luego apunta los charts a ellas: api.image.repository=$ACR.azurecr.io/kubebolt/api, web.image.repository, metrics.storage.embedded.image.repository y, en el chart del agente, image.repository.

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.