Implementar e correr o agent

O agent é um único executável autocontido. Não tem instalador, nem dependências de execução, nem base de dados própria, e lê toda a sua configuração das variáveis de ambiente mais o instantâneo de configuração que extrai do ConnXL. Tudo o que se segue assume que já criaste um suplemento e um ambiente no dashboard — o separador Implementação da página do Agente é onde transferes um binário já gravado com a sua identidade.

Transferir e verificar o binário

Implementação → Transferir agent configurado dá-te um binário com o URL do backend, o ID do suplemento, o ID do ambiente e um token de inscrição novo já incorporados, por isso corre com zero variáveis de ambiente. Plataformas: Windows x64, Linux x64, Linux arm64.

Cada transferência é publicada juntamente com um ficheiro SHA256SUMS. Verifica antes de o executares:

# Linux / macOS
sha256sum -c SHA256SUMS --ignore-missing

# Windows PowerShell
(Get-FileHash .\connxl-agent.exe -Algorithm SHA256).Hash -eq (Get-Content .\SHA256SUMS | Select-String 'connxl-agent.exe').ToString().Split()[0]

Confirma a qualquer momento o que tens:

connxl-agent --version     # imprime a versão de compilação
connxl-agent --licenses    # imprime os avisos de terceiros

Correr como serviço

O agent corre em primeiro plano e escreve os logs em stdout, por isso qualquer gestor de serviços serve. Dá-lhe um utilizador dedicado e um diretório de trabalho estável — é aí que escreve a identidade que inscreve.

Linux (systemd)

[Unit]
Description=ConnXL Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=connxl
WorkingDirectory=/opt/connxl
ExecStart=/opt/connxl/connxl-agent
Restart=always
RestartSec=5
Environment=CONNXL_DATA_DIR=/var/lib/connxl
# TimeoutStopSec tem de exceder o dreno de 10 s de pedidos em voo do agent.
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now connxl-agent
sudo systemctl status connxl-agent

Windows (serviço)

O binário é uma aplicação de consola simples, por isso regista-o com sc.exe ou com um wrapper de serviços como o NSSM:

# A usar o NSSM (trata do redirecionamento de stdout e dos reinícios)
nssm install ConnXLAgent "C:\Program Files\ConnXL\connxl-agent.exe"
nssm set ConnXLAgent AppDirectory "C:\Program Files\ConnXL"
nssm set ConnXLAgent AppEnvironmentExtra "CONNXL_DATA_DIR=C:\ProgramData\ConnXL"
nssm set ConnXLAgent AppStdout "C:\ProgramData\ConnXL\logs\stdout.log"
nssm start ConnXLAgent

Correr num contentor

Não há imagem publicada — constrói uma mínima à volta do binário de Linux. O agent precisa de certificados de CA para o TLS de saída e de um volume persistente para a sua identidade, ou volta a inscrever-se a cada reinício.

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY connxl-agent /usr/local/bin/connxl-agent
ENV CONNXL_DATA_DIR=/var/lib/connxl
VOLUME /var/lib/connxl
EXPOSE 3000
ENTRYPOINT ["/usr/local/bin/connxl-agent"]

Kubernetes. Corre-o como um Deployment atrás de um Service, com o token de inscrição vindo de um Secret. Usa apenas uma sonda de liveness — vê o aviso sobre o endpoint de saúde na secção 6.

spec:
containers:
  - name: connxl-agent
    image: your-registry/connxl-agent:0.1.0
    ports:
      - containerPort: 3000
    env:
      - name: CONNXL_BACKEND_URL
        value: https://api.connxl.com
      - name: CONNXL_ADDIN_ID
        value: "<add-in id>"
      - name: CONNXL_ENV_ID
        value: "<environment id>"
      - name: CONNXL_ENROLL_TOKEN
        valueFrom:
          secretKeyRef: { name: connxl-agent, key: enrollToken }
    livenessProbe:
      httpGet: { path: /healthz, port: 3000 }
      initialDelaySeconds: 10
      periodSeconds: 30
    terminationGracePeriodSeconds: 30

Variáveis de ambiente

Um binário gravado não precisa de nenhuma destas; ainda assim, cada variável sobrepõe-se ao seu valor gravado. Só o grupo de identidade é obrigatório num binário não configurado.

Identidade e backend

Listener e TLS

Armazenamento e ficheiros de identidade

Logging

Segredos

Requisitos de rede

Todas as ligações ao ConnXL são iniciadas pelo agent para fora. Nada precisa de alcançar o agent a partir da internet, e não é necessária nenhuma regra de firewall de entrada para o próprio ConnXL.

