DEV Community: Mario Ezquerro

Building a Hybrid Docker Orchestrator in Go: The Journey from Single VM to Multi-Node Cluster

Mario Ezquerro — Tue, 14 Jul 2026 17:54:10 +0000

What if you could combine the native simplicity of Docker Compose with the decentralized targeting and reliability of HashiCorp Nomad?

Meet Gubernator (or gbnt), a "Goldilocks" container orchestrator written in Go. In this post, I want to share how I took Gubernator from a single-node API to a fully decentralized, multi-node VM cluster with autonomous DNS resolution and local ingress routing—all co-authored alongside Antigravity, Google DeepMind's agentic AI pair programmer.

The Vision: Why Gubernator?

Kubernetes is the undisputed king of container orchestration, but for small-to-medium projects, homelabs, or edge deployments, it represents massive operational overhead. Docker Swarm is simple but lacks fine-grained task scheduling constraints.

Gubernator is designed to fill that sweet spot:

Single Binary Portability: The same gbnt binary acts as the Central Manager (holding the centralized SQLite state) and the Worker Agents.
Central SQLite with Local Cache: Workers run a local cache so that containers keep running and resolving internal routes even if connectivity to the Manager is lost.
Decentralized Ingress & DNS: The cluster leverages a distributed network of CoreDNS and Caddy instances.

The Architecture: Multi-Node Setup

To test the orchestrator realistically, we provisioned three Multipass Ubuntu VMs:

gbnt-manager (192.168.252.8)
gbnt-worker1 (192.168.252.9)
gbnt-worker2 (192.168.252.10)

graph TD
    Host[Mac/Laptop Host OS] -->|Resolves *.gbnt via local resolver| CoreDNS_Manager
    subgraph Manager VM [gbnt-manager: 192.168.252.8]
        CoreDNS_Manager[gbnt-coredns]
        Mgr[gbnt-manager API & DB]
        Caddy_Mgr[gbnt-caddy]
    end
    subgraph Worker 1 VM [gbnt-worker1: 192.168.252.9]
        Agent1[gbnt Agent]
        Caddy1[gbnt-caddy]
        CoreDNS1[gbnt-coredns]
        Cont1[App Containers]
    end
    subgraph Worker 2 VM [gbnt-worker2: 192.168.252.10]
        Agent2[gbnt Agent]
        Caddy2[gbnt-caddy]
        CoreDNS2[gbnt-coredns]
        Cont2[App Containers]
    end

    Mgr -->|Orchestrates| Agent1 & Agent2
    CoreDNS_Manager -->|Synchronizes Records| CoreDNS1 & CoreDNS2
    Caddy1 -->|Routes to local| Cont1
    Caddy2 -->|Routes to local| Cont2

Decentralized Ingress & Localized Caddy Routing

One of the biggest challenges in multi-host networking is how to route web traffic to containers without overloading the Manager.

Instead of routing all external traffic through a single ingress proxy on the Manager, we built a fully decentralized routing scheme:

Decentralized DNS (CoreDNS): When a stack is deployed, Gubernator registers the domain (e.g., hello-app.gbnt) pointing directly to the IP of the Worker VM hosting the container.
Localized Ingress (Caddy): Each VM runs its own independent Caddy Ingress container.
Decentralized Caddyfiles: Caddy on the Manager only manages reverse-proxy rules for containers running locally on the Manager. Worker agents periodically poll the Manager for their assigned tasks and generate a local Caddyfile targeting only their local containers.

This means if hello-app.gbnt is deployed on gbnt-worker2 (192.168.252.10):

The client's browser queries DNS, which resolves to 192.168.252.10.
The browser connects directly to Caddy on gbnt-worker2 on port 80.
Caddy proxies the request to the local container IP (e.g. 172.17.0.2:80).
Zero transit traffic touches the Manager VM.

Co-authoring with Antigravity (Google DeepMind)

What makes this project unique is that 100% of the Go code, GORM integrations, Flutter dashboard widgets, and cluster setups were co-authored with Antigravity, Google DeepMind's agentic AI coding assistant.

Unlike simple autocomplete or chat windows, Antigravity acts as a pair programmer with agentic capabilities:

Debugging Complex Network Behaviors: We encountered an issue where containers connected to multiple Docker networks (like bridge and gbnt-monitor-net) had their IPs concatenated (e.g., 172.17.0.2172.19.0.7). Antigravity traced the container IP extraction logic, proposed a fix, and validated the parser.
Infrastructure Bootstrapping: Antigravity ran Multipass commands to spin up the VMs, transfer Go binaries, configure authorization keys, and join the workers into the cluster via JWT tokens.
Auto-Generating the Flutter Dashboard: Antigravity designed and iterated on the Flutter Web UI, implementing features like a real-time cluster topology map, live task statuses, and a settings dialog containing system metadata and version tags.

