quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Contributor’s guide

19. From desired state to a real container

An ARM PUT cannot directly become a shell command. Quinzee first validates and persists a resource model. A separate controller translates a bounded desired state into Docker operations. This separation is both an implementation boundary and the reason an ARM resource can exist while its runtime is not ready.

Follow the handoff through files

ARM caller -> provider -> private resource record
                         -> requests/<instance>.json
operator-run helper -> validate schema/revision -> Docker CLI -> Docker daemon
                    -> probe real protocol/TLS
                    -> status/<instance>.json
provider -> accept matching revision/status -> API and DNS/gateway readiness

Engine mailboxes live under <data-dir>/engine-runtime; hosting mailboxes under <data-dir>/functions-runtime, including App Service. These are files shared through the operator's selected paths or mounts, not network message queues. Their credential-bearing contents stay private. The helpers publish documents through temporary-file flush/replace operations so readers see complete records.

A revision identifies the desired incarnation of a resource. If an old probe finishes after a settings change, its success must not certify the new revision. The provider compares status to current desired state and applies freshness checks. Engine diagnostics also have a separate two-second heartbeat writer, so a slow operation and a dead supervisor can be distinguished. Hosting reports timestamps with reconciled status; do not assume it uses the same heartbeat file. A Running hosting status older than 15 seconds or more than five seconds in the future loses its routing address. An outstanding change has a 180-second provisioning deadline. These are current implementation bounds, not a distributed clock-synchronization guarantee.

Understand controller ownership

The engine helper derives an owner identifier from the resolved mailbox path. Its default private state is outside the cloud data mount. Both runtime helpers take a nonblocking exclusive flock on their private helper lock file. The lock is held by an open file description and released on process exit; the continued existence of the lock filename does not prove that the lock is held.

Docker ownership labels identify the helper and resources it may reconcile. The helper inspects labels before adopting or removing objects. Do not start a second controller with a different private-state directory against the same mailboxes, or rewrite labels to bypass a mismatch. Moving paths can change owner hashes and the objects a helper expects to find.

The Python process invokes the Docker CLI with structured argument lists. The CLI talks to the Docker daemon selected by the operator's context. With a remote daemon, bind-mount source paths refer to that daemon's filesystem, which may not be the controller's filesystem. The standard lab assumes the matching local Docker host. Access to the daemon is a privileged operator capability even when the Python process itself is non-root.

Native engine creation, step by step

  1. Validate the fixed schema, supported engine kind, names, image identity and desired action. ARM input cannot choose arbitrary Docker flags or executables.
  2. Establish ownership-labelled volume/container state. Prepare engine-specific configuration, credentials and TLS material outside the cloud mount.
  3. Run the pinned PostgreSQL, MySQL or Valkey image with its prescribed user, network, mounts and limits: 1 GiB memory, two CPUs and 256 processes.
  4. Probe the native protocol over verified TLS. Creating a container is not a successful database query.
  5. Record status and actual network address. The provider's DNS contribution points clients at that engine address.

Data lives in engine volumes, not solely in ARM JSON. PostgreSQL has its own WAL, MySQL its own engine recovery, and Valkey its configured append-only persistence. The engine helper also owns a CA and a bridge-reachable CRL responder. Stopping the helper can leave databases alive while removing that responder and stopping reconciliation/heartbeat updates.

The helper's stop action stops an owned SQL container while preserving volume data. Delete is different: it can remove the owned volume and private runtime credentials. Resource-group deletion can initiate that sequence. It is not a general container backup or volume-adoption API.

Functions and web-host creation, step by step

The hosting registry maps an operator-approved image name to an immutable local image ID. The helper uses --pull=never; provisioning cannot fetch arbitrary code from a registry. Functions overrides the image entrypoint to start the real Functions host. App Service uses the approved image's own entrypoint.

The workload runs as the helper's numeric UID/GID, with a read-only root, dropped capabilities, no-new-privileges, and fixed CPU/memory/process limits. Writable tmpfs mounts provide /tmp and /home/LogFiles; their content is ephemeral. Private generated files supply TLS, trust, settings and host secrets. An ordinary application gets no Docker socket or cloud bootstrap credentials.

The helper injects settings through a private environment file. Those values become process environment inside the container; they are not magically hidden from the Docker administrator. Avoid unrestricted docker inspect or /proc/<pid>/environ dumps when investigating a failure.

Functions readiness uses a verified host-status request with the private master key. Web readiness checks / over TLS on 8443. Once ready, the cloud gateway makes its own verified upstream connection using the correct constrained CA. Functions admits bounded /api/... traffic and leaves function-key enforcement to the real host. Web hosting forwards normal paths and leaves application login to the application.

A managed identity attachment causes the helper to inject a private workload header and HTTPS token endpoint. The endpoint checks the header and the actual site attachments, then issues a token for the selected principal. The header is a credential, not an Azure resource ID. Identity attachment alone grants no resource access; authorization still depends on assignments.

Separate revision replacement from graceful application draining

The hosting helper removes an existing owned container when the revision changes, the action is not start, or the image is cleared. This path uses forced container removal; it does not promise application-level request draining. Settings changes can therefore interrupt in-flight work. Store durable application data in a real service and design message consumers for retries.

Stopping the hosting helper leaves existing containers alone. Unloading App Service blocks its gateway but can leave its process running. A Functions Service Bus trigger can keep consuming independently of the public HTTP gateway. To stop execution, submit the supported app Stop operation while its helper is running and wait for the resulting status.

Observation Meaning to check
Resource exists, no container Missing helper, wrong paths, rejected request or unapproved image
Container running, resource not ready Protocol probe, TLS, credentials, revision or timestamp
API stopped, messages still consumed Gateway/module stopped but workload container still alive
New helper cannot adopt an old container Ownership/path/private-state mismatch
Data missing after Delete Destructive resource lifecycle, not a controller restart

This model explains why backups need cloud state, dedicated directory data, engine volumes and helper private state together. Copying only the ARM resource record cannot recreate the contents of an external database.