RFC-2: Deploy Spec
Abstract
The Deploy Spec defines a declarative YAML format for where a blueprint runs and how each of its deployments is configured. One file declares every environment a blueprint deploys to: its cluster, interfaces, variables, models, schedules, knowledge bindings, and compute. The CLI deploys the file with ast deploy -f, and a connected GitHub repository deploys it after each build.
Changelog
Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
1. Introduction
A Deploy Spec file (astropods.deploy.yml) is a YAML document that sits beside astropods.yml. The Blueprint Spec describes how to build the agent. The Deploy Spec describes where it runs.
The file deploys the blueprint named in the astropods.yml in the same directory, so it names no blueprint itself. Each environment in the file maps to one deployment of that blueprint.
The file is the reviewed, versioned record of deploy settings. Commit it with the code, and every deploy from it is repeatable.
The spec does not cover access grants. A first deploy gets the default grants, and the agent’s Access tab changes them.
2. Top-Level Structure
A conforming document MUST contain the following top-level fields:
An environment name is the name of an environment in the account. If the environment doesn’t exist, the deploy creates it. An empty entry (staging: {}) deploys with the current values, or the defaults on a first deploy.
3. Environment
Every field in an environment is OPTIONAL. A field the file leaves out keeps the deployment’s current value on a redeploy, and the default on a first deploy.
3.1 Public
public MUST appear only in an environment that also sets interfaces.
A public web interface has no signed-in user, so its access becomes anyone. A redeploy that makes web public replaces the web grants with anyone and records the change in the audit log.
3.2 Variables
A variable is either a literal value or a reference to a secret:
A variable the blueprint marks as secret MUST use ref. The deploy refuses a literal value for it, so a secret never lands in the file.
4. Resources
resources sizes each component. Each entry MUST set sizing, so the file always states who sizes the component.
4.1 Compute
A Size has cpu and memory, with the same format as above.
sizing: fixedsets the size and turns the autosizer off. A redeploy keeps that size instead of the one the autosizer chose.sizing: autolets the platform size the component, within optionalminandmaxbounds.
5. Deploying
Two tools deploy the file. Both MUST deploy only the environments described here, and MUST leave out of the request every field an environment omits.
A GitHub build reads astropods.deploy.yml from the directory that holds astropods.yml, at the pushed commit.
6. Validation Rules
Implementations MUST enforce the following validation rules:
specMUST equaldeploy/v1.environmentsMUST name at least one environment.- An environment name MUST be 1 to 64 characters, with no leading or trailing spaces.
branchMUST NOT have leading or trailing spaces.- Each entry in
interfacesMUST beweb,slack, ormesh. publicMUST NOT be set unlessinterfacesis set in the same environment.- Each variable MUST be a non-empty value or
{ ref: NAME }, whereNAMEis not empty. Arefmapping MUST contain no other key. - A secret variable MUST use
ref. This rule is checked at deploy time against the blueprint’s variables. - Each
resourcesentry MUST setsizingtofixedorauto. sizing: fixedMUST setcpuormemory, and MUST NOT setminormax.sizing: autoMUST NOT setcpuormemory. Aminormaxit sets MUST setcpuormemory.- The file MUST contain exactly one YAML document. Unknown fields anywhere in the document are rejected.
- The file MUST NOT exceed 64 KiB.
Validation runs offline. It does not check that a cluster, variable, model, or knowledge store exists; the deploy reports those.