Cluster Observability

Observability is built-in. By running gbnt monitor init, the Manager spins up a complete telemetry stack connected via a dedicated network gbnt-monitor-net:

cAdvisor: Exposes hardware and container metrics.
Prometheus: Scrapes metrics from all nodes.
Grafana: Visualizes metrics.
Loki & Promtail: Aggregates logs across all nodes.

Conclusion

Gubernator proves that you don't need a heavy orchestrator like Kubernetes to manage multi-host Docker deployments. By combining Go, SQLite, CoreDNS, and Caddy, we created a lightning-fast, decentralized orchestrator.

Pair-programming with an agentic coder like Antigravity allowed me to focus on high-level architecture while the AI handled refactoring, cross-compilation, VM deployment, and frontend updates.

If you are interested in building lightweight orchestration systems, check out the Gubernator repository and start building!

Have you built or used lightweight orchestrators? Let me know in the comments below!

#devops #docker #golang #ai #pairprogramming #antigravity

Stop Copy-Pasting `dns:` Blocks: Introducing Transparent DNS Injection in Gubernator

Mario Ezquerro — Mon, 13 Jul 2026 06:21:32 +0000

If you’ve ever built a containerized home lab, a multi-host cluster, or an internal development environment using Docker Compose with custom local DNS (like CoreDNS), you know this exact pain point:


yaml
services:
  web:
    image: nginx:alpine
    dns:
      - 192.168.1.100  # Hardcoded CoreDNS IP
  api:
    image: my-api:latest
    dns:
      - 192.168.1.100  # Copied again...
  db:
    image: postgres:alpine
    dns:
      - 192.168.1.100  # And again!

It is repetitive, it litters your configuration files, and if you forget to paste that block or the DNS IP changes, your container is born blind—unable to resolve internal services or talk to the internet.

With Gubernator, we decided to eliminate this boilerplate entirely.

The Solution: Transparent DNS Injection 🪄
Starting with version v2.4.13, Gubernator implements Transparent DNS Injection.

Now, you can deploy your standard, clean, unedited docker-compose.yml file. No custom network configurations, no hardcoded IPs.

yaml
# Standard, clean Compose file. No "dns:" blocks required!
services:
  web:
    image: nginx:alpine
  api:
    image: my-api:latest
  db:
    image: postgres:alpine

Behind the scenes, Gubernator's deployment executor intercepts container creation and dynamically injects the cluster's CoreDNS host IP directly into the container's runtime configuration.

How It Works Under the Hood 
Host IP Auto-Detection: Gubernator automatically detects the Manager Node IP at startup (either via GBNT_HOST_IP or by testing outbound gateway paths).

Dynamic Templating: CoreDNS templates are updated on the fly to handle custom local routing domains (like *.gbnt and *.gbnt.test).
Runtime Interception: During scheduling and task execution, Gubernator intercepts the container host configuration and populates the DNS servers parameter with the dynamically resolved CoreDNS address.

The Result: 0% Boilerplate, 100% Magic 
Your containers are deployed instantly and gain immediate out-of-the-box support to:

Resolve internal service domains seamlessly.
Communicate with the outer internet through your configured upstream forwarders.
Adapt automatically even if the physical IP of your manager host changes.

Get Started 
Gubernator is designed to combine the simplicity of Docker Compose with the scheduling power of Nomad. You can inspect the code, read the documentation, and launch your first cluster today on GitHub:

Gubernator GitHub Repository https://github.com/mario-ezquerro/gubernator

If you find this feature useful, don't forget to drop a ⭐️ on GitHub! What are your thoughts on container DNS management? Let me know in the comments!

Gubernator visual schema.

Mario Ezquerro — Tue, 09 Jun 2026 09:42:18 +0000

Excited to share the latest feature built for Gubernator (gbnt): Visual Stack Topology & Network Schema!

Gubernator is designed as a "Goldilocks" orchestrator—combining the raw simplicity of Docker Compose with Nomad-inspired scheduling and hardware/AI targeting. But deploying complex multi-container stacks means visualization is key to maintaining control.

To bridge this gap, I’ve just integrated a native Web Network Schema & Container Topology Viewer directly into the Gubernator dashboard:

What makes it unique?

