Kubernetes Agent

Colete dados dos seus clusters Kubernetes e abra chamados automaticamente no OpsScript

O Kubernetes Agent é um agente que roda dentro do seu cluster Kubernetes, coleta dados das integrações que você configura no OpsScript e envia esses dados para a plataforma, onde alertas e chamados são criados automaticamente.

Visão geral

O agente é instalado no cluster via Helm e se registra no OpsScript usando as credenciais geradas no marketplace de integrações. A partir daí ele:

Coleta dados das integrações configuradas (por exemplo, um índice do Elasticsearch) e, para cada novo registro encontrado, abre um chamado no OpsScript por meio de uma política de alerta.
Reporta o inventário do cluster automaticamente (nome, versão do Kubernetes, nodes e status), sem qualquer configuração adicional.
Recarrega a configuração das integrações a quente: mudanças feitas na interface do OpsScript são aplicadas pelo agente sem necessidade de redeploy.

A configuração das integrações vive no OpsScript; o agente apenas as executa. Você pode instalar um agente por cluster e gerenciar todos eles pela mesma tela.

O Kubernetes Agent é um recurso dos planos Pro e Enterprise. Se o seu plano atual não o inclui, o card aparece bloqueado no marketplace de integrações com a opção de fazer upgrade.

Conectar no OpsScript e criar um agente

Toda a configuração começa no marketplace de integrações. Conectar a integração provisiona o workspace do agente na sua organização.

Conecte a integração

Acesse Integrações, localize o card Kubernetes Agent (seção Automação) e abra-o. Na tela da integração, clique em Conectar.

Ao conectar, o OpsScript provisiona automaticamente, em nome da sua organização, um workspace do Kubernetes Agent, que registra os agentes instalados nos seus clusters.

A política de alerta usada como destino dos chamados não é criada neste momento: ela é criada automaticamente para cada integração que você configurar (uma política por integração, visível em Integrações → Alertas) — cada novo registro coletado abre um chamado por ela.

Crie um agente

Na aba Agentes, clique em Novo agente, informe uma Descrição (ex.: cluster de produção us-east-1) e confirme em Criar agente.

Crie um agente por cluster. A descrição serve apenas para você identificar o agente na lista.

Guarde as credenciais

Após a criação, o OpsScript exibe as credenciais AGENT_ID e AGENT_TOKEN. Copie ambas — você vai usá-las na instalação via Helm.

O AGENT_TOKEN é exibido uma única vez, no momento da criação do agente. Guarde-o em local seguro (um gestor de segredos). Se perdê-lo, remova o agente e crie um novo para gerar credenciais novas.

Assim que o agente iniciar no cluster e estabelecer o primeiro contato, o status muda para Online na aba Agentes. A tela também exibe indicadores de agentes instalados, online e offline.

Instalar o agente com Helm

O agente é distribuído como um chart Helm no repositório da CloudScript. O método recomendado é criar antes um Secret com as credenciais e referenciá-lo na instalação — assim o token não fica registrado no histórico do Helm nem em arquivos de values.

Adicione o repositório de charts:

helm repo add cloudscript https://charts.cloudscript.com.br
helm repo update

Método recomendado: Secret existente

Crie o namespace e o Secret com as credenciais do agente e instale o chart referenciando esse Secret:

kubectl create namespace opsscript-agent

kubectl -n opsscript-agent create secret generic opsscript-agent-credentials \
  --from-literal=AGENT_ID=<agent-id> \
  --from-literal=AGENT_TOKEN=<agent-token>

helm install opsscript-agent cloudscript/opsscript-agent \
  --namespace opsscript-agent \
  --set credentials.existingSecret=opsscript-agent-credentials

O Secret deve conter as chaves AGENT_TOKEN (obrigatória) e AGENT_ID (opcional; quando presente, dispensa config.agentId). Em ambientes GitOps, gerencie esse Secret pelo seu fluxo habitual (por exemplo, External Secrets) em vez de criá-lo manualmente.

