O Manager e o Worker do Fetcher são configurados inteiramente por variáveis de ambiente — cada componente lê seu próprio arquivo .env (components/manager/.env, components/worker/.env). Esta página cobre as variáveis que importam para uma implantação MVP; os arquivos .env.example no repositório são a referência exaustiva.
Chaves de criptografia
| Variável | Componente | Descrição |
|---|
APP_ENC_KEY | Manager + Worker | Obrigatória. Chave-mestra de 32 bytes codificada em base64. Gere com make generate-master-key. Os dois serviços devem compartilhar o mesmo valor. |
APP_ENC_KEY_VERSION | Manager + Worker | Contador de rotação de chave (padrão 1). Incremente ao rotacionar; o Fetcher rastreia qual versão criptografou cada credencial. |
make derive-key KEY="<chave-mestra>".
API do Manager
| Variável | Descrição | Padrão |
|---|
SERVER_PORT | Porta HTTP da API do Manager | 4006 |
SCHEMA_CACHE_TTL_SECONDS | Por quanto tempo esquemas descobertos ficam em cache | 300 |
PLUGIN_AUTH_ENABLED | Delegar autenticação/autorização ao Access Manager | false |
PLUGIN_AUTH_ADDRESS | Endereço do Access Manager quando a autenticação está habilitada | — |
LOG_LEVEL | Verbosidade dos logs | debug (local) |
Infraestrutura
Ambos os serviços conectam ao MongoDB (metadados) e ao RabbitMQ (fila de jobs); o Manager também usa Valkey/Redis para cache, e o Worker grava resultados em object storage.
| Variável | Componente | Descrição |
|---|
MONGO_HOST, MONGO_PORT, MONGO_NAME, MONGO_USER, MONGO_PASSWORD | Manager + Worker | Armazenamento de metadados no MongoDB |
RABBITMQ_HOST, RABBITMQ_PORT_AMQP, RABBITMQ_DEFAULT_USER, RABBITMQ_DEFAULT_PASS | Manager + Worker | Broker RabbitMQ |
RABBITMQ_FETCHER_WORK_QUEUE | Manager + Worker | Fila de trabalho de extração (padrão fetcher.extract-external-data.queue) |
RABBITMQ_NUMBERS_OF_WORKERS | Worker | Workers de extração concorrentes (padrão 5) |
REDIS_HOST, REDIS_PORT, REDIS_PASSWORD | Manager | Cache Valkey/Redis |
OBJECT_STORAGE_ENDPOINT, OBJECT_STORAGE_REGION, OBJECT_STORAGE_BUCKET, OBJECT_STORAGE_ACCESS_KEY_ID, OBJECT_STORAGE_SECRET_KEY | Worker | Armazenamento de resultados compatível com S3 (SeaweedFS por padrão; AWS S3 e MinIO funcionam da mesma forma) |
ENGINE_MAX_RESULT_BYTES | Worker | Teto do artefato de resultado serializado por job (padrão 256 MiB) |
MONGO_TLS_CA_CERT, REDIS_TLS, RABBITMQ_TLS) estão disponíveis por dependência.
Streaming de eventos de jobs
O Worker publica notificações obrigatórias job.completed e job.failed e falha de forma fechada na inicialização se o streaming não estiver habilitado:
| Variável | Descrição | Padrão |
|---|
STREAMING_ENABLED | Deve ser true para o Worker iniciar | false |
STREAMING_BROKERS | Servidores bootstrap Kafka/Redpanda | localhost:9092 |
STREAMING_CLOUDEVENTS_SOURCE | Origem CloudEvents dos eventos do Worker | — |
RABBITMQ_JOB_EVENTS_EXCHANGE | Exchange RabbitMQ para eventos de jobs | fetcher.job.events |
single-tenant.
Multi-tenancy
| Variável | Descrição | Padrão |
|---|
MULTI_TENANT_ENABLED | Habilita o modo multi-tenant | false |
MULTI_TENANT_URL | URL do serviço Tenant Manager | — |
MULTI_TENANT_MAX_TENANT_POOLS | Máximo de pools de conexão de tenant concorrentes | 100 |
MULTI_TENANT_IDLE_TIMEOUT_SEC | Timeout de conexão ociosa de tenant | 300 |
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD | Limite de falhas do circuit breaker | 5 |
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC | Timeout de reset do circuit breaker | 30 |
Habilitar o modo multi-tenant também ativa a guarda de segurança contra SSRF: hosts de conexão fornecidos por tenants são checados contra faixas de loopback, endereços privados (RFC 1918) e metadados de nuvem antes de o Fetcher conectar. Com MULTI_TENANT_ENABLED=false (o padrão), todos os caminhos de código multi-tenant são ignorados com impacto zero de desempenho.
Readiness e postura de TLS
| Variável | Descrição | Padrão |
|---|
DEPLOYMENT_MODE | saas, byoc ou local — etiqueta o /readyz e comanda a exigência de TLS em SaaS | local |
ALLOW_INSECURE_TLS | Permite conexões em texto claro com MongoDB, Redis e RabbitMQ. O Fetcher falha de forma fechada em URIs de conexão inseguras por padrão — defina apenas para desenvolvimento local. | não definida (fail closed) |
READYZ_DRAIN_DELAY_SEC | Janela de drenagem graciosa após SIGTERM, durante a qual o /readyz reporta unhealthy antes de as conexões serem encerradas | 12 |
GET /health (liveness), GET /readyz (readiness com sondas paralelas de dependências) e GET /version.
Datasources internos
Bancos fixos, de propriedade do operador, podem ser declarados como variáveis de ambiente em vez de conexões registradas pela API, usando a família DATASOURCE_{NAME}_*:
| Variável | Obrigatória | Exemplo |
|---|
DATASOURCE_{N}_CONFIG_NAME | sim | billing_db |
DATASOURCE_{N}_TYPE | sim | postgresql / mysql / oracle / mongodb / sql_server |
DATASOURCE_{N}_HOST | sim | db.internal.example.com |
DATASOURCE_{N}_PORT | sim | 5432 |
DATASOURCE_{N}_DATABASE | sim | billing |
DATASOURCE_{N}_USER | sim | fetcher_ro |
DATASOURCE_{N}_PASSWORD | sim | do seu gerenciador de segredos |
DATASOURCE_{N}_OPTIONS | não | authSource=admin (apenas MongoDB) |
DATASOURCE_{N}_SSLMODE | não | require (PostgreSQL) |
_SSLMODE é a opção validada; plumbing de CA customizada ou certificado de cliente para datasources internos não está disponível.
Observabilidade
O Fetcher emite traces e métricas OpenTelemetry quando a telemetria está habilitada:
| Variável | Descrição | Padrão |
|---|
ENABLE_TELEMETRY | Liga/desliga a emissão OTel | false |
OTEL_EXPORTER_OTLP_ENDPOINT | Endpoint do coletor OTLP | — |
OTEL_RESOURCE_SERVICE_NAME | Nome do serviço na telemetria (fetcher / fetcher-worker) | por componente |