Auto-discovered Ingress & Routing: The scheduler parses docker-compose.yml to automatically place a virtual Caddy Ingress node in web-facing services (e.g. n8n, WordPress, Jupyter) and internal sinks/databases (e.g. MySQL, PostgreSQL).

Live Network Context: Every container card details live telemetry—including internal container IPs, host port mappings, and active domains (e.g.ingress.host).

Visual Dependency Mapping: Custom Bézier-curve connection lines are dynamically drawn in yellow/amber to highlight container network relationships and dependencies (like depends_on).

One-Click Multi-Format Export: Perfect for team architecture syncs or DevOps documentation! Diagrams can be instantly exported and downloaded as PNG, JPEG, PDF, or native SVG (automatically adapting to light/dark system themes).

Gubernator continues its journey to simplify local and edge container orchestration. Let me know what you think of this visualization layer!

https://github.com/mario-ezquerro/gubernator/

_ #Docker #Golang #Flutter #DevOps #Nomad #Orchestration #WebDevelopment #SystemArchitecture #Containers

Gubernator E101 examples examples examplesss....

Mario Ezquerro — Mon, 08 Jun 2026 12:30:01 +0000

Gubernator Examples: Hands-On Tutorials

Gubernator features four progressive developer examples designed to walk you from basic container orchestration to advanced AI workloads:

Example 101 — Getting Started (WordPress & MySQL)
Goal: Understand the basics of single-node orchestration.
Stack: A classic multi-container application consisting of a WordPress front-end and a MySQL database backend.
Key Concepts: Persistent Docker named volumes, basic container scheduling, internal CoreDNS resolution (db.wp.gbnt), and initial Caddy Ingress routing.
Example 102 — Load Balancing (Round-Robin Routing)
Goal: Learn how Gubernator handles horizontal scaling and high availability.
Stack: A scaled deployment featuring multiple BusyBox HTTP replicas serving their individual container hostnames.
Key Concepts: Scaling up replicas, automatic target grouping under a single DNS record, and Caddy Ingress configuring native round-robin load balancing across the running replicas under hello.gbnt.local.
Example n8n — AI Automation Stack (RAG & Local LLMs)
Goal: Orchestrate a modern, automated AI agent workflow.
Stack: An automation workspace integrating n8n (workflows), PostgreSQL (backend database), Ollama (local LLM runtime running llama3.2), and Qdrant (vector database for RAG).
Key Concepts: Inter-container communication using CoreDNS, complex service dependencies, transient automated setup tasks (auto-pulling LLM models on startup), and multi-domain Caddy Ingress routing.
Example Jupyter — AI Development Stack (JupyterLab with PyTorch)
Goal: Spin up a fully-equipped machine learning and data science environment.

Stack: A specialized developer workspace running JupyterLab powered by the comprehensive quay.io/jupyter/pytorch-notebook image.
Key Concepts: Managing large Docker image downloads, mounting persistent data scientist workspace volumes, and setting up Ingress reverse proxying for custom/non-standard container ports (port 8888).

https://github.com/mario-ezquerro/gubernator/tree/main/examples https://github.com/mario-ezquerro/gubernator/tree/main/examples

docker #gubernator #examples #orchestration

Examples Gubernator

Mario Ezquerro — Sat, 06 Jun 2026 09:18:33 +0000

Gubernator Orchestrator Update!

Just shipped some major improvements examples to Gubernator (the lightweight Go container orchestrator):

Premium Data Grid UI: Upgraded the Tasks Dashboard to PlutoGrid for interactive column resizing, filtering, and custom actions.
Dynamic Ingress Routing: Fixed port mapping to auto-detect and route traffic to custom container ports (like n8n, Qdrant, Ollama) instead of hardcoding port 80.
AI Automation Stack (n8n + Ollama + Qdrant): Added a complete RAG workflow example with automated LLM pulling and CoreDNS service discovery.
Simplicity of Docker Swarm meets the flexibility of Nomad!

Check it out: https://github.com/mario-ezquerro/gubernator

Gubernator [the kill k8s]

Mario Ezquerro — Tue, 02 Jun 2026 12:55:56 +0000

Why I built an alternative to Kubernetes overkill.

Let’s talk about infrastructure efficiency.

Kubernetes is the undisputed industry standard for container orchestration, and for massive, complex enterprises, it’s irreplaceable. But for small-to-medium deployments or distributed multi-host edge environments, it often feels like an operational nightmare.

You install a massive orchestration layer, only to realize it's still missing the basics for actual operations. To get it production-ready, you have to layer on external tools for Ingress routing, plus a heavy stack for observability, health metrics, and SLOs. Suddenly, your infrastructure consumes more resources than your actual applications.

