DEV Community

Cover image for Adopt Pre-Existing Docker Containers with Zero Downtime: Reverse-Engineering docker-compose.yml in Gubernator v4.0
Mario Ezquerro for Google Developer Experts

Posted on Originally published at github.com

Adopt Pre-Existing Docker Containers with Zero Downtime: Reverse-Engineering docker-compose.yml in Gubernator v4.0

When you roll out a container orchestrator on a real production Linux server, you rarely start with an empty machine. Most teams face the classic brownfield reality:

  • Containers have already been running for months.
  • Some were launched with docker compose, others manually with docker run.
  • Nobody remembers where the original docker-compose.yml livesβ€”or it doesn't exist at all.
  • And rule #1 of production still applies: you cannot stop or restart live workloads just because you installed an orchestrator.

In Gubernator v4.0, we tackled this exact problem head-on with a native Unmanaged Container Discovery & Zero-Downtime Stack Adoption engine powered by docker inspect reverse-engineering.


🧭 The Goal: Govern Live Workloads Without Breaking Them

Most orchestrators assume a greenfield world: "redeploy everything from scratch using my manifests." In practice, migrating running services usually means scheduling maintenance windows, recreating containers by hand, or painfully reconstructing YAML files line by line from raw docker inspect JSON.

In Gubernator v4.0, brownfield adoption follows a safe, two-phase workflow:

  Production Docker Hosts (Manager + Workers)
                      β”‚
                      β–Ό  1. Non-Intrusive Scan (Zero-Touch)
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚           Unmanaged / Discovered (Cluster-Wide)          β”‚
  β”‚  β€’ Auto-grouped by com.docker.compose.project            β”‚
  β”‚  β€’ Detects standalone containers (docker run)            β”‚
  β”‚  β€’ Day-1 actions: status, start, stop, restart           β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                        β”‚
                        β–Ό  2. Reverse-Engineering (docker inspect)
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚       docker-compose.yml Generator + Interactive YAML    β”‚
  β”‚  β€’ Extracts image, ports, volumes, networks, env, limits β”‚
  β”‚  β€’ Filters image-default env vars via docker image inspectβ”‚
  β”‚  β€’ Optional toggle to read original host compose file    β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                        β”‚
          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
          β–Ό                           β–Ό
  Adopt (Zero-Downtime)        Adopt & Redeploy
  Registers Stack & Tasks      Adopts and redeploys under
  without restarting anything  Gubernator DNS / Load Balancing
Enter fullscreen mode Exit fullscreen mode

πŸ”Ž Step 1: Multi-Node Automatic Discovery (Unmanaged / Discovered)

With Gubernator v4.0's new 3-level collapsible sidebar, Cluster β†’ Legions [Stacks] now provides two dedicated subsections:

  • Managed Stacks: your standard Gubernator-orchestrated stacks.
  • Unmanaged / Discovered: a cluster-wide radar that scans both the Manager (locally) and all Worker Centurions (over SSH) for any running or stopped container not tracked by Gubernator and not belonging to internal system infrastructure (CORE-GBNT, monitoring, etc.).

Smart Automatic Grouping

Instead of dumping a flat, noisy list of containers, Gubernator inspects Docker's native metadata:

  1. Docker Compose Projects (COMPOSE PROJECT): containers created with docker compose already carry com.docker.compose.project, com.docker.compose.service, and com.docker.compose.project.config_files. Gubernator automatically groups them into a single project card showing the detected host YAML path.
  2. Standalone Containers (DOCKER RUN): manually started containers appear under Standalone with multi-select checkboxes, letting you adopt a single container or bundle multiple standalone containers into a brand-new Stack.

πŸ› οΈ Step 2: Reverse-Engineering docker-compose.yml from docker inspect

Clicking Adopt Project as Stack (or Adopt Selected) runs docker inspect on the target host and synthesizes a clean, production-ready docker-compose.yml:

  • Runtime identity: image, container_name, and restart (RestartPolicy).
  • Networking & ports: deduplicated ports (hostIP:hostPort:containerPort) and custom Docker networks automatically declared as external: true.
  • Persistent storage: bind mounts (preserving :ro flags) and named volumes declared as external: true so existing data is never lost.
  • Smart environment cleanup: a common pain point with naive docker inspect generators is dumping dozens of boilerplate image variables (PATH, GOSU_VERSION, etc.). Gubernator cross-references docker image inspect and strips out image-default variables, keeping only real user-configured environment variables.
  • Operations & limits: overridden command, working_dir, user, healthcheck, and CPU/Memory limits (deploy.resources.limits).
  • Bonus β€” Original Host Compose File: if com.docker.compose.project.config_files points to a readable file on the host, the adoption dialog exposes a one-click toggle to switch between the docker inspect reconstruction and the original host docker-compose.yml.

⚑ Step 3: Two Adoption Modes (You Choose When to Restart)

