Variables de entorno

Toda la configuración del runner viene del entorno y se valida contra el schema en el boot, en modo fail-fast: si algo no cuadra, el proceso muere con un error legible en lugar de levantarse configurado a medias.

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

Por qué el entorno, y no un archivo de configuración

El runner corre en la infraestructura del cliente, así que su entorno ya es configuración por tenant. La configuración específica de cada connector vive aquí, declarada en el manifest, y no en client_config: ese es un parámetro del control-plane, y ningún connector lo recibe jamás.

Endpoints del control-plane

Variable	Por defecto	Notas
RUNNER_TUNNEL_URL	ninguno	Obligatoria. Ej.: wss://tunnel.rootpilot.sh:8443.
RUNNER_ENROLL_URL	ninguno	Obligatoria, salvo que haya un certificado aprovisionado. Ej.: https://app.rootpilot.sh.
RUNNER_ENROLL_PATH	/api/enroll	La ruta de enrollment.

Identidad

Variable	Por defecto	Notas
RUNNER_INSTANCE_ID	UUID generado en cada boot	Identifica la instancia en los logs y en la Flota. No tiene relación con la persistencia: el dueño de la identidad vive dentro del propio RUNNER_IDENTITY_DIR.
RUNNER_IDENTITY_DIR	ninguno	Directorio con permiso de escritura donde se persiste la identidad, para que sobreviva al reemplazo del contenedor. Basta por sí sola. Uno por Agent: dos Agents en el mismo volumen se lo disputan. Ver Identidad y enrollment.
RUNNER_ATTESTATION_MODE	bootstrap-token	bootstrap-token, aws-sts, gke-oidc. eks-oidc es aceptado por el schema y falla en el boot.
RUNNER_BOOTSTRAP_TOKEN	ninguno	Obligatoria cuando el modo es bootstrap-token.
AWS_REGION	ninguno	Obligatoria cuando el modo es aws-sts. También la usan los connectors de AWS.
RUNNER_GKE_TOKEN_PATH	/var/run/secrets/tokens/gke-oidc/token	Dónde leer el token proyectado de la KSA.
RUNNER_CERT_PEM	ninguno	El certificado de tu tenant. PEM inline, no una ruta. El entrypoint lo completa a partir de /certs.
RUNNER_KEY_PEM	ninguno	Su par. Juntos se saltan el enrollment.
RUNNER_CA_PEM	ninguno	Cadena de la CA, opcional.
RUNNER_CERT_RENEWAL	on	Activa el planificador de renovación. Requiere RUNNER_ENROLL_URL; sin ella, nada se renueva.

Cómo nace la identidad, y cómo sobrevive

Son preguntas distintas, y la segunda es la que decide si un deploy necesita a alguien frente a un navegador.

Nace de una de estas: atestación de nube, un bootstrap token (ambos a través de RUNNER_ENROLL_URL) o un certificado aprovisionado (RUNNER_CERT_PEM + RUNNER_KEY_PEM). Se requiere al menos una; sin ninguna, el boot falla. Cuando hay un certificado aprovisionado, le gana a las otras, y el boot registra un warn que nombra lo que quedó afuera.

Sobrevive mediante la renovación (dentro del proceso) y la persistencia (RUNNER_IDENTITY_DIR, a través del reemplazo del contenedor). Un certificado aprovisionado no se renueva: vence en la fecha notAfter y el reemplazo es manual.

Detalle en Identidad y enrollment.

Secret store

De dónde se leen las credenciales de tus servicios. Detalle en Secret stores.

Variable	Por defecto	Notas
RUNNER_SECRET_STORE_MODE	env	env (desarrollo), aws, vault.
RUNNER_SECRETS_MANAGER_REGION	ninguno	Modo aws. Ausente ⇒ resolución por defecto del SDK.
RUNNER_SECRETS_MANAGER_PREFIX	''	Modo aws. Prefijo del SecretId.
RUNNER_VAULT_ADDR	ninguno	Obligatoria en modo vault.
RUNNER_VAULT_AUTH	token	token o approle.
RUNNER_VAULT_TOKEN	ninguno	Obligatoria con auth token.
RUNNER_VAULT_ROLE_ID	ninguno	Obligatoria con auth approle.
RUNNER_VAULT_SECRET_ID	ninguno	Obligatoria con auth approle.
RUNNER_VAULT_NAMESPACE	ninguno	Vault Enterprise.
RUNNER_VAULT_KV_MOUNT	secret	Mount del KV v2.
RUNNER_VAULT_KV_FIELD	value	Qué campo del secret devolver.
RUNNER_VAULT_PREFIX	''	Prefijo de la ruta lógica.

El schema valida las combinaciones y rechaza temprano:

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

Variable	Por defecto	Notas
RUNNER_CONNECTORS	synthetic	synthetic, real, demo. Ver Modos de connector.
RUNNER_OBSERVABILITY	datadog	datadog, grafana, none. Exclusivo. Ver Observabilidad.
RUNNER_CONNECTOR_MECHANISMS	native	CSV de los mecanismos de aislamiento habilitados.
RUNNER_CONNECTOR_SIDECAR_TIMEOUT_MS	30000	Plazo máximo del invoke del sidecar.
RUNNER_AWS_CRED_MODE	static	static o chain. Ver Credenciales de nube.
RUNNER_GCP_CRED_MODE	static	static o chain.
RUNNER_DENY_POLICY_FILE	ninguno	Artefacto JSON de la denylist de tools.
RUNNER_DENIED_GROUPS	ninguno	CSV de grupos denegados (network-posture, iam).
RUNNER_DENIED_CAPABILITIES	ninguno	CSV de capabilities denegadas.
RUNNER_DENIED_CONNECTORS	ninguno	CSV de connectors denegados.
RUNNER_DENIED_OPS	ninguno	CSV de operaciones denegadas.

