mirror of
https://github.com/tiennm99/coolify.git
synced 2026-08-21 08:25:45 +00:00
Andras Bacsai
4938b65f20
Remove active builder flags from dev Lima sync, bootstrap commands, and server capabilities while documenting the v5 control-plane and host-agent boundaries.
102 lines
3.4 KiB
Markdown
102 lines
3.4 KiB
Markdown
# v5 Host Primitives
|
|
|
|
Coolify deploy logic must send explicit primitives to coold through Flux. There
|
|
must be no raw Podman passthrough.
|
|
|
|
This file is the target primitive catalog. Implementations may lag behind this
|
|
catalog; code should only call primitives that exist in the current protocol.
|
|
|
|
## Images
|
|
|
|
| Primitive | Purpose |
|
|
| --- | --- |
|
|
| `images.pull` | Pull an OCI image ref onto a host. |
|
|
| `images.list` | List local images. |
|
|
| `images.delete` | Remove a local image when safe. |
|
|
|
|
## Containers
|
|
|
|
| Primitive | Purpose |
|
|
| --- | --- |
|
|
| `containers.create` | Create a container from an explicit spec. |
|
|
| `containers.start` | Start an existing container. |
|
|
| `containers.stop` | Stop a container with an optional timeout. |
|
|
| `containers.restart` | Restart a container. |
|
|
| `containers.delete` | Delete a stopped or forced container. |
|
|
| `containers.inspect` | Return detailed runtime state. |
|
|
| `containers.list` | Return host container summaries. |
|
|
| `containers.logs` | Stream or read container logs. |
|
|
| `containers.exec` | Run a command inside a container. |
|
|
| `containers.healthcheck.run` | Trigger or read a runtime health check. |
|
|
|
|
`containers.create` must enforce a deny filter for dangerous host options such
|
|
as privileged mode, unsafe host mounts, host networking, and disallowed
|
|
capabilities unless the host is explicitly configured to allow them.
|
|
|
|
## Volumes
|
|
|
|
| Primitive | Purpose |
|
|
| --- | --- |
|
|
| `volumes.create` | Create an idempotent named volume. |
|
|
| `volumes.inspect` | Inspect a host volume. |
|
|
| `volumes.delete` | Delete an unused volume. |
|
|
|
|
## Networks
|
|
|
|
| Primitive | Purpose |
|
|
| --- | --- |
|
|
| `networks.create` | Create an idempotent Podman network. |
|
|
| `networks.list` | List host networks. |
|
|
| `networks.delete` | Delete an unused network. |
|
|
|
|
Bootstrap-created mesh namespace networks are managed by the v5 cluster init
|
|
flow. Per-resource or compose networks are runtime primitives.
|
|
|
|
## Firewall
|
|
|
|
| Primitive | Purpose |
|
|
| --- | --- |
|
|
| `firewall.allow` | Add an allow tuple and persist it. |
|
|
| `firewall.revoke` | Remove an allow tuple by ID. |
|
|
| `firewall.list` | List active/persisted allow rules. |
|
|
| `firewall.reconcile` | Flush and restore firewall state from snapshots. |
|
|
|
|
coold is the sole writer for both firewall planes: iptables for cross-host
|
|
traffic and nft bridge rules for same-bridge traffic.
|
|
|
|
## Service discovery and DNS
|
|
|
|
| Primitive | Purpose |
|
|
| --- | --- |
|
|
| `services.register` | Register this host's container endpoint in Corrosion. |
|
|
| `services.unregister` | Remove an endpoint from Corrosion. |
|
|
| `services.endpoints` | Read known endpoints for diagnostics. |
|
|
| `dns.lookup` | Diagnose internal DNS resolution. |
|
|
| `dns.stats` | Return DNS server status. |
|
|
|
|
## Host facts
|
|
|
|
| Primitive | Purpose |
|
|
| --- | --- |
|
|
| `host.info` | Return host/runtime facts for scheduling and debugging. |
|
|
| `host.stats` | Return CPU, memory, disk, and container stats snapshot. |
|
|
| `host.containers` | Return host container summaries. |
|
|
|
|
## Builder (deferred)
|
|
|
|
Builder is intentionally not part of the active v5 Flux/coold primitive
|
|
surface. Before reintroducing it, add an ADR/API covering scheduling, capacity,
|
|
logs, artifacts, cancellation, restart adoption, and registry flow.
|
|
|
|
## Not primitives
|
|
|
|
These belong in Coolify, not coold:
|
|
|
|
- `deploy.application`
|
|
- `rollback.deployment`
|
|
- `create.preview`
|
|
- `configure.domain`
|
|
- `authorize.user`
|
|
- `send.notification`
|
|
- `render.proxy.config`
|