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 deleted

The 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

FieldTypeDefaultMeaning
namestringrequiredThe atoll name. Only a-z A-Z 0-9 - _ . are allowed.
namespacestring"default"Label-style namespace. recify get atolls shows "default" unless you pass -n.
restartAlways | Never | OnFailure"Always"Restart policy. Repeated crashes back off 1 s, 2 s, 4 s, up to 300 s.
netnone | host | bridge"none"corail run --net. Capsules of one atoll share one network namespace.
publishstring[] "host:capsule"[]corail run -p. Only with net "bridge", which needs root.
termination_grace_period_secondsnumber5corail stop --grace.
volumesVolume[][]Named volumes, mounted by volume_mounts.
init_capsulesCapsule[][]Run to completion before the capsules start. Names must differ from capsule names.
capsulesCapsule[]requiredAt least one.

Capsule

FieldTypeDefaultMeaning
namestringrequiredUnique inside the atoll. The corail id is at-<atoll>-<capsule>.
imagestringrequiredAny registry reference, pulled if not cached.
cmdstring[]image CmdThe part after -- in corail run. The image Entrypoint still runs.
envstring[] "K=V"[]corail run -e.
secret_envstring[] "K=V"[]Written to a 0600 file and passed as -e, so the value is not in the process list.
livenessProbenoneFailing past failure_threshold kills and restarts the capsule.
probeProbenoneThe older name of liveness. liveness wins when both are set.
readinessProbenoneGates the READY column.
startupProbenoneRuns 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

FieldTypeDefaultMeaning
execstring[]—Command run inside the capsule. Exit 0 is healthy.
tcpport—TCP connect to that port on the capsule loopback.
http_port, http_pathport, string—, "/"HTTP GET on the capsule loopback.
period_secondsnumber > 010Seconds between probes.
failure_thresholdnumber3Consecutive failures before the probe fails.
initial_delay_secondsnumber0Wait before the first probe.

Volume

FieldTypeDefaultMeaning
namestringrequiredA safe path component. Unique in the atoll.
host_pathstring""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.