Arion control plane

The Arion control plane supplies listeners, routes, clusters, endpoints, and secrets to running proxies over xDS. Use it to manage configuration with files, Elixir code, or Kubernetes resources; Arion continues to handle application traffic.

Choose how to configure it

The shell attaches to the standalone service. Both interfaces save changes through Arion.Ctl. Each deployment uses the same library to deliver configuration to proxies.

Before you begin

Complete steps 1–5 of the standalone walkthrough. Leave the backend, control plane, and proxy running. Keep the operator terminal's release PATH, RELEASE_NODE, and cookie settings.

That setup listens on port 18080 and forwards to backend-a on 18081. Its bootstrap selects fleet arion. The general xDS guide explains the connection.

Apply a configuration change

Save this as backend.yaml in the operator terminal's working directory:

apiVersion: ctl.arion.io/v1alpha1
kind: Cluster
metadata:
  name: backend
  fleet: arion
spec:
  type: STATIC
  connectTimeout: 1s
  loadAssignment:
    clusterName: backend
    endpoints:
      - lbEndpoints:
          - endpoint:
              address:
                socketAddress: { address: 127.0.0.1, portValue: 18081 }

This is a control-plane resource document. The outer fields identify the resource; spec holds its protobuf configuration. Proxy bootstrap files configure the process and its xDS connection. Kubernetes uses its own resource definitions.

arionctl validate -f backend.yaml
arionctl apply -f backend.yaml
arionctl get --fleet arion
arionctl status

Validation reports one resource. Apply keeps the existing Listener and saves the Cluster, leaving two resources in this walkthrough's store. get shows saved definitions as JSON; status shows connected proxies and their ACK/NACK information.

Change the backend from the shell

In another terminal at the arion-ctl repository root, start a second backend:

python3 docs/examples/backend.py --port 18082 --name backend-b

In the operator terminal, attach to the service:

arionctl shell

Enter these Elixir expressions at the IEx prompt:

alias Arion.ControlPlane.Helpers.Cluster
cluster_b = Cluster.static("backend", "127.0.0.1", [18082], connect_timeout: 1)
{:ok, _} = Arion.Ctl.apply_resources([cluster: cluster_b], fleet: "arion")
Arion.Ctl.status()

The helper builds a Cluster value. apply_resources validates, saves, and publishes it through the same store as the CLI. From an ordinary terminal:

curl --fail http://127.0.0.1:18080/

After the update is accepted, expect hello from backend-b. Neither process needs a restart. The shell walkthrough covers inspection, deletion, and detaching.

Embedded and Kubernetes use

An Elixir application can supervise Arion.ControlPlane and publish resources through Arion.ControlPlane.Service. The application owns persistence and recovery; follow the library example.

On Kubernetes, a GatewayClass selects the controller, a Gateway defines entry points, and routes attach rules. The controller translates them into xDS and can provision the proxy workloads and Services. Start with the Helm installation.

For self-hosted model servers, the controller derives ready Pod endpoints from an InferencePool and configures ext_proc to call an external endpoint picker. See the AI inference gateway overview for the request flow and the inference routing guide for the Kubernetes resources.

Operational boundaries

• Apply replaces supplied resource specifications and preserves omitted identities. Delete explicitly; files are not watched.
• A successful apply means saved and published. Proxy acceptance arrives asynchronously; verify status and a real request.
• Give each standalone instance its own state directory. Kubernetes replicas reconstruct configuration from Kubernetes.
• metadata.fleet must match the proxy's node.cluster. Fleets separate configuration, not client access; keep control-plane connections on trusted networks.

See the configuration reference for accepted fields and deployment options for storage, credentials, and networking. The architecture post explains how the applications fit together.