Variáveis de ambiente

Toda a configuração do runner vem do ambiente e é validada por schema no boot, com fail-fast: se algo não bate, o processo morre com o erro legível em vez de subir meio configurado.

Invalid runner configuration:
  RUNNER_TUNNEL_URL: String must contain at least 1 character(s)

Por que o ambiente, e não um arquivo de config

O runner roda na infra do cliente, então o ambiente dele já é a configuração por tenant. Configuração específica de connector mora aqui, declarada no manifest, e não no client_config: aquele é parâmetro do control-plane, e connector nenhum o recebe.

Endpoints do control-plane

Variável	Default	Notas
RUNNER_TUNNEL_URL	nenhum	Obrigatória. Ex.: wss://tunnel.rootpilot.sh:8443.
RUNNER_ENROLL_URL	nenhum	Obrigatória, exceto com certificado provisionado. Ex.: https://app.rootpilot.sh.
RUNNER_ENROLL_PATH	/api/enroll	A rota de enrollment.

Identidade

Variável	Default	Notas
RUNNER_INSTANCE_ID	UUID aleatório	Identifica a instância nos logs e no Fleet.
RUNNER_ATTESTATION_MODE	bootstrap-token	bootstrap-token, aws-sts, gke-oidc. eks-oidc é aceito pelo schema e falha no boot.
RUNNER_BOOTSTRAP_TOKEN	nenhum	Obrigatória quando o modo é bootstrap-token.
AWS_REGION	nenhum	Obrigatória quando o modo é aws-sts. Também usada pelos connectors AWS.
RUNNER_GKE_TOKEN_PATH	/var/run/secrets/tokens/gke-oidc/token	Onde ler o token projetado da KSA.
RUNNER_CERT_PEM	nenhum	Atalho de desenvolvimento. PEM inline, não caminho.
RUNNER_KEY_PEM	nenhum	Par do anterior. Os dois juntos pulam o enrollment.
RUNNER_CA_PEM	nenhum	Cadeia da CA, opcional no atalho.
RUNNER_CERT_RENEWAL	on	off desliga a rotação, e devolve ao runner um prazo de validade de 1 hora.

Secret store

Onde as credenciais dos seus serviços são lidas. Detalhe em Secret stores.

Variável	Default	Notas
RUNNER_SECRET_STORE_MODE	env	env (desenvolvimento), aws, vault.
RUNNER_SECRETS_MANAGER_REGION	nenhum	Modo aws. Ausente ⇒ resolução default do SDK.
RUNNER_SECRETS_MANAGER_PREFIX	''	Modo aws. Prefixa o SecretId.
RUNNER_VAULT_ADDR	nenhum	Obrigatória no modo vault.
RUNNER_VAULT_AUTH	token	token ou approle.
RUNNER_VAULT_TOKEN	nenhum	Obrigatória com auth token.
RUNNER_VAULT_ROLE_ID	nenhum	Obrigatória com auth approle.
RUNNER_VAULT_SECRET_ID	nenhum	Obrigatória com auth approle.
RUNNER_VAULT_NAMESPACE	nenhum	Vault Enterprise.
RUNNER_VAULT_KV_MOUNT	secret	Mount do KV v2.
RUNNER_VAULT_KV_FIELD	value	Campo do secret a retornar.
RUNNER_VAULT_PREFIX	''	Prefixa o caminho lógico.

O schema valida as combinações e recusa cedo:

RUNNER_SECRET_STORE_MODE=vault requires RUNNER_VAULT_ADDR
vault auth requires RUNNER_VAULT_TOKEN (token) or RUNNER_VAULT_ROLE_ID+RUNNER_VAULT_SECRET_ID (approle)

Connectors

