Skip to main content

​
Configuration

All control_plane fields require a process restart to change.

​
Authentication

Every request must be authenticated:
  • With auth_token: Send Authorization: Bearer <token> from any IP. Comparison is constant-time.
  • Without auth_token: Requests must originate from a loopback address (127.0.0.1 or ::1). No header required.
Unauthorized requests receive 401 Unauthorized.

​
Node roles

​
Common response codes

Gateway control plane API

Runtime API for config, cluster, and XDP endpoints.

Daemon control plane API

API for daemon lifecycle and control operations.

Observability API

API surface related to metrics and observability.

​
Follower configuration

When role: follower, Arc automatically polls a leader for config changes:
The follower issues GET /v1/config/longpoll?since=<generation> against the leader. When the config changes, the leader responds immediately. On timeout (30s), the follower re-issues. On network error, it backs off and retries.

​
Audit logging

Every config change event (validate, apply, or reject) is written to the structured log with:
  • Operation name (api, api_validate, cluster_api)
  • Peer address
  • Outcome (applied, rejected_restart_required, rejected_quorum)
  • Old and new generation numbers
  • Diff summary

​
Troubleshooting

If auth_token is set, include Authorization: Bearer <token> in every request. If auth_token is not set, the control plane only accepts connections from loopback (127.0.0.1 or ::1). Verify the control plane is bound to the correct address.
The node is not in leader role. Only leaders can push cluster config. Verify control_plane.role: leader in config. If the node is a follower, push config to the leader instead.
The committed and failed arrays in the response show which peers succeeded. Failed peers will pick up the config on their next long-poll cycle or gossip round. If committed is less than quorum, the entire commit is rejected and no nodes apply the new config.
Check that since is set to the current generation number. If since is less than the current generation, the server returns 200 immediately with the current config. Use GET /v1/config first to get the current X-Config-Generation header, then pass that as since.
XDP was not initialized — either the kernel does not support it, the interface does not support native XDP, or the XDP config block is absent. Check GET /v1/xdp/status first. If the endpoint itself returns 503, XDP is not running.
Gossip is not enabled. The control plane requires gossip configuration to be present. If you only need leader/follower replication without gossip, use pull_from with long-poll instead.