---
title: "Arion control plane"
url: "/docs/operate/arion-control-plane/"
kind: "feature"
summary: "Configure Arion with YAML files, an interactive Elixir shell, an embedded library, or Kubernetes Gateway API."
---

> Arion site index: [/llms.txt](/llms.txt)

# Arion control plane

Configure Arion with YAML files, an interactive Elixir shell, an embedded library, or Kubernetes Gateway API.

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

| Use | Interface | Configuration owner |
| --- | --- | --- |
| Files and operator commands | Standalone service with `arionctl` | Durable local snapshot |
| Interactive inspection and programming | `arionctl shell`, using `Arion.Ctl` | The same standalone snapshot |
| Configuration generated by an application | Embedded `Arion.ControlPlane` library | The embedding application |
| Kubernetes-managed gateways | Gateway API controller | Kubernetes resources |

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.

{{ <figure src="img/docs/arion-control-plane.svg" alt="Configuration sources: an Elixir application, the standalone service shared by arionctl and IEx, or the Kubernetes controller. Each uses the Arion.ControlPlane library to send configuration over delta ADS. Application traffic goes from the client through Arion to the backend." caption="Alternative deployments use the same library. Application requests pass through the proxy." label="Figure 1." /> }}

## Before you begin

Complete steps 1–5 of the [standalone walkthrough](https://github.com/arion-gateway/arion-ctl/blob/main/docs/standalone-walkthrough.md). 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](@/docs/operate/xds-control-planes.md) explains the connection.

## Apply a configuration change

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

```yaml,name=backend.yaml
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.

```bash
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:

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

In the operator terminal, attach to the service:

```bash
arionctl shell
```

Enter these Elixir expressions at the IEx prompt:

```elixir
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:

```bash
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](https://github.com/arion-gateway/arion-ctl/blob/main/docs/shell-walkthrough.md) 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](https://github.com/arion-gateway/arion-ctl/blob/main/apps/arion_control_plane/README.md#complete-http-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](https://github.com/arion-gateway/arion-ctl/blob/main/charts/arion-ctl/README.md).

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](@/docs/ai-inference-gateway/overview.md) for the request flow and the [inference routing guide](@/guides/inference/inference-routing.md) 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](https://github.com/arion-gateway/arion-ctl/blob/main/docs/configuration-reference.md) for accepted fields and [deployment options](https://github.com/arion-gateway/arion-ctl/blob/main/docs/deployment-options.md) for storage, credentials, and networking. The [architecture post](@/blog/introducing-arion-control-plane.md) explains how the applications fit together.