xDS control planes

An xDS control plane pushes configuration to Arion over gRPC while it runs, so listeners, routes, clusters, endpoints and secrets change without restarts. Use it when configuration changes often or is generated by a platform; a static file is fine otherwise.

The Arion control plane supplies this configuration from YAML files, an interactive Elixir shell, application code, or Kubernetes Gateway API. The connection instructions below apply to any compatible delta ADS server.

Enable it

The bootstrap needs two things: a static cluster pointing at your control plane, and dynamic_resources naming that cluster for ADS. The control plane speaks gRPC, so the cluster must be HTTP/2:

envoy_bootstrap:
  node:
    id: "arion-1"
    cluster: "edge"
  dynamic_resources:
    ads_config:
      grpc_services:
        - envoy_grpc:
            cluster_name: xds_cluster
  static_resources:
    clusters:
      - name: xds_cluster
        connect_timeout: 0.25s
        type: STATIC
        lb_policy: ROUND_ROBIN
        typed_extension_protocol_options:
          envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
            "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
            explicit_http_config:
              http2_protocol_options: {}
        load_assignment:
          cluster_name: xds_cluster
          endpoints:
            - lb_endpoints:
                - endpoint:
                    address:
                      socket_address: { address: 127.0.0.1, port_value: 50051 }

node.id and node.cluster identify this instance to the control plane (both are required when node is present). With the Arion control plane, node.cluster selects the fleet: this example needs resources in the edge fleet, so set metadata.fleet: edge in its control-plane manifests. Leave api_type and transport_api_version out — Arion rejects them, because there is nothing to choose: the transport is always the one described next.

What the transport is

Arion speaks incremental (delta) xDS over ADS: one AggregatedDiscoveryService stream to one control plane, using DeltaDiscoveryRequest/DeltaDiscoveryResponse. State-of-the-world responses and per-type config sources (lds_config, cds_config) are not supported, so your control plane must serve the delta ADS variant (go-control-plane and most modern servers do). On connect, Arion subscribes to secrets, clusters, endpoints, listeners and routes in that order.

What can be dynamic

Field-level support matches the file format exactly; the same conversion runs on both paths. See the xDS resource type reference.

When an update is rejected

Every pushed resource goes through the same decoding and conversion as a bootstrap resource. If any resource fails this step, including an unsupported Envoy field or enum variant, Arion NACKs the whole response before applying its updates or removals. The reply carries an error_detail naming the rejected resources and reasons.

After conversion, resources are applied individually. A failure at this stage produces a NACK, but successful changes from the same response stay applied. Updates across resource types are separate responses, with no atomic transaction between them. Inspect the applied state and verify traffic after a NACK; watch the Arion log for rejecting configs with nack response and your control plane's NACK metrics.

Reconnects

If the control plane is unreachable at startup, Arion retries the connection every 10 seconds (Retrying XDS connection in the log). If an established stream fails, the client reconnects with exponential backoff from 1 second up to 20 seconds, re-subscribes, and resumes from its tracked resource versions. Static resources keep serving throughout.

Verify

grep -E "received config resources|Retrying XDS" /var/log/arion/arion.log
curl -s http://127.0.0.1:9901/listeners

Expected: received config resources from xDS lines as pushes arrive (a repeating Retrying XDS connection means the control plane cannot be reached), and the pushed listeners appearing in the admin interface — /config_dump shows the full applied state on a config-dump build.

Limits

• One ADS stream at a time. Listing several grpc_services entries gives fallback clusters to try in turn when connecting; google_grpc targets are not supported here.
• The control-plane connection is an ordinary upstream cluster: endpoints load-balance round-robin, and a TLS transport socket on xds_cluster encrypts it.
• There is no on-demand or REST xDS, and no state-of-the-world fallback for control planes without delta support.