Configuration

Arcentra ships three example configuration files under conf.d/:

​

Control plane: config.toml

The control plane configuration is read by cmd/arcentra and shared across HTTP, gRPC, scheduling, and storage subsystems.

​

[metrics]

Prometheus-compatible metrics endpoint.

​

[trace] and [trace.batch]

OpenTelemetry tracing.

• exporterType: jaeger, otlp-grpc, otlp-http, or none.
• endpoint, insecure, headers: configure the exporter target.
• [trace.batch] controls queue size and export timeouts; raise exportTimeout if you see context deadline exceeded.

​

[events] and [messageQueue.kafka]

CloudEvents publishing and the Kafka transport. Important keys:

• [events].sourcePrefix — prefix used for event sources.
• [messageQueue.kafka].bootstrapServers — Kafka brokers.
• securityProtocol — PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL.
• [messageQueue.kafka.sasl] — SASL mechanism, username, password.
• [messageQueue.kafka.ssl] — TLS material when SSL is enabled.

​

[log] and [logger.*]

Two complementary logging modes:

• [log] — single-output logger (stdout, file, or kafka) with rotation by time and size.
• [logger.*] — multi-category logger initialized via logger.InitMulti, with per-category outputs (HTTP, plugin, cron, and so on).

​

[grpc] and [http]

[http.auth] controls JWT issuance:

• accessExpire and refreshExpire accept duration strings (60m, 1h, 7d); plain numbers fall back to minutes.
• secretKey must be rotated before any non-local deployment.

​

[database]

Choose mysql or sqlite via driver.

• [database.mysql].dsn — full DSN with charset and parseTime=True.
• [database.sqlite].dsn — file path; SQLite is unsuitable for production control-plane usage.
• [database.options] — connection pool size, max lifetime/idletime, and SQL logging (output).

​

[redis]

Single, cluster, or sentinel modes.

• mode — single, cluster, or sentinel.
• address — single host, comma-separated cluster endpoints, or sentinel addresses.
• TLS, sentinel master and credentials, and maxRedirects are commented out in the defaults; uncomment as needed.

​

[taskQueue]

Task queue configuration for delayed jobs.

• provider — kafka is the supported default.
• delaySlotCount and delaySlotDuration — control delayed-execution slots.
• messageFormat and messageCodec — protobuf, json, sonic, or blob.

​

Agent: agent.toml

The agent file is read by cmd/arcentra-agent and connects each agent to the control plane.

​

[grpc]

• serverAddr — control-plane gRPC address (host:port).
• token — bearer token for agent authentication.
• readWriteTimeout, maxMsgSize, maxReconnectAttempts.

​

[agent]

• mode — sandbox or baremetal.
• id, name, description — identity for scheduling and audit.
• interval — heartbeat interval, in seconds.
• maxConcurrentJobs, jobTimeout — concurrency budget and per-job timeout.
• workspaceDir, tempDir, cacheDir — local working directories.
• deniedCommands — commands the shell builtin must refuse.
• proxyUrl — outbound proxy.
• [agent.labels] — arbitrary key/value labels used by step run selectors (for example env, team, region).
• [agent.resourceLimits] — declared CPU/memory budgets.
• [agent.envVars] — environment variables injected into jobs.
• [agent.cleanupPolicy] — workspace retention (max_size_gb, max_age_days).

​

[agent.sandbox], [agent.sandbox.containerd], [agent.sandbox.kubernetes]

• enable and runtime — switch between containerd and kubernetes.
• containerd: network, unixSocket, default image, and resource limits.
• kubernetes: target namespace, podName, image, and resource limits.

​

Other sections

The agent shares the metrics, log, Kafka, HTTP, Redis, and task queue layout with the control plane. The HTTP server defaults to :8081, metrics to :8084, and the agent uses its own log file (agent.LOG).

​

Plugins and builtins: plugins.toml

This file provides default args.config for builtins and per-plugin configuration. Step-level configuration overrides these defaults.

​

Builtins

• [builtins.shell] — shell binary, default timeout, and allowDangerous flag.
• [builtins.stdout] — output prefix and json toggle.
• [builtins.artifacts], [builtins.reports], [builtins.scm] — reserved for future use.

​

Plugins

• [plugins.git] — gitPath, default userName / userEmail, shallow clone settings.
• [plugins.svn] — svnPath, default credentials, trustServerCert, nonInteractive.

​

Configuration tips

• Keep the example files as a reference and maintain your real settings in a separate, secret-managed location.
• When using SASL or TLS for Kafka, prefer SASL_SSL and store credentials outside the repository.
• For multi-tenant deployments, give each agent a unique id and a label set rich enough to drive scheduling decisions.
• Match the database, Redis, and Kafka versions used in production with what your CI environment validates against.