Alternativa rápida: token nos values

Para um teste rápido, é possível passar o token diretamente e deixar o chart criar o Secret:

helm install opsscript-agent cloudscript/opsscript-agent \
  --namespace opsscript-agent --create-namespace \
  --set config.agentId=<agent-id> \
  --set credentials.agentToken=<agent-token>

Nesse modo o token acaba no histórico do Helm e em eventuais arquivos de values. Não versione o token em repositórios (GitOps ou não) — prefira o método com credentials.existingSecret.

O agente roda como uma instância única (replicaCount: 1), como contêiner não-root com filesystem somente leitura, e recebe uma ClusterRole somente leitura e de privilégio mínimo para coletar o inventário do cluster. Ele não tem acesso ao conteúdo de Secrets do seu cluster. O parâmetro opcional config.clusterName define o nome do cluster exibido no card do agente (aba Agentes), facilitando a identificação quando você tem vários agentes; o nome do cluster no inventário é detectado automaticamente pelo próprio agente.

Integrações disponíveis e como configurá-las

As integrações são configuradas por agente, na aba Integrações da tela do Kubernetes Agent. Clique em Nova integração dentro do bloco do agente desejado e escolha o tipo.

Elasticsearch Index

Monitora um índice do Elasticsearch e abre um chamado para cada novo documento gravado nele. Campos do formulário:

Campo	Obrigatório	Descrição
Descrição	Sim	Identificação da integração (ex.: `alertas do índice de produção`).
URL do Elasticsearch	Sim	URL pública ou o service interno do cluster onde o agente roda (ex.: `https://es.example.com:9200`).
Índice	Sim	Nome exato do índice a monitorar. Não aceita wildcards ou patterns (`*`, `?`).
Campo de data/hora	Não	Campo usado para detectar documentos novos. Vazio usa `@timestamp`. Informe outro (ex.: `timestamp`) se o seu conector gravar em campo diferente.
API key	Sim	Chave de API do Elasticsearch (valor base64). Fica armazenada criptografada e é usada apenas pelo agente para consultar o índice.
Frequência	Sim	Com que frequência o agente consulta o índice: a cada 1, 5, 10, 15, 30 minutos ou 1 hora. O modo Avançado libera um cron com segundos (6 campos, ex.: `0 /5 * * *`).

Ao informar o índice, o formulário gera automaticamente uma policy de privilégios (Control security privileges) pronta para colar no Kibana em Stack Management → Security → API Keys. Ela concede somente leitura no índice informado, seguindo o princípio de privilégio mínimo.

A API key é emitida com leitura restrita ao índice exato informado. Se você alterar o índice de uma integração existente, a chave antiga passa a receber 403 — gere uma nova API key com a policy atualizada e cole-a na edição.

As integrações da aba suportam edição e remoção. Cada integração exibe um atalho para a política de alerta associada, onde os chamados são abertos.

Hoje a interface expõe apenas o tipo Elasticsearch Index para configuração. O chart do agente também traz um servidor de webhooks (por exemplo, para Alertmanager), mas ele ainda não é configurável pela interface do OpsScript — não o documentamos como integração disponível até que o fluxo esteja exposto na UI.

Inventário do cluster

Independentemente das integrações configuradas, o agente reporta o inventário do cluster automaticamente — por padrão, a cada 10 minutos. Os dados aparecem na aba Kubernetes da tela do Kubernetes Agent, agrupados por agente:

Nome do cluster (o agente infere o provedor pelo prefixo — EKS, GKE ou AKS — quando disponível). Você pode definir um apelido para exibir no lugar do nome técnico.
Versão do Kubernetes, número de nodes e status do cluster (ativo, erro ou inativo).
Data da última coleta.
Detalhe por node (expansível): kubelet, sistema operacional, CPU, memória e se o node está pronto.

Nenhuma configuração é necessária: logo após a instalação, o agente começa a reportar o cluster — aguarde alguns minutos até os dados aparecerem.