Run an atoll
An atoll is a group of capsules that share a network namespace, described by a reef.json.
Your first atoll
This is examples/web/reef.json in the repository. It applies unchanged.
{
"name": "web",
"restart": "Always",
"capsules": [
{
"name": "app",
"image": "alpine:latest",
"cmd": ["sh", "-c", "while true; do nc -l -p 8080; done"],
"probe": {
"exec": ["sh", "-c", "echo x | nc -w 1 127.0.0.1 8080"],
"period_seconds": 2,
"failure_threshold": 3
}
},
{
"name": "sidecar",
"image": "alpine:latest",
"cmd": ["sleep", "300"]
}
]
}Start the daemon, apply the file, and watch it settle. The output below is what a run printed.
$ coraild &
$ recify apply -f examples/web/reef.json
atoll/web applied
$ recify get atolls
NAME READY STATUS RESTARTS AGE
web 2/2 Running 0 6s
$ recify describe atoll web
Name: web
Namespace: default
Phase: Running
Restart: Always
Net: none
Capsules:
app:
Image: alpine:latest
State: running
Ready: true
Restarts: 0
sidecar:
Image: alpine:latest
State: running
Ready: true
Restarts: 0
Events:
6s Adopted atoll accepted
6s Started at-web-app
6s Started at-web-sidecar
$ recify exec web -c sidecar -- echo hi
hi
$ recify delete atoll web
atoll/web deletedThe two capsules reach each other over loopback. coraild runs app's probe every 2 s. Three failures in a row kill and restart the capsule. sonar shows the same table live.
Fields
Unknown fields are ignored. recify apply rejects a file that breaks a rule below and prints the reason.
Atoll
| Field | Type | Default | Meaning |
|---|---|---|---|
name | string | required | The atoll name. Only a-z A-Z 0-9 - _ . are allowed. |
namespace | string | "default" | Label-style namespace. recify get atolls shows "default" unless you pass -n. |
restart | Always | Never | OnFailure | "Always" | Restart policy. Repeated crashes back off 1 s, 2 s, 4 s, up to 300 s. |
net | none | host | bridge | "none" | corail run --net. Capsules of one atoll share one network namespace. |
publish | string[] "host:capsule" | [] | corail run -p. Only with net "bridge", which needs root. |
termination_grace_period_seconds | number | 5 | corail stop --grace. |
volumes | Volume[] | [] | Named volumes, mounted by volume_mounts. |
init_capsules | Capsule[] | [] | Run to completion before the capsules start. Names must differ from capsule names. |
capsules | Capsule[] | required | At least one. |
Capsule
| Field | Type | Default | Meaning |
|---|---|---|---|
name | string | required | Unique inside the atoll. The corail id is at-<atoll>-<capsule>. |
image | string | required | Any registry reference, pulled if not cached. |
cmd | string[] | image Cmd | The part after -- in corail run. The image Entrypoint still runs. |
env | string[] "K=V" | [] | corail run -e. |
secret_env | string[] "K=V" | [] | Written to a 0600 file and passed as -e, so the value is not in the process list. |
liveness | Probe | none | Failing past failure_threshold kills and restarts the capsule. |
probe | Probe | none | The older name of liveness. liveness wins when both are set. |
readiness | Probe | none | Gates the READY column. |
startup | Probe | none | Runs first, for slow starters. |
volume_mounts | {name, mount_path, read_only}[] | [] | corail run -v. mount_path must be absolute and name must be a declared volume. |
resources | {memory, cpus, pids} | {} | corail run --memory, --cpus, --pids-limit. |
Probe
| Field | Type | Default | Meaning |
|---|---|---|---|
exec | string[] | — | Command run inside the capsule. Exit 0 is healthy. |
tcp | port | — | TCP connect to that port on the capsule loopback. |
http_port, http_path | port, string | —, "/" | HTTP GET on the capsule loopback. |
period_seconds | number > 0 | 10 | Seconds between probes. |
failure_threshold | number | 3 | Consecutive failures before the probe fails. |
initial_delay_seconds | number | 0 | Wait before the first probe. |
Volume
| Field | Type | Default | Meaning |
|---|---|---|---|
name | string | required | A safe path component. Unique in the atoll. |
host_path | string | "" | A host directory. |
files | {path, content}[] | [] | Files the daemon writes for you. path is relative with no "..". A volume needs host_path or files. |
Also in YAML: recify apply -f reef.yaml takes the same fields.