← Voltar ao Holistic

Bearer token do Kubernetes

O Holistic usa um ServiceAccount de somente leitura para descobrir e monitorar nodes, pods, namespaces, deployments, jobs, cronjobs e events. Não use credenciais de administrador do cluster.

1. Namespace e ServiceAccount

kubectl create namespace holistic-monitor
kubectl create serviceaccount holistic-monitor -n holistic-monitor

2. ClusterRole mínimo (inclui nodes, jobs e cronjobs)

O ClusterRole view padrão não inclui nodes — use o abaixo. Se você já aplicou uma versão antiga, reaplique este manifesto para incluir batch (Jobs/CronJobs) e events.

kubectl apply -f - <<'EOF'
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: holistic-monitor-read
rules:
- apiGroups: [""]
  resources: ["nodes", "pods", "namespaces", "events"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs", "cronjobs"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: holistic-monitor-read
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: holistic-monitor-read
subjects:
- kind: ServiceAccount
  name: holistic-monitor
  namespace: holistic-monitor
EOF

3. Token de longa duração

Em Kubernetes ≥ 1.24, crie um Secret do tipo ServiceAccount token:

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: holistic-monitor-token
  namespace: holistic-monitor
  annotations:
    kubernetes.io/service-account.name: holistic-monitor
type: kubernetes.io/service-account-token
EOF

kubectl get secret holistic-monitor-token -n holistic-monitor \
  -o jsonpath='{.data.token}' | base64 -d; echo

4. URL do API server

kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'; echo

Onde colar no Holistic

Em Clusters, ao criar ou editar o cluster, informe o API server e o Bearer token.
O token é cifrado no navegador antes de sair e fica cifrado em repouso no servidor.
No plano de monitoração do cluster, use Descobrir para escolher namespaces e deployments — as credenciais vêm do Cluster e a listagem roda no agente runner.

Boas práticas

Use só o RBAC mínimo acima; não conceda cluster-admin.
Prefira token via Secret (longa duração) em vez de kubectl create token de curta validade.
Em produção com CA confiável, desmarque “Ignorar verificação TLS”.
Rote o monitoramento e o Descobrir por um host (agente) que alcance a API do cluster.

Troubleshooting — Descobrir

O botão Descobrir enfileira uma tarefa allowlisted no agente runner do cluster (host com agente associado). O servidor Holistic não precisa alcançar o API server (:6443). Se falhar, o Holistic classifica a causa e aponta para a seção abaixo.

Host e agente runner

Sintomas: mensagens pedindo para associar um host, agente offline, timeout aguardando o agente, ou plugin binary not found: k8s.

Em Servidores → Editar (ou ao criar o host), escolha o cluster no campo Cluster — esse host vira o runner do Descobrir.
Se o host mostrar badge update, use Atualizar agente (remoto — sem script). Agentes online aplicam sozinhos em ~30s. Use Token / script só se o agente estiver offline.
O agente nesse host precisa estar online e na versão v1.0.0-rc.6 ou superior (passa a fazer poll de /api/v1/agents/tasks).
Aplique o plano do cluster com a dimensão Kubernetes para instalar o plugin k8s no runner.
O agente precisa alcançar o Holistic (para receber a tarefa) e o API server do cluster (para listar).

API inacessível (rede / timeout)

Sintomas: connection refused, i/o timeout, no such host, dial tcp, network is unreachable, ou página HTML Bad gateway / Error code 502 da Cloudflare no Descobrir.

Confirme a URL em Editar cluster (veja a seção URL do API server).
O agente runner precisa alcançar o endpoint (não o servidor Holistic).
Endereços internos do cluster funcionam se o agente estiver na mesma rede/VPC.
Teste conectividade a partir do host do agente até https://…:6443.
Se o Descobrir mostrar HTML da Cloudflare: o proxy mascarou o corpo do erro. Versões recentes do Holistic devolvem JSON 422 com a causa real.

Falha de TLS / certificado

Sintomas: x509, certificate, unknown authority, erros de TLS.

Em lab ou CA privada, marque Ignorar verificação TLS no Cluster (o agente usa essa flag).
Em produção com CA pública/confiável, desmarque essa opção e use o endpoint HTTPS correto.

Token inválido ou expirado (401)

Sintomas: 401, Unauthorized.

Regenere o token (seção Token de longa duração) e cole de novo em Editar cluster.
Evite tokens curtos de kubectl create token sem duração adequada.
Confirme que o Secret está ligado ao ServiceAccount certo.

Sem permissão RBAC (403)

Sintomas: 403, Forbidden — em list nodes, list jobs, list cronjobs, etc. O ClusterRole view padrão não inclui nodes; versões antigas do manifesto Holistic também omitiam batch.

Aplique (ou reaplique) o ClusterRole e o Binding da seção ClusterRole mínimo.

Verifique:

kubectl auth can-i list nodes --as=system:serviceaccount:holistic-monitor:holistic-monitor
kubectl auth can-i list jobs.batch --as=system:serviceaccount:holistic-monitor:holistic-monitor
kubectl auth can-i list cronjobs.batch --as=system:serviceaccount:holistic-monitor:holistic-monitor