KubeBolt docs
ENES GitHub

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
  1. Instalación rápida
  2. Autenticación
  3. Docker Compose
  4. Helm con ALB Ingress
  5. Metrics Server
  6. Amazon Managed Prometheus (AMP)

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:

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:

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:

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.