Inside the interactive adoption modal, you can review or tweak the generated YAML (for example, adding depends_on or Load Balancing ingress labels) and choose how to adopt:

  1. Adopt (Zero-Downtime): saves the Stack, RawComposeFile, Services, and Tasks into Gubernator's SQLite state, binding them directly to the live running containers. Zero restarts, zero downtime. The stack immediately appears in Managed Stacks under full Gubernator lifecycle control.
  2. Adopt & Redeploy: registers the stack and immediately triggers a managed Gubernator Redeploy to recreate it with CoreDNS records, Load Balancing routes, or updated configuration.

πŸ§ͺ Live Test: Adopting a 3-Container App (web + api + cache)

On a 2-node cluster (gbnt-manager + gbnt-worker1), we spun up a standalone 3-tier docker compose application completely outside Gubernator:

  • legacy-demo-web (nginx:alpine, port 8095:80, read-only nginx.conf bind mount)
  • legacy-demo-api (hashicorp/http-echo:latest, connected over private network legacy-net)
  • legacy-demo-cache (redis:7-alpine, named volume legacy_redis_data + healthcheck)

Opening Cluster β†’ Legions [Stacks] β†’ Unmanaged / Discovered hits GET /api/unmanaged and immediately detects:

{
  "total_containers": 3,
  "total_groups": 1,
  "groups": [
    {
      "group_key": "node-local-manager::legacy-demo",
      "group_name": "legacy-demo",
      "node_id": "node-local-manager",
      "source_type": "compose",
      "compose_config_files": "/home/ubuntu/legacy-demo/docker-compose.yml",
      "running_count": 3,
      "total_count": 3
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

With one click on Adopt Project as Stack β†’ Adopt (Zero-Downtime), all three interconnected containers become a versioned, editable Gubernator Stackβ€”without dropping a single request.


πŸ›οΈ REST API Endpoints

For automation and CI/CD pipelines, the entire workflow is exposed behind Gubernator's RBAC layer:

Endpoint Method Description
/api/unmanaged GET Scans Manager and Workers for external containers, grouped by Compose project or standalone.
/api/unmanaged/generate-compose POST Reconstructs docker-compose.yml from docker inspect (or loads the original host Compose file).
/api/unmanaged/adopt POST Registers the Stack, Services, and Tasks with Zero-Downtime without restarting live containers.
/api/unmanaged/action POST Day-1 lifecycle actions (start, stop, restart, rm) on unmanaged containers.

πŸš€ Wrapping Up

With unmanaged discovery and zero-downtime adoption, installing Gubernator on existing Docker servers stops being a risky migration and becomes a smooth, incremental transition:

  1. Install Gubernator without touching running workloads.
  2. Discover every Compose project and docker run container across your nodes.
  3. Reconstruct & review clean docker-compose.yml manifests automatically.
  4. Adopt services into managed stacks with zero downtime.

Have you ever had to reconstruct a lost docker-compose.yml in production from raw docker inspect output? Drop your war stories in the comments!

Top comments (4)

Collapse
 
kursatyz profile image
KΓΌrşat YΔ±lmaz •

Reverse-engineering docker inspect into declarative Compose YAML walks a tightrope between preserving implicit daemon defaultsβ€”like IPAM leases, log drivers, and network aliasesβ€”and freezing transient runtime env vars into static config. True zero-downtime adoption hinges on whether the synthesized manifest's config hash aligns with the live container so the first managed reconcile stays a strict no-op instead of triggering a recreation cascade. Runtime state rarely equals intent.

Collapse
 
gautamtalksdev profile image
Gautam K •

Adopting existing containers without restarting them is a hard problem and a good one to solve, since most teams can't afford the downtime to migrate. How do you handle containers that were started with flags the tool doesn't understand?

Collapse
 
prascli profile image
Indra Prasetya •

The docker inspect β†’ compose reconstruction approach matches what we hit in our homelab: mixed docker run and docker compose deployments across nodes, with no surviving compose files for the docker run workloads.

One concrete gap we ran into: docker inspect on a docker run container doesn't preserve the original --network alias names β€” only the network IDs. Reconstructing a portable docker-compose.yml then requires correlating those IDs back to the host's docker network ls output, which isn't always stable across reboots. Gubernator's "external: true" network handling is the right call there.

Also, the com.docker.compose.project.config_files label is only present on Compose v2 projects; legacy v1 projects and manual docker run lack it entirely, so the "original host compose file" toggle covers a narrower set than the discovery scan.

Collapse
 
upordownonline profile image
upordown.online •

Declaring named volumes as external is the right call. One case worth testing is anonymous volumes: an image with a VOLUME line, like the official Postgres one, run without -v gets a volume with a random hash name. If the generator treats that as image-default and leaves it out, the first compose up after adoption mounts a fresh empty volume and the data looks gone, even though it is still on disk. Mapping those hash-named mounts to external volumes by name would close that gap.