I believe in radical software minimalism. That’s why I’ve been developing Gubernator (gbnt), an open-source, lightweight distributed container orchestrator written entirely in Go.

Unlike traditional platforms, Gubernator bakes essential Site Reliability Engineering (SRE) and traffic management right into its core architecture:

Native Reverse Proxy: No complex third-party Ingress controllers. Gubernator automatically manages routing—like dynamically hooking up web containers to an Ingress layer (e.g., Caddy)—making exposure seamless and native.

Built-in SRE & Observability: Out-of-the-box support for health monitoring, metrics, and SLO tracking natively leveraging OpenTelemetry and Prometheus.

Zero-Bloat State Management: It swaps out heavy external key-value stores for an embedded, rock-solid SQLite architecture, ensuring multi-host consistency with a near-zero footprint.

Gubernator is designed for engineers who want robust, predictable, and resilient orchestration without the overhead and cognitive load of K8s.

If you are passionate about minimalist backend architecture, systems engineering, or streamlined DevOps, I’d love for you to take a look at the blueprint and documentation:

Explore the project: https://mario-ezquerro.github.io/gubernator/

How do you handle container orchestration for smaller setups? Let’s connect and discuss in the comments!

SoftwareEngineering #GoLang #SRE #DevOps #ContainerOrchestration #OpenSource #SystemsArchitecture #Minimalism

The Kubernetes Overkill: Why I Built a "K8s Killer" for Small Environments

Mario Ezquerro — Fri, 29 May 2026 09:48:30 +0000

Let’s be honest: Kubernetes is the undisputed king of orchestration. But if you are running a small to medium-sized environment, deploying K8s is often like using a sledgehammer to crack a nut. It brings massive resource overhead and operational complexity that most projects simply do not need.

Worse yet, despite its size, Kubernetes isn't actually a complete solution out of the box.

If you want proper SRE management—like native observability, health checks, and Service Level Objectives (SLOs)—you have to bolt on a complex stack of external tools. Need Ingress management to expose your services? You'll have to configure and maintain third-party Ingress controllers just to get traffic flowing.

That architectural bloat led me to advocate for a more minimalist approach. I wanted an orchestrator that provided everything necessary for robust deployments without the massive footprint.

Enter Gubernator: built to be the Kubernetes killer for small environments.

What Makes Gubernator Different?
Gubernator (gbnt) is a lightweight, distributed container orchestrator written entirely in Go. It strips away the unnecessary layers of traditional orchestration and bakes the essential operational requirements directly into its core:

Native SRE & Observability: Instead of treating SRE as an afterthought, Gubernator integrates robust health checks and observability (leveraging OpenTelemetry and Prometheus) directly into the orchestrator.

Built-in Ingress Management: No need to wrestle with external controllers. Gubernator handles your ingress routing natively, simplifying how you expose and manage your services.

True Software Minimalism: By using SQLite for data consistency rather than heavy key-value stores, Gubernator maintains a tiny resource footprint while ensuring reliable state management across multiple hosts.

Developer-Friendly Interface: A clean REST API and an intuitive CLI tool get your containers running securely and efficiently.

If you are tired of the Kubernetes learning curve and the overhead of maintaining tools you barely use, it's time to look at alternatives that prioritize simplicity and reliability.

Check out the repository, documentation, and architecture here: Gubernator on GitHub Pages:

https://mario-ezquerro.github.io/gubernator/

I’d love to hear from the community: at what point do you think Kubernetes becomes too big for its own good? Drop your thoughts in the comments!

Introducing Gubernator: A Minimalist Container Orchestrator Alternative

Mario Ezquerro — Wed, 27 May 2026 06:11:16 +0000

Hey everyone, I'm Mario. Over the past few months, I've been working on a project that I'm really excited to share with the community.

If you've ever felt that Kubernetes (K8s) is a bit too heavy or overwhelming for certain deployments, you're not alone. While K8s is a powerhouse, it isn't always the right tool when you need a streamlined, minimalist approach. That’s exactly why I built Gubernator (gbnt).

What is Gubernator?
Inspired by the efficiency of Roman governance, Gubernator is a lightweight, distributed container orchestrator written entirely in Go. It’s designed to manage containers across multiple hosts efficiently, without the massive resource footprint and complexity of traditional orchestration systems.

Key Highlights:

