Skip to content
Tobby

Connected zones — overview

A passthrough instance is Tobby’s delivered use case (milestone 4, train v0.4.x): a long-lived service standing between two connected network zones. On one side it reads from source registries — directly, or through the enterprise proxy. On the other side it pushes into the zone’s registry, the one your clusters and hosts actually pull from. In between sits its own store and an embedded OCI registry, so the zone can also consume content straight from Tobby itself.

Retriever desired state of the zone re-read each cycle Source registries direct or via proxy Tobby — passthrough store + embedded registry each cycle: re-read → reconcile → push Zone Zone registry Zone clients docker · containerd · helm fetch + verify differential push recipes included pull

Continuous promotion

Section titled “Continuous promotion”

The loop is deliberately simple, and each step is a requirement you can audit:

  1. Re-read the Retriever. At every cycle the instance re-fetches the desired-state document from retriever.source (FR-010) and resolves every listed recipe from the cookbook, honouring version constraints (~, ^, 12.x) at each pass — a patch release lands by being published, with no file to edit.
  2. Reconcile. The destination registry is compared against what the recipes pin. Only what is missing moves.
  3. Push differentially. Blobs and manifests already present at the destination are never re-sent (FR-028). A second cycle over unchanged content transfers zero bytes — the crucible plays exactly that scenario.
  4. Re-verify before every push. Signatures are checked against the local copy before each push, not once at import (FR-033). A store that was tampered with between cycles does not propagate.
  5. Propagate the recipes. The signed recipe artifacts themselves are pushed to the zone’s cookbook alongside their ingredients (FR-034), so the zone’s cookbook always reflects what the zone actually holds — and a further downstream zone can chain from it.

The cycle runs every sync.interval (default 15m). The interval is changeable at runtime from the administration screen and the API without redeploying (FR-013), and that change is audited as sensitive configuration (FR-094). A synchronization can also be triggered by hand, from the recipes screen or with POST /api/v1/sync.

Ingredients land at the destination under their nominal source host — docker.io/library/nginx becomes registry.zone.example/docker.io/library/nginx — with digests and signatures unchanged. Tobby never rewrites and never re-signs content; the naming rule and its consequences for your clients are the subject of Connect your clients.

Prerequisites

Section titled “Prerequisites”
  • A Linux host or a Kubernetes cluster for the instance — see the OS matrix.
  • Two directories on separate volumes: the store (large, refetchable) and the state (small, the backup target). They must not be nested in one another; Tobby refuses to start otherwise.
  • Network reach to the source registries, directly or through a forward proxy, and to the destination registry.
  • A destination registry that accepts nested repository paths — Tobby probes for this before pushing and fails explicitly when it does not (FR-035).
  • A Retriever document and signed recipes in a cookbook. To understand those first, read recipes, cookbook, retriever.

Working through this section

Section titled “Working through this section”

The pages are ordered the way a deployment actually proceeds:

  1. Deploy — Kubernetes (Helm chart or raw manifests), VM packages, the container image, and the first account.
  2. Enterprise network — authenticated proxy, private certificate authorities, and the TLS the instance itself serves.
  3. Zone Retriever and cascade — the desired-state document, and how zones chain without touching recipes.
  4. Connect your clients — why the paths look the way they do, containerd mirrors, GitOps pitfalls, and the OS-package endpoint.
  5. One-off imports — pulling a single image or chart in by reference, outside any recipe.
  6. Operate over time — probes, task tracking and resume, backup, growth, upgrades.

If you have not run Tobby at all yet, the ten-minute install and start path and the first promotion walkthrough are the faster introduction; this section assumes you are past them and heading to production.