Mecanismo y fuente de datos son ortogonales

RUNNER_CONNECTOR_MECHANISMS dice cómo se aísla un connector (native, sidecar, wasm). RUNNER_CONNECTORS dice de dónde vienen los datos. Ninguno implica al otro.

Estado aprendido

Variable	Por defecto	Notas
RUNNER_LEARNED_SYNC	on	off = estrictamente local: el store ni siquiera se instancia y nada sale del runner.
RUNNER_LEARNED_STORE_PATH	:memory:	Ruta del SQLite. Es una caché, no una fuente de verdad.
RUNNER_LEARNED_FLUSH_INTERVAL_MS	60000	Flush periódico. 0 lo desactiva, y queda solo el flush del drain.
RUNNER_LEARNED_FLUSH_DEBOUNCE_MS	2000	Flush poco después de una extracción, con debounce. 0 lo desactiva.

Los dos plazos miden cosas distintas. El flush periódico existe porque antes el único flush ocurría en el drain, así que un reclaim abrupto (SIGKILL, OOM, spot) perdía todo lo acumulado desde el boot. Acota la pérdida. El debounce acota la latencia: sin él, una arista que el agente acaba de descubrir podía tardar un intervalo entero en llegar al control-plane. Es un debounce y no un flush por operación porque una wave dispara varias operaciones a la vez, y hacer flush por operación significaría N llamadas para el mismo resultado; el flush periódico sigue actuando como techo, así que bajo extracción continua es el que garantiza un flush. Es watermark-safe: marca como sincronizado solo el snapshot que realmente se envió, así que un nuevo flush después de reconectar no cuenta dos veces.

Comportamiento y tiempos

Variable	Por defecto	Notas
RUNNER_INVOKE_DEADLINE_MS	30000	Plazo máximo por operación, aplicado en el enforcement.
RUNNER_IDEMPOTENCY_TTL_MS	300000	TTL de la caché de idempotencia.
RUNNER_IDEMPOTENCY_MAX_ENTRIES	2000	Tope de entradas; desaloja las más antiguas. Acota la memoria en un runner de larga vida.
RUNNER_HEALTH_PROBE_TIMEOUT_MS	10000	Plazo máximo por connector para el self-check de credenciales en el boot.
RUNNER_RECONNECT_MAX_MS	30000	Tope del backoff de reconexión del túnel.
RUNNER_HEARTBEAT_INTERVAL_MS	15000	Cadencia del ping de keepalive en el túnel. Mantiene la conexión abierta a través de LBs/proxies con idle timeout; dos intervalos sin respuesta cierran el socket para reconectar.
RUNNER_DRAIN_TIMEOUT_MS	120000	Tope del drain en SIGTERM. Dimensiona el período de gracia de tu orquestador por encima de este valor.
RUNNER_HEALTH_DIR	/tmp/rootpilot-health	Dónde el runner escribe la señal de salud que lee rootpilot-health (HEALTHCHECK de Docker, probe exec de Kubernetes). El uid 1000 tiene que poder escribir ahí; con un sistema de archivos raíz de solo lectura, monta un emptyDir/tmpfs en /tmp.
RUNNER_TLS_INSECURE_SKIP_VERIFY	false	Solo para pruebas. Ver la advertencia más abajo.
NODE_ENV	development	development, production, test.

HEALTH_PROBE_TIMEOUT_MS es 10 s y no 5 s a propósito: varios runners en un mismo host disparando probes en paralelo, sumados al cold start, empujan una llamada de ~2 s más allá de los 5 s y producen un error falso.

RUNNER_TLS_INSECURE_SKIP_VERIFY

Desactiva la verificación de identidad del servidor en TLS. El túnel sigue validando el certificado del runner; solo el runner deja de verificar el del servidor. Es una vía de escape de desarrollo para un certificado vencido o un hostname que no coincide. No lo lleves a producción.

Fuera del schema del runner

Estas no se validan con el schema, pero cambian el comportamiento:

Variable	Por defecto	Dónde actúa
ROOTPILOT_OTEL_ENABLED	false	Activa OpenTelemetry. Ver Telemetría.
ROOTPILOT_PII_REDACTION	activado	off desactiva las capas de redacción estructural y de contenido. Se rechaza con RUNNER_CONNECTORS=real y NODE_ENV=production. Ver Redacción de PII.
EKS_CLUSTER	ninguno	Sin ella, el health check de EKS responde skipped: no cluster configured. Es por Agent: el clúster tiene que estar en la cuenta y la región que lee ese Agent.
RUNNER_TENANT	ninguno	De los scripts de flota, no del runner. Elige la carpeta del cofre de secretos y activa RUNNER_CONNECTORS=real.

Las credenciales de cada connector (DD_API_KEY, GITHUB_TOKEN, …) tampoco están en el schema del runner: se declaran en los manifests y se leen del secret store. La lista completa está en Credenciales por connector.