Simplicity by Design: It features a clean REST API and an intuitive CLI tool (gbnt) to get your containers up and running quickly.
Built for Reliability: SRE principles are a core focus. Gubernator natively integrates robust observability, health checks, and Service Level Objectives (SLOs) leveraging OpenTelemetry and Prometheus.
Efficient State Management: Instead of requiring heavy external key-value stores, it utilizes SQLite to maintain rock-solid data consistency within a minimalist architecture.
Performance-Oriented: Being Go-native, it’s fast, reliable, and perfectly suited for distributed environments or unikernel-inspired deployments.

Gubernator is an exploration into rethinking container management for modern, lightweight infrastructure. It's built for those who advocate for software minimalism and want just the right amount of orchestration without the overhead.

You can check out the documentation and the repository here: Gubernator Docs & Repo:

https://mario-ezquerro.github.io/gubernator/

I’d love to hear your thoughts, feedback, or any questions you might have in the comments. Let's talk about minimalist backend architecture!

The Loading Screen

Mario Ezquerro — Fri, 15 May 2026 08:46:20 +0000

BUILD WITH AI [Antigravity]

Building “The Loading Screen”: A Real-Time Interactive Experience with Google Cloud Run and Anti-Gravity
How we turned pre-event waiting time into a high-bandwidth, 100% stateless interactive game.

The Concept: “Don’t Panic, We’re Caching the Awesome”
We’ve all been there: waiting for a conference talk to start, staring at a static slide. We decided to change that. The Loading Screen is an interactive, real-time web application designed to turn pre-event “lag” into an analog networking experience.

It consists of a massive “Stage View” (projected on the main screen) and a “Mobile Interface” that turns every attendee’s smartphone into a remote controller.

The Architecture: 100% Stateless & Cloud-Native
When building for live events, the two biggest fears are latency and sudden traffic spikes. To solve this, we designed the system to be completely stateless, optimized for the serverless nature of Google Cloud Run.

Key Tech Stack:
Backend: Node.js 20+ with Express.
Real-Time: WebSockets via Socket.io for sub-millisecond interaction.

Deployment: Dockerized containers on Google Cloud Run.
Scaling: Designed to scale horizontally. Since it operates entirely in memory, it eliminates database bottlenecks during the high-intensity “shaking” phase of the game.

Core Components

The Stage View (The Visual Centerpiece) The Stage View is a retro-futuristic canvas inspired by 8-bit hacker culture and circuit board aesthetics.

The I/O Portal: A moving digital gateway acting as a 3D vanishing point.

loading-screen.fiware.app

The “Muggle March”: When a user launches a “Muggle” (a pixel-art character) from their phone, it appears on the big screen and marches toward the portal, shrinking in size to create a depth effect.

Dynamic QR Integration: The screen automatically generates a QR code so attendees can jump into the action instantly without typing a URL.

2. The Mobile Interface (Launch Control)
We wanted a “zero-install” experience. No App Store, just the browser.

Shake-to-Launch: Leveraging the HTML5 DeviceMotion API, users physically shake their phones to "throw" their character onto the big screen.
Anti-Gravity Feel: The integration with motion sensors provides a tactile, “anti-gravity” sensation as if the phone is pushing the character into the digital space.
Customization: Users can add a 25-character message that floats above their character, creating a real-time, anonymous chat-bubble parade.

Deployment & Scalability on Google Cloud
By using Google Cloud Run, we achieved a “Pay-as-you-go” model that is perfect for events. The application stays at zero cost until the event starts, then scales instantly as hundreds of attendees scan the QR code.

Become a Medium member
The container is bound to the $PORT environment variable, making it fully compatible with Cloud Run’s managed runtime.

Running it locally
If you want to experiment with this setup, you can run the Dockerized version in seconds:

Bash

Build the lightweight Alpine image

docker build -t loading-screen .

Run the container

docker run -d -p 8080:8080 -e PORT=8080 --name loading-screen-app loading-screen

Lessons Learned
Building The Loading Screen taught us that:

State is the Enemy of Scale: Keeping the app in-memory and stateless allowed us to handle connections without worrying about DB latency.

Permissions Matter: Modern mobile browsers (especially iOS 13+) require explicit user consent for motion sensors. A “Ready to Launch” button is essential for the UX.

Visual Feedback is King: In a crowded room, seeing your specific character appear instantly on a 20-foot screen creates a powerful “wow” moment.

Check out the Project
The project is fully open-source. We encourage you to fork it, add new “Muggle” characters, or adapt it for your own tech meetups!

to probe:

loading-screen.fiware.app

Repository: https://github.com/mario-ezquerro/loading-screen
Keywords: #GoogleCloud #NodeJS #WebSockets #GameDev #CloudRun #Serverless