Variável	Default	Notas
RUNNER_CONNECTORS	synthetic	synthetic, real, demo. Ver Modos de connector.
RUNNER_OBSERVABILITY	datadog	datadog, grafana, none. Exclusivo. Ver Observabilidade.
RUNNER_CONNECTOR_MECHANISMS	native	CSV dos mecanismos de isolamento habilitados.
RUNNER_CONNECTOR_SIDECAR_TIMEOUT_MS	30000	Deadline de invoke do sidecar.
RUNNER_AWS_CRED_MODE	static	static ou chain. Ver Credenciais de nuvem.
RUNNER_GCP_CRED_MODE	static	static ou chain.

Mecanismo e fonte de dados são coisas ortogonais

RUNNER_CONNECTOR_MECHANISMS diz como o connector é isolado (native, sidecar, wasm). RUNNER_CONNECTORS diz de onde vêm os dados. Um não implica o outro.

Estado aprendido

Variável	Default	Notas
RUNNER_LEARNED_SYNC	on	off = estritamente local: o store nem é instanciado e nada sai do runner.
RUNNER_LEARNED_STORE_PATH	:memory:	Caminho do SQLite. É cache, não fonte de verdade.
RUNNER_LEARNED_FLUSH_INTERVAL_MS	60000	Flush periódico. 0 desliga e deixa só o flush do drain.

O flush periódico existe porque o único flush era no drain, então um reclaim duro (SIGKILL, OOM, spot) perdia tudo desde o boot. Ele é watermark-safe: marca como sincronizado apenas o snapshot que de fato foi enviado, então re-flush após reconexão não dobra contagem.

Comportamento e tempos

Variável	Default	Notas
RUNNER_INVOKE_DEADLINE_MS	30000	Deadline por operação, aplicado no enforcement.
RUNNER_IDEMPOTENCY_TTL_MS	300000	TTL do cache de idempotência.
RUNNER_IDEMPOTENCY_MAX_ENTRIES	2000	Teto de entradas; despeja a mais antiga. Limita memória num runner longevo.
RUNNER_HEALTH_PROBE_TIMEOUT_MS	10000	Deadline por connector do self-check de credencial no boot.
RUNNER_RECONNECT_MAX_MS	30000	Teto do backoff de reconexão do túnel.
RUNNER_HEARTBEAT_INTERVAL_MS	15000	Intervalo de heartbeat no túnel.
RUNNER_DRAIN_TIMEOUT_MS	120000	Teto do drain no SIGTERM. Dimensione a graça do orquestrador acima disso.
RUNNER_TLS_INSECURE_SKIP_VERIFY	false	Só teste. Ver aviso abaixo.
NODE_ENV	development	development, production, test.

O HEALTH_PROBE_TIMEOUT_MS é 10 s e não 5 s de propósito: vários runners no mesmo host disparando probes em paralelo, somados ao cold start, empurram uma chamada de ~2 s para além de 5 s e produzem um error falso.

RUNNER_TLS_INSECURE_SKIP_VERIFY

Desliga a verificação de identidade do servidor no TLS. O túnel continua validando o certificado do runner. Só o runner para de checar o do servidor. É uma escotilha de desenvolvimento para certificado expirado ou hostname divergente. Não a leve para produção.

Fora do schema do runner

Estas não são validadas pelo schema, mas mudam o comportamento:

Variável	Default	Onde age
ROOTPILOT_OTEL_ENABLED	false	Liga a telemetria OpenTelemetry. Ver Telemetria.
ROOTPILOT_PII_REDACTION	ligado	off desliga a camada estrutural de redação. Ver Redação de PII.
EKS_CLUSTER	nenhum	Sem ela o health check do EKS responde skipped: no cluster configured.
RUNNER_TENANT	nenhum	Dos scripts de frota, não do runner. Escolhe a pasta do cofre e liga RUNNER_CONNECTORS=real.

As credenciais de cada connector (DD_API_KEY, GITHUB_TOKEN, …) também não estão no schema do runner: elas são declaradas nos manifests e lidas do secret store. A lista completa está em Credenciais por connector.