Kubernetes Agent

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.

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.

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

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>

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:

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.

Alertmanager

Conecta o Alertmanager do seu cluster (Prometheus Operator / kube-prometheus-stack) ao OpsScript: os alertas que disparam no Prometheus viram chamados automaticamente, e você passa a gerenciar regras de alerta (PrometheusRule) e mutes pela interface do OpsScript — incluindo sugestões de regras geradas por IA a partir do que o agente observa no cluster.

Como funciona

• O agente atua como reconciliador: as regras e rotas definidas no OpsScript são aplicadas por ele como CRs PrometheusRule e AlertmanagerConfig no namespace alvo, a cada 5 minutos (e imediatamente após qualquer mudança na interface). Recursos removidos no OpsScript são removidos do cluster.
• A entrega dos alertas é direta: a integração provisiona uma rota (opsscript-routes) cujo receiver envia os webhooks do Alertmanager direto para a política de alerta no OpsScript — o agente não fica no caminho do alerta, então a entrega continua funcionando mesmo se o agente estiver pausado ou fora do ar.
• Alertas resolvidos no Alertmanager resolvem o chamado correspondente (sendResolved); o agrupamento padrão é por alertname + namespace, com reenvio a cada 4 horas. O alerta Watchdog (heartbeat do kube-prometheus-stack) é ignorado por padrão.

Pré-requisitos

1. Prometheus Operator no cluster (kube-prometheus-stack, rancher-monitoring ou equivalente) — a integração aplica CRs monitoring.coreos.com. Sem os CRDs, a tela exibe o aviso "Prometheus Operator não detectado" e o agente retoma sozinho quando eles aparecerem.

2. RBAC do agente habilitado no chart (desligado por padrão — o cliente decide o escopo de escrita):

   alertmanagerIntegration:
     enabled: true
     # Único namespace onde o agente pode criar/alterar PrometheusRule e
     # AlertmanagerConfig (onde o monitoring roda, ex.: monitoring ou
     # cattle-monitoring-system). Leitura dos CRs é cluster-wide; o agente
     # nunca acessa Secrets (o alertmanager.yaml fica intocado).
     targetNamespace: monitoring

3. O Alertmanager precisa carregar AlertmanagerConfig de CRs — confira no recurso Alertmanager do cluster (values do kube-prometheus-stack/rancher-monitoring):

   alertmanager:
     alertmanagerSpec:
       # Selecionar os AlertmanagerConfigs ({} = todos)
       alertmanagerConfigSelector: {}
       # OBRIGATÓRIO para receber alertas de todos os namespaces
       # (requer prometheus-operator >= 0.62)
       alertmanagerConfigMatcherStrategy:
         type: None

   O default do prometheus-operator (OnNamespace) injeta um matcher de namespace na rota gerada: somente alertas do próprio namespace do AlertmanagerConfig são entregues e todos os demais são descartados sem nenhum erro em logs ou na interface. Se a integração está "verde" mas nenhum chamado é aberto, este é o primeiro item a verificar — a tela da integração exibe um aviso quando o agente detecta essa configuração.

4. Egress: o Alertmanager precisa alcançar api.opsscript.io (HTTPS) para entregar os webhooks.

Criar a integração

Na aba Integrações, clique em Nova integração no bloco do agente e escolha Alertmanager. Campos:

Regras, sugestões de IA e mutes

• Regras geridas: crie e edite PrometheusRule pela interface (formulário ou YAML). Toda regra passa por validação de sintaxe PromQL e de semântica de disparo antes de ser aceita — expressões sem comparação/threshold e for menor que 1 minuto são rejeitadas, os dois erros mais comuns que fazem uma regra "nunca alertar".
• Sugestões por IA: peça sugestões manualmente (inclusive em linguagem natural) ou habilite a análise diária. As sugestões passam pela mesma validação das regras manuais e só são aplicadas após você aceitar.
• Regras do cluster: a integração também lista as regras de terceiros (Helm/ArgoCD/manuais) observadas no cluster, para você saber a origem de cada alertname que chega.
• Ignorar alertnames (mute): para alertas de regras de terceiros que você não quer no OpsScript, use o mute — a integração adiciona um matcher alertname != <nome> na rota (a regra do terceiro nunca é alterada ou removida) e resolve os chamados já abertos daquele alertname.

Solução de problemas

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.

Próximos Passos