Solana / Agave Automation
The automation responsibilities required to create and operate a private Agave cluster safely.
Automation should encode the operational sequence, not merely copy a validator startup command onto a host. A host-and-systemd deployment and a Kubernetes StatefulSet deployment need the same control points, but implement them differently.
The Agave private-devnet role is a reference implementation for the host-and-systemd path. It generates development keypairs on target hosts when none are supplied; use externally managed secrets for any persistent key material.
Automation phases
| Phase | Required result |
|---|---|
| Host preparation | Dedicated service user or container security context, required packages, directories, storage mounts, kernel limits, and firewall policy. |
| Key handling | Protected configuration directory; supplied key material written with owner-only permissions or generated according to the agreed custody model. |
| Genesis | Bootstrap-only creation of the ledger and program arguments; never rerun when a valid genesis exists. |
| Service installation | An explicit systemd unit for a host deployment, or a StatefulSet/container command for Kubernetes, with identity, vote, ledger, accounts, gossip, RPC, and dynamic-port configuration. |
| Follower configuration | Bootstrap entrypoint, trusted validator identity, expected genesis hash, and follower-specific behavior. |
| Faucet | Optional, separately scoped service with its own keypair and bounded request policy. In Kubernetes, use a separate Deployment. |
| Verification | Cluster version, slot progression, and validator health checks after deployment. |
Idempotency rules
The most important protection is to make destructive operations explicit. A normal automation run may create missing directories, configure limits, or restart a service. It must not silently replace existing keys, wipe ledger/accounts data, or recreate genesis.
Required variables
Document and review at least:
- service user and base/config/ledger/accounts paths;
- bootstrap or follower role;
- image/client version and upgrade policy;
- bind address, gossip port, RPC port, and dynamic UDP range;
- bootstrap entrypoint, trusted validator identities, and expected genesis hash;
- ledger retention and snapshot policy;
- whether a faucet is enabled and its request limits.
Deployment verification
Automation should fail the deployment if the validator cannot return a cluster version or if the slot does not advance across a short sample window. Add an equivalent slot-progression readiness gate before treating Kubernetes rollout success as cluster readiness.
See Private Cluster Topology and Networking and Trust for the operational meaning of those inputs.