PnR: Configuration-Intention Driven Container Orchestration with Go's Platform Abstraction

Have you ever wished container orchestration could be more flexible than static dependency chains but simpler than Kubernetes? Meet PnR (Prompt and Response) - a configuration-driven approach that leverages Go's powerful platform abstraction capabilities to orchestrate containers based on actual readiness states rather than simple dependencies.

The Power of Go's Platform Abstraction

Before diving into PnR, let's understand why Go is particularly well-suited for cross-platform container orchestration:

1. Unified Docker API Interface: Go's Docker client library provides a consistent interface across Windows, Linux, and macOS through platform-specific socket connections:

   • Unix systems use /var/run/docker.sock
   • Windows uses named pipes
   • The client.NewClientWithOpts() function automatically handles these differences

2. Native Concurrency Support: Go's goroutines and channels enable efficient container monitoring:

   • Each container's health check runs concurrently
   • The intention loop coordinates multiple containers without blocking
   • Mutex-protected state updates prevent race conditions

3. Cross-Platform Network Handling: Go's net package abstracts platform-specific network details:

   • TCP health checks work identically across operating systems
   • HTTP clients handle platform-specific DNS resolution
   • Port binding uses consistent syntax regardless of platform

The Core Concept: Configuration over Code

PnR orchestrates containers through three key components:

1. Domain configuration (JSON)
2. Platform-agnostic health checks
3. Runtime state management

Let's see this in action with a typical web stack: MongoDB, API Server, and Web Client.

Domain Configuration Structure

{
    "name": "dev_stack",
    "cpuxs": {
        "stack_startup": {
            "design_chunks": [
                {
                    "name": "mongodb",
                    "gatekeeper": {
                        "system_ready": {
                            "prompt": "Is system ready?",
                            "response": ["yes"],
                            "tv": "Y"
                        }
                    },
                    "flowout": {
                        "mongodb_ready": {
                            "prompt": "Is MongoDB ready?",
                            "response": ["yes"],
                            "tv": "Y"
                        }
                    },
                    "health_check": {
                        "type": "tcp",
                        "port_key": "27017",
                        "timeout_seconds": 2,
                        "status_mapping": {
                            "success": {
                                "key": "mongodb_ready",
                                "response": ["yes"],
                                "tv": "Y"
                            },
                            "failure": {
                                "key": "mongodb_ready",
                                "response": ["no"],
                                "tv": "N"
                            }
                        }
                    },
                    "container": {
                        "name": "pnr_mongodb",
                        "image": "mongo:latest",
                        "ports": {
                            "27017": "27017"
                        }
                    }
                }
            ]
        }
    }
}

Platform-Agnostic Container Management

The heart of PnR is its platform-agnostic container management. Here's how it works:

func (il *ContainerIntentionLoop) Execute() error {
    // Create platform-specific network
    _, err := il.dockerClient.NetworkCreate(il.ctx, "pnr_network", types.NetworkCreate{})
    if err != nil {
        return fmt.Errorf("failed to create network: %v", err)
    }

    for {
        // Update runtime state
        if err := il.updateRTStateFromRuntime(); err != nil {
            return err
        }

        allCompleted := true
        anyExecuting := false

        // Process each container
        for i := range il.cpux.DesignChunks {
            chunk := &il.cpux.DesignChunks[i]

            // Container state machine
            switch chunk.Status {
            case "completed":
                continue
            case "executing":
                anyExecuting = true
                allCompleted = false
                if il.checkChunkCompletion(chunk) {
                    chunk.Status = "completed"
                }
            case "", "ready":
                allCompleted = false
                if il.checkGatekeeper(chunk) {
                    if err := il.startContainer(chunk); err != nil {
                        return err
                    }
                    chunk.Status = "executing"
                    anyExecuting = true
                }
            }
        }

        // Check termination conditions
        if allCompleted {
            return nil
        }
        if !anyExecuting && !allCompleted {
            return fmt.Errorf("no progress possible - execution stalled")
        }

        time.Sleep(5 * time.Second)
    }
}

Cross-Platform Health Checks

PnR implements platform-independent health checks using Go's standard libraries:

func (il *ContainerIntentionLoop) checkChunkCompletion(chunk *DesignChunk) bool {
    // Platform-agnostic container status check
    isRunning, err := il.isContainerRunning(chunk.Container.Name)
    if !isRunning {
        il.updateChunkStatus(chunk, false)
        return false
    }

    // Health check based on configuration
    status := false
    switch chunk.HealthCheck.Type {
    case "tcp":
        addr := fmt.Sprintf("localhost:%s", chunk.Container.Ports[chunk.HealthCheck.PortKey])
        conn, err := net.DialTimeout("tcp", addr, timeout)
        if err == nil {
            conn.Close()
            status = true
        }

    case "http":
        url := fmt.Sprintf("http://localhost:%s%s", 
            chunk.Container.Ports[chunk.HealthCheck.PortKey],
            chunk.HealthCheck.Path)
        resp, err := client.Get(url)
        if err == nil {
            status = (resp.StatusCode == chunk.HealthCheck.ExpectedCode)
        }
    }

    il.updateChunkStatus(chunk, status)
    return status
}

Key Benefits

1. True Cross-Platform Support: Works identically on Windows, Linux, and macOS
2. Configuration-Driven: All orchestration logic in domain.json
3. Container Agnostic: No PnR-specific container modifications needed
4. Flexible Health Checks: TCP, HTTP, and extensible to other protocols
5. State Visibility: Clear status updates through runtime files
6. Concurrent Execution: Efficient parallel container management

Getting Started

Full code is available here : Github

Prerequisites

1. Install Go (1.19 or later):

2. Install Docker

Project Structure

pnr-orchestrator/
├── main.go
├── containers.go
├── config/
│   └── domain.json
└── runtime/          # Created automatically

Installation

# Create project directory
mkdir pnr-orchestrator
cd pnr-orchestrator

# Initialize Go module
go mod init pnr-orchestrator

# Install dependencies
go get github.com/docker/docker/client
go get github.com/docker/docker/api/types
go get github.com/docker/go-connections/nat

Building and Running

# Option 1: Direct run
go run main.go containers.go

# Option 2: Build and run separately
go build
./pnr-orchestrator   # Unix/Linux/Mac
pnr-orchestrator.exe # Windows

Beyond Simple Dependencies

Traditional Docker Compose:

api:
  depends_on:
    - mongodb

PnR's intelligent orchestration:

"gatekeeper": {
    "mongodb_ready": {
        "prompt": "Is MongoDB ready?",
        "response": ["yes"],
        "tv": "Y"
    }
}

The key difference? PnR ensures actual service readiness across any platform, not just container startup.

Next Steps

1. Explore more complex orchestration patterns
2. Add custom health check types
3. Implement graceful shutdown and cleanup
4. Create platform-specific optimization hints

PnR demonstrates how Go's strong platform abstraction capabilities can create robust, cross-platform container orchestration tools without sacrificing simplicity or power.

Let me know in the comments if you'd like to see more examples or have questions about platform-specific implementations!