Saída — permite para o host da tua API do ConnXL em TCP 443:

Duas destas — o stream SSE de configuração e o canal de controlo por WebSocket — são ligações de longa duração. Os middleboxes que matam ligações inativas provocarão reconexões repetidas; o agent recupera, mas o dashboard vai oscilar.

Entrada: os teus utilizadores de Excel (e o teu balanceador de carga) têm de alcançar o agent em CONNXL_LISTEN_ADDR, porta 3000 por omissão.

Permite também: as tuas próprias fontes de dados e — apenas se usares inscrição por identidade cloud — o endpoint de metadados da instância (169.254.169.254).

Verificações de saúde e monitorização

O agent serve GET /healthz no seu endereço de escuta. Devolve 200 ok sempre que o processo está a correr.

Para saúde a sério, usa o dashboard: a página do Agente do ambiente mostra o CPU, a memória e o disco de cada réplica com uma linha temporal de 24 horas, o último heartbeat e a versão de configuração efetivamente aplicada. O backend marca um agent como offline ao fim de cerca de 90 segundos sem heartbeat, e os alertas podem notificar-te — vê Alertas.

Atualizar para uma versão nova

O agent nunca se atualiza a si próprio. Quando uma réplica reporta uma versão mais antiga do que a última publicada, o dashboard assinala-a e pode levantar uma notificação de Atualização disponível, mas nada é transferido nem substituído sem ti. Uma atualização é: colocar o binário novo no lugar e reiniciar.

Como não há qualquer handshake de desregisto com o teu balanceador de carga, tira tu mesmo a instância de rotação primeiro — o /healthz vai continuar a devolver 200 mesmo durante um encerramento, por isso não consegue sinalizar o dreno por ti.

1. Remove a réplica do balanceador de carga.
2. Envia drain a partir da página do Agente. Isto desmonta os subscritores de streaming para que se reconectem noutro sítio; não para o listener nem termina o processo.
3. Para o serviço (SIGTERM, ou systemctl stop). Os pedidos em voo têm até 10 segundos para terminar, por isso permite pelo menos 30 segundos de timeout de paragem.
4. Substitui o binário e arranca o serviço de novo.
5. Confirma a nova versão na página do Agente e devolve a réplica à rotação.

Com mais do que uma réplica, faz isto uma de cada vez e o ambiente mantém-se disponível do princípio ao fim.

O que o agent guarda em disco

Os resultados de funções em cache são mantidos em memória, ou em Valkey/Redis quando o ambiente configura uma cache externa — nunca em disco.

Não precisas de fazer cópia de segurança de nada disto. Se o diretório de dados se perder, o agent volta a inscrever-se automaticamente no arranque seguinte e continua, desde que o seu token de inscrição (ou a atestação cloud, ou a identidade gravada) continue no seu ambiente. O único custo é um certificado novo e um histórico de logs do zero. Só precisas de um token novo se um administrador tiver entretanto clicado em Regenerar.

Dimensionamento e escalabilidade

O agent é um proxy leve: não retém qualquer conjunto de dados, e o seu trabalho é dominado pela espera pelas tuas fontes de dados. Uma instância pequena — 1 vCPU e 512 MB de memória — corre confortavelmente um ambiente típico, e o uso de disco limita-se a uma semana de logs.

Escala horizontalmente, não verticalmente. Acrescenta réplicas atrás de um balanceador de carga quando precisares de débito ou de redundância:

• Todas as réplicas de um ambiente partilham um único token de inscrição e aparecem individualmente na página do Agente.
• Não é necessária afinidade de sessão — o agent não guarda estado por utilizador entre pedidos.
• Dimensiona primeiro para a concorrência nas tuas fontes de dados; as predefinições do pool SQL (20 ligações abertas por motor, por réplica) multiplicam-se pelo número de réplicas.

Retirar um agent

Para desativar um host de forma limpa:

1. Tira-o de rotação e confirma que o tráfego passou para outra réplica.
2. Para o serviço e desativa o seu arranque automático.
3. Expulsa a réplica a partir da página do Agente do ambiente. Isto coloca-a numa lista de bloqueio para que não se possa voltar a ligar mesmo que o processo regresse — a forma fiável de cortar um host que já não controlas.
4. Apaga o diretório de dados para destruir a chave privada em disco.
5. Se estiveres a retirar todos os agents desse ambiente, clica em Regenerar no separador Implementação para que os tokens de inscrição antigos deixem de funcionar.