Application YAML (v3)

The canonical Application format used by edgible stack deploy. One YAML document describes one application; multiple documents in a single file are separated by ---.

Top level

apiVersion: v3
kind: Application
metadata: { ... }
spec: { ... }

Field	Required	Type	Notes
apiVersion	yes	v3	The only supported value today.
kind	yes	Application	The only supported value today.
metadata	yes	object	See Metadata.
spec	yes	object	See Spec.

Metadata

metadata:
  name: my-app
  organization: <org-id>
  dependsOn: [other-app-name]   # optional

Field	Required	Type	Notes
name	yes	string	Unique within the organization. Lowercase, alphanumeric, hyphens.
organization	yes	string	Your organization ID. Find with edgible config list.
dependsOn	no	string[]	Names of other applications that must be deployed before this one.

Spec

spec:
  placement: { ... }
  workloads: [ ... ]
  storage: [ ... ]    # optional
  access: [ ... ]     # optional but typical

spec.placement

placement:
  strategy: serving-device
  deviceSelector:
    deviceName: my-first       # OR
    deviceId: dev_a1b2c3d4
  gateway:                      # optional — pin to a specific gateway
    deviceName: eu-gateway

Field	Required	Type	Notes
strategy	yes	enum	serving-device is the only supported value today (the cloud strategy is on the roadmap).
deviceSelector.deviceName	one of	string	Pin to a device by its name.
deviceSelector.deviceId	one of	string	Pin to a device by its ID. Mutually exclusive with deviceName.
gateway	no	object	Override the automatic gateway choice. Same selector shape as deviceSelector.

spec.workloads[]

A list of one or more workloads. Common fields apply to every type:

workloads:
  - name: api
    type: compose | docker | managed-process | vm | pre-existing
    ports: [ ... ]
    storage: [ ... ]      # optional
    env: { ... }          # optional
    dependsOn: [ ... ]    # optional, names of other workloads

Field	Required	Type	Notes
name	yes	string	Unique within the application.
type	yes	enum	One of compose, docker, managed-process, vm, pre-existing.
ports	usually	array	Ports the workload listens on.
storage	no	array	Storage volumes from spec.storage to mount.
env	no	map	Environment variables, string keys to string values.
dependsOn	no	string[]	Names of other workloads to start first.

type: compose

- name: api
  type: compose
  composeFile: ./api.compose.yml

Field	Required	Type	Notes
composeFile	yes	string	Path to a Docker Compose file, relative to the application YAML.

type: docker

- name: redis
  type: docker
  image: redis:7-alpine

Field	Required	Type	Notes
image	yes	string	A pullable image reference.

type: managed-process

- name: worker
  type: managed-process
  command: ["./bin/worker"]
  workingDir: /opt/app
  logFile: /var/log/edgible/worker.log

Field	Required	Type	Notes
command	yes	string[]	argv. No shell expansion.
workingDir	no	string	CWD for the process. Defaults to the agent’s working directory.
logFile	no	string	Where stdout/stderr are written.

type: vm

- name: legacy
  type: vm
  vmBackend: qemu
  diskImage: /var/lib/edgible/vms/legacy.qcow2
  memory: 2048
  cpus: 2

Field	Required	Type	Notes
vmBackend	yes	enum	qemu today.
diskImage	yes	string	Path on the device to a qcow2 disk image.
memory	yes	number	MiB.
cpus	yes	number	Virtual CPUs.

type: pre-existing

- name: legacy-svc
  type: pre-existing
  hostPort: 8080

Field	Required	Type	Notes
hostPort	yes	number	A port already listening on 127.0.0.1 on the device.

spec.workloads[].ports[]

ports:
  - { name: http, containerPort: 8080, protocol: tcp }

Field	Required	Type	Notes
name	yes	string	Used by access entries to reference this port.
containerPort	yes	number	The port number the workload listens on.
protocol	no	enum	tcp (default) or udp.

spec.storage[]

storage:
  - { name: pgdata, type: persistent, size: 20Gi, mobility: device-bound }

Field	Required	Type	Notes
name	yes	string	Referenced by workloads[].storage[].name.
type	no	enum	persistent (default) or ephemeral.
size	no	string	A size like 20Gi, 500Mi.
mobility	no	enum	device-bound (default). Cloud-class mobility on the roadmap.

spec.access[]

access:
  - name: public
    type: https | http | tcp | udp
    target: { workload: <workload-name>, port: <port-name> }
    hostname: { generated: true } | { custom: <fqdn-or-list> }
    tls: { managedBy: edgible }
    listenPort: 443       # optional override
    publish: true         # optional, defaults to true
    policies:
      auth: { mode: none | org | api-key | short-code }

Field	Required	Type	Notes
name	yes	string	Unique within the application.
type	yes	enum	https, http, tcp, udp.
target.workload	yes	string	A name from spec.workloads[].
target.port	yes	string	A port name from that workload.
hostname	https only	object	{ generated: true } or { custom: <fqdn> } or { custom: [<fqdn>, ...] }.
tls	https only	object	{ managedBy: edgible } is the only supported value today.
listenPort	no	number	Override the default port (443 for https, 80 for http).
publish	no	bool	If false, the route is configured but not exposed publicly. Defaults to true.
policies.auth.mode	no	enum	One of the four modes documented in Authentication modes.

Multi-document files

You can put several Applications in one file, separated by ---:

apiVersion: v3
kind: Application
metadata:
  name: db
  organization: <org-id>
spec: { ... }
---
apiVersion: v3
kind: Application
metadata:
  name: api
  organization: <org-id>
  dependsOn: [db]
spec: { ... }

edgible stack deploy -f all.yml deploys both, in dependsOn order.