Volumes and Networks

Volumes and networks

Both sit with Containers in the sidebar, because that is what they are for. Both get the same list as every other section: rows with a checkbox, Sort, filter, a hover action and ⋮, and the selected item's page beside the list. See Views and filtering.

Each has a detail screen of its own — Details… on the row, or Inspect to go straight to the authoritative record, with the options, labels and addressing the runtime actually holds rather than the summary the row shows. Both also have a Copy submenu on the row.

Once a host is paired, both lists include each host's volumes and networks, with a host chip on the row and a Host filter, and the create forms gain Create on. A volume or a network belongs to one Mac: a container mounts the volumes on its own Mac, and the same network name on two Macs is two separate private networks.

Volumes

A volume is storage that outlives the container using it. Without one, everything a container writes disappears when it is removed.

New Volume… in the Volumes toolbar's + menu, or File ▸ New Volume…. A volume needs only a Name, and the name is validated as an identifier before anything runs. The rest is optional:

• Size, a number with an optional K, M or G suffix. Left empty, the driver provisions 512 GiB as a sparse image. It does not consume that — but it is what the size reports, which is why an untouched volume looks alarming in the list.
• Labels and Driver options, up to eight each, as key=value. Nothing reads labels but you and whatever you script; what driver options mean is the driver's business.

Delete removes one. When Confirm destructive actions is on it asks first, naming the volume rather than saying "this item" — a volume is exactly the kind of thing you do not want to delete the wrong one of. Deleting several always asks.

The empty state reads "Create one to persist data across container runs." — it says what a volume is for, on the assumption that if you have none you may not yet know.

Using one

In the run form's volume field:

shared-data:/data          a named volume, mounted read-write
shared-data:/data:ro       read-only
/srv/shared:/host:rw       a folder on this Mac

A named volume is always allowed; the runtime namespaces it and it exposes nothing of the Mac's filesystem. A host path is a bind mount, and who may use one depends on who is asking. Running a container on This Mac, you are its owner, and any absolute path except / is accepted. A request from an admin Mac is held to named volumes only by the host's own mount policy, so a container run on a host can never mount a folder from either Mac. See Security model.

A fresh named volume mounts owned by root, with a lost+found in it. An image that runs as a non-root user and does not fix that itself — Redis is one — fails to write to it, and the container stops. The group form warns about this beside its Volumes field.

A decoding note worth knowing

container volume inspect and volume ls nest their real payload under configuration and status. An early hand-written fixture flattened it, which matched the models but not reality — so the decoder threw the moment a real volume existed, with a green test suite throughout.

Every fixture in this project is now captured from the live CLI. It is the single most useful rule here.

Networks

A network gives a set of containers their own isolated addressing, so they can reach each other without publishing ports to your Mac. They reach each other by address unless a DNS domain is in use for containers; see DNS.

New Network… in the Networks toolbar's + menu. The form has:

• Name — how you attach a container to it in the run form.
• Addressing — IPv4 or IPv6. They are independent and each takes its own subnet, which is why they are not offered in one column.
• Subnet, in CIDR notation. Left empty, a private range is assigned. For IPv6, use a unique-local prefix (fd00::/8); a globally routable prefix you do not own will not behave.
• Isolation — Host-only — no external access keeps the containers talking to each other and to nothing else, the right default for a database only its own app should reach.
• Labels, Plugin and Plugin options, expanded rather than behind a disclosure triangle, because hiding three short controls mostly hides that they exist.

The detail view shows addressing — the subnet and gateway the runtime assigned, which network ls does not always return.

Delete removes one, asking first when Confirm destructive actions is on. The built-in network cannot be deleted, and its delete button is disabled rather than spinning forever — an early version passed "you cannot delete this" as the busy flag, so the button span indefinitely, claiming the app was working when it was actually refusing. Busy and unavailable are different states and now have separate parameters. A bulk delete leaves the built-in network out of the batch rather than failing on it.

The empty state reads "Create one to give containers an isolated network."

When a network loses its connection

Sometimes a running container's network loses its link to the Mac: the network's gateway is no longer one of the Mac's own addresses. Its containers can still reach each other, but not the Mac or the internet, and their published ports stop answering. The container says it is running and cannot be reached — the hardest kind of fault to read.

It is a known container bug (apple/container#2051), so Flotilla names it where the symptom shows: a banner in Networks and Containers names the network, the cause and the one fix. About the Bug opens the issue. Restart container… fixes it, and asks first: every running container stops and is not started again automatically, so start them afterwards — groups from their rows. It is also a notice; see Notifications.

The banner waits until both lists have loaded, so a slow refresh never raises a false alarm.

Push to Hosts

Push to Hosts… is on the row menu of a volume or network on This Mac. This Mac's item is the definition; the push creates the same thing on the hosts you tick. Before anything runs, each host says what a push would do there:

• will create — for a volume, will create, empty;
• already has it, the same;
• differs, with how, and left as it is;
• not answering.

Only the first can be ticked. A host whose copy differs is reported and left alone, because replacing a volume deletes its data and replacing a network detaches its containers. That is a decision for someone looking at that host, not something a push should do on the way past.

A push copies a definition, not contents. A pushed volume is empty on every host; no file in it moves. The built-in network has no Push.

Each Mac's address block

A pushed network does not take This Mac's subnet. Every Mac in the fleet is given its own /20 from 10.240.0.0/12 — room for 256 Macs with sixteen /24 networks each — and a pushed network gets the first free /24 in that host's block, shown per host in the push form's Subnet list.

Networks of the same name on two Macs are separate private networks. Giving each Mac its own range keeps them from ever overlapping, which letting each runtime choose cannot promise. A block is never handed out on top of one of this Mac's interface ranges — the office LAN, a VPN — or a subnet any Mac already uses. When a host's sixteen are taken, the push says no free subnet is left.

Flotilla does not join those networks together. Not yet: tunnels and an overlay network between Macs are planned for 2.0.

Details and filters

Networks filter by built-in or user-defined and carry Mode, Subnet, Gateway and Created. Volumes carry Format, Driver, Capacity and Created. Both have Tags, Host and On hosts — the last on This Mac's rows, saying how many of the hosts that answered have one of the same name.