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
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:
podLabels."azure\.workload\.identity/use"es lo que hace que el webhook de Workload Identity inyecte el token en el pod. Pásalo con--set-string(el valor de una etiqueta tiene que ser la cadena"true"). Sin él, el pod de promread termina al arrancar conpromread init failed.backendUrles un destino de conexión gRPC,host:port, sin esquema. Con un proxy que termina TLS delante del backend,tls.enabled=truetambién es obligatorio: si lo omites, parece que el host es inalcanzable. 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 los colectores de kubelet del DaemonSet.- El chart difiere automáticamente los colectores del propio agente de red
de nodo y de NodeStress (carga + PSI) cuando
agent.promRead.auth.mode=azureWorkloadIdentity, porqueama-metrics-nodede Azure ya hace scraping de node-exporter. No necesitasagent.deferNodeStress=trueniagent.deferNodeNetwork=truea mano; quítalos si los arrastras de un archivo de values antiguo.
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.