Guías de despliegue
Guía de Amazon EKS
Ejecuta KubeBolt contra Amazon EKS: dentro del clúster con Helm, desde tu máquina o con el agente, incluida la exposición con ALB, IRSA y la lectura de Amazon Managed Prometheus.
En esta página
En KubeBolt Cloud, lo único que se ejecuta en tu clúster de EKS es el agente, y el asistente Add cluster imprime su comando. De esta página te aplican Metrics Server y Amazon Managed Prometheus; el resto es para quien ejecuta KubeBolt por su cuenta.
Instalación rápida
El chart crea dos PVC (10 GiB para VictoriaMetrics, 1 GiB para los datos
propios de KubeBolt) en la StorageClass por defecto. En EKS eso requiere
el complemento Amazon EBS CSI driver (y su rol de IAM), y una
StorageClass marcada como (default): los clústeres creados en Kubernetes
1.30 o posterior ya no marcan gp2 como predeterminada. Compruébalo con
kubectl get storageclass. Sin ambas cosas, los PVC se quedan en Pending y
los pods nunca arrancan. Para indicar una clase concreta, define
metrics.storage.embedded.persistence.storageClass y
auth.persistence.storageClass.
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).
Autenticación
Cómo se autentica KubeBolt en EKS depende de dónde se ejecute:
- En el clúster (Helm): la API usa su propia ServiceAccount y el ClusterRole del chart. No intervienen credenciales de AWS.
- En tu máquina (Homebrew, krew, binario único): usa tu kubeconfig igual
que
kubectl, así que el execaws eks get-tokende un kubeconfig de EKS necesita la AWS CLI y un perfil activo o una sesión SSO en el host. - Imagen de contenedor único: la imagen incluye
aws-cli. Monta tu kubeconfig y tu configuración de AWS en el home del usuario no root:
docker run -p 3000:3000 \
-v ~/.kube/config:/kubeconfig:ro -e KUBECONFIG=/kubeconfig \
-v ~/.aws:/home/kubebolt/.aws:ro -e AWS_PROFILE=my-profile \
-v kubebolt-data:/data \
ghcr.io/clm-cloud-solutions/kubebolt:latest
Importar un kubeconfig tampoco ayuda. Una instalación con Helm rechaza
Import kubeconfig directamente (cannot add clusters in in-cluster mode),
y la imagen de la API que ejecuta Compose no tiene la AWS CLI, así que un
kubeconfig de EKS importado allí falla en el mismo aws eks get-token.
Conecta esos clústeres con el agente.
IRSA o EKS Pod Identity nunca hacen falta para leer el clúster. Entran en juego en dos sitios:
-
La ServiceAccount del chart
kubebolt(kubeboltpara una release llamadakubebolt): la identidad de AWS de la que parte el conector de AWS de Kobi en una instalación autoalojada. DefinemcpConnectors.aws.principalArncon el mismo rol para que la política de confianza que imprime la guía de configuración del conector lo incluya:helm upgrade --install kubebolt \ oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \ --namespace kubebolt --create-namespace \ --set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=arn:aws:iam::123456789012:role/kubebolt-api \ --set mcpConnectors.aws.principalArn=arn:aws:iam::123456789012:role/kubebolt-apiCon Pod Identity, quita la anotación y asocia el rol a la ServiceAccount
kubebolten el namespacekubebolt. En Cloud, el conector asume tu rol desde el lado de KubeBolt; no hay que instalar nada en el clúster. -
La ServiceAccount del agente, que firma las consultas a Amazon Managed Prometheus (más abajo).
Docker Compose
El archivo de Compose monta ~/.aws para generar el token de EKS, pero la
imagen de la API que construye no incluye la AWS CLI, así que un
kubeconfig que ejecuta aws eks get-token falla dentro del contenedor.
Ejecuta KubeBolt en el host (Homebrew o el binario), usa la imagen de
contenedor único de arriba o dale a Compose un kubeconfig con un token
estático (por ejemplo, un token de ServiceAccount). Los pasos de Compose en
sí:
git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt
kubectl config use-context my-eks-cluster
./deploy/docker-kubeconfig.sh
cd deploy && docker compose up -d
El script auxiliar no es un paso propio de EKS: Compose monta
/tmp/docker-kubeconfig, así que se ejecuta en toda instalación. Con un
endpoint enrutable no reescribe nada. La referencia completa de Compose está
en Métodos de instalación.
Helm con ALB Ingress
Esto necesita el AWS Load Balancer Controller
y el almacenamiento de Instalación rápida. Los Services del
chart son ClusterIP, así que el ALB tiene que apuntar a las IP de los pods
(target-type: ip; el valor por defecto del controlador, instance, necesita
un NodePort). Su esquema por defecto es internal. Las anotaciones son más
fáciles de poner en un archivo de values que con --set:
cat > kubebolt-alb.yaml <<'EOF'
ingress:
enabled: true
className: alb
annotations:
alb.ingress.kubernetes.io/scheme: internet-facing # o internal
alb.ingress.kubernetes.io/target-type: ip
# HTTPS con un certificado de ACM:
# alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
# alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:REGION:ACCOUNT:certificate/ID
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-alb.yaml
kubectl -n kubebolt get ingress kubebolt # ADDRESS es el nombre DNS del ALB
Apunta kubebolt.example.com a esa dirección. El Ingress da acceso solo a la
interfaz y a la API: enruta al Service web, que hace de proxy de /api y
/ws. Los agentes de otros clústeres se conectan al puerto gRPC
(kubebolt-agent-ingest, 9090), que expones por separado: un Service
LoadBalancer (agentIngest.service.type) o un proxy compatible con gRPC, con
agentIngest.tls.* para TLS. Consulta
El agente no llega al backend.
KubeBolt en sí no necesita ningún DaemonSet, así que los modos kubeconfig e
in-cluster funcionan en EKS Fargate. Los pods de Fargate no pueden montar EBS,
así que apunta los dos PVC a una StorageClass respaldada por EFS
(metrics.storage.embedded.persistence.storageClass,
auth.persistence.storageClass), o ejecuta KubeBolt en un grupo de nodos
gestionado (managed node group). El DaemonSet del agente opcional no se
ejecuta en nodos Fargate; su Deployment promread sí.
Metrics Server
EKS no siempre incluye Metrics Server. Sin él, KubeBolt sigue mostrando todos los recursos, eventos e insights; solo las barras de CPU/memoria en vivo muestran “no data”. Compruébalo, e instálalo si falta el API service:
kubectl get apiservice v1beta1.metrics.k8s.io
# Como complemento (add-on) de EKS
aws eks create-addon --cluster-name my-eks-cluster --addon-name metrics-server
# O desde el manifiesto upstream
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
Amazon Managed Prometheus (AMP)
Si tus métricas ya viven en AMP, no necesitas un segundo pipeline: despliega
el agente con agent.promRead.enabled=true y un Deployment
aparte de una sola réplica lee las familias de kube-state-metrics, de nodo y
de salud de targets (y las de OpenCost, con agent.promRead.cost.enabled=true)
directamente de tu workspace, firmando cada consulta con AWS SigV4. AMP solo
guarda lo que algo le envía con remote_write; el agente lo vuelve a leer.
1. Encuentra el endpoint
Los endpoints de AMP son por workspace y por región:
REGION=us-east-1
# El primer workspace de la región; elige el tuyo si hay varios
WORKSPACE_ID=$(aws amp list-workspaces --region "$REGION" \
--query 'workspaces[0].workspaceId' --output text)
AMP_ENDPOINT=$(aws amp describe-workspace --workspace-id "$WORKSPACE_ID" \
--region "$REGION" --query 'workspace.prometheusEndpoint' --output text)
echo "$AMP_ENDPOINT" # https://aps-workspaces.<region>.amazonaws.com/workspaces/<id>/
Para probarlo desde tu máquina, awscurl
firma la petición: awscurl --service aps --region "$REGION" "${AMP_ENDPOINT}api/v1/query?query=up"
debería devolver "status":"success". Un resultado vacío es normal en un
workspace al que todavía no se envía nada.
2. Crea el rol de IAM (IRSA)
Crea un rol que pueda asumir la ServiceAccount del agente, con la política
administrada por AWS AmazonPrometheusQueryAccess: solo consultas, sin
ingesta ni administración:
CLUSTER=my-eks-cluster
CLUSTER_REGION=$REGION # cámbialo si el clúster y el workspace están en regiones distintas
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
# IRSA necesita el proveedor OIDC del clúster en IAM (no hace nada si ya está)
eksctl utils associate-iam-oidc-provider --cluster "$CLUSTER" --region "$CLUSTER_REGION" --approve
eksctl create iamserviceaccount \
--cluster "$CLUSTER" --region "$CLUSTER_REGION" \
--namespace "$NAMESPACE" --name "$KSA" \
--role-name kubebolt-promread --role-only \
--attach-policy-arn arn:aws:iam::aws:policy/AmazonPrometheusQueryAccess \
--approve
ROLE_ARN=$(aws iam get-role --role-name kubebolt-promread --query 'Role.Arn' --output text)
--role-only crea solo el rol; el chart crea la ServiceAccount y la anota en
el siguiente paso. El agente firma con la cadena de credenciales por defecto
del AWS SDK, así que una asociación de EKS Pod Identity para la misma
ServiceAccount también funciona; en ese caso, omite la anotación.
3. Instala el agente en modo promread
El Secret kubebolt-agent-token contiene 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: el host:port gRPC de tu backend para agentes
CLUSTER_NAME=my-eks-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="$AMP_ENDPOINT" \
--set agent.promRead.auth.mode=awsSigV4 \
--set agent.promRead.auth.awsRegion="$REGION" \
--set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"="$ROLE_ARN"
Detalles en los que mucha gente tropieza:
agent.promRead.auth.awsRegiones obligatorio conawsSigV4: el chart se niega a renderizar sin él, y una región distinta de la del workspace hace fallar todas las consultas conInvalidSignatureException.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 (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. La barra final no molesta.scrape.enabled=falsemantiene desactivado el sidecarvmagentincluido (él y promread son mutuamente excluyentes). Los collectors de kubelet del DaemonSet siguen funcionando y complementan AMP con las métricas propias de KubeBolt.- Si lo que envía a AMP incluye node-exporter, añade
--set agent.deferNodeStress=true, o el panel Load average dibujará cada serie dos veces. - Salida: el agente necesita
sts.<region>.amazonaws.comyaps-workspaces.<region>.amazonaws.comen el 443, además de tu backend.
El asistente Add cluster también construye este comando: en sus opciones avanzadas, elige Read from existing Prometheus en Prometheus integration, la autenticación AWS SigV4, y añade el ARN del rol como anotación de la ServiceAccount. Consulta Conectar clústeres y Métricas.
4. Verifica
kubectl -n "$NAMESPACE" get pods -l kubebolt.dev/role=promread # 1 pod, 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 buscas es promread enabled … auth_mode=awsSigV4 y channel registered.
promread matcher failed con AccessDenied significa que el rol no llega al
pod (anotación, política de confianza o política); con
InvalidSignatureException, la región es incorrecta. Si no aparece ninguna
línea channel registered, el backend rechazó el agente: revisa el Secret y
auth.mode. En KubeBolt, la tarjeta Prometheus (read) en Administration →
Agents & Ingest → Integrations pasa a Installed tras el primer sondeo.