Deployment Planner

Deployment Planner Skill

Deterministic, compute-aware service placement engine for multi-node container clusters.

Overview

This skill automates the process of determining which services should run on which hardware nodes by:

1. Discovering available hardware resources across all cluster nodes
2. Cataloging all deployed (and planned) services with their resource profiles
3. Classifying services into operational tiers with HA requirements
4. Running a placement scoring algorithm to find optimal assignments
5. Generating migration plans including volume data movement
6. Producing a reusable "golden deployment" blueprint

Prerequisites

Configuration

Steps

Step 1: Hardware Discovery

Collect compute resources from every reachable node in the cluster inventory.

Data Collected Per Node:

Output Format:

{
  "nodes": [
    {
      "hostname": "compute-a",
      "address_ref": "connection://inventory/compute-a",
      "cpu_model": "Example Processor",
      "cpu_cores": 16,
      "ram_total_gib": 64,
      "ram_available_gib": 48,
      "disk_total_gb": 500,
      "disk_available_gb": 350,
      "disk_used_pct": 30,
      "architecture": "x86_64",
      "swarm_role": "leader",
      "labels": {"workload-class": "general"},
      "gpu": null
    }
  ]
}

Step 2: Service Catalog

Enumerate all running and configured services with their resource profiles.

For each service, determine:

Resource Estimation Heuristic:

When explicit resource limits aren't set, estimate using these defaults:

Step 3: Service Tier Classification

Classify every service into an operational tier. Tiers determine HA requirements, restart policies, and placement priority.

Classification Algorithm:

FOR each service:
  IF service.ports includes [53, 80, 443] OR service.name matches [caddy, dns, registry, vpn]:
    tier = T0
  ELIF service.name matches [portainer, gitlab, keycloak, openbao, grafana, loki, prometheus]:
    tier = T1
  ELIF service.name matches [erpnext, plane, twenty, mattermost, nextcloud, paperless]:
    tier = T2
  ELIF service.name matches [mealie, wger, gramps, firefly, calibre, freshrss, archivebox]:
    tier = T3
  ELIF service.image references [ollama, whisper, xtts, immich-ml, stable-diffusion]:
    tier = T4
  ELIF service.name contains "mcp" OR service.image contains "mcp" OR "agent":
    tier = T5
  ELIF service.volumes references NAS paths OR service.name matches [jellyfin, sonarr, radarr, arr]:
    tier = T6
  ELSE:
    tier = T3  # default to lifestyle

Step 4: Node Role Assignment

Assign functional roles to each node based on hardware capabilities.

Role Assignment Rules:

Auto-detection heuristic:

nodes.sort(by: disk_available, descending)
nas_node = nodes[0] if nodes[0].disk_available > 2x nodes[1].disk_available

nodes.sort(by: cpu_cores * ram_total, descending)
compute_leader = nodes[0]

gateway_node = node where caddy/dns currently runs OR node with lowest latency to WAN

ai_node = node with gpu OR node with architecture == "aarch64" OR highest ram

Step 5: Placement Scoring Algorithm

For each service, score candidate nodes and select the optimal placement.

Scoring Function:

FOR each service S:
  candidates = nodes.filter(compatible_architecture(S))

  IF S.tier == T0: candidates = [gateway_node]          # pinned
  IF S.tier == T6: candidates = [nas_node]               # pinned
  IF S.tier == T4 AND gpu_required: candidates = [ai_node]

  FOR each candidate node N:
    # Base capacity score (0-100)
    ram_headroom = (N.ram_available - S.estimated_ram) / N.ram_total * 100
    cpu_headroom = (N.cpu_cores - N.services_cpu_load) / N.cpu_cores * 100
    disk_headroom = (N.disk_available - S.estimated_disk) / N.disk_total * 100

    capacity_score = min(ram_headroom, cpu_headroom, disk_headroom)

    # Density penalty: prefer spreading services
    density_penalty = N.current_service_count / 20  # penalty increases with density

    # Affinity bonus: co-locate with dependencies
    affinity_bonus = 0
    FOR each dep in S.dependencies:
      IF dep.current_node == N: affinity_bonus += 15

    # Storage bonus: prefer nodes where volumes already exist
    storage_bonus = 0
    IF S.volumes exist on N: storage_bonus += 20

    # Network bonus: same overlay = no cross-node hop
    network_bonus = len(S.networks intersect N.networks) * 5

    FINAL_SCORE = capacity_score - density_penalty + affinity_bonus + storage_bonus + network_bonus

  ASSIGN S to candidate with highest FINAL_SCORE

Step 6: Migration Plan Generation

For services that need to move, generate migration commands.

Migration Types:

Stateless Migration Template:

# Update service constraint
docker service update --constraint-rm 'node.labels.name == OLD_NODE' \
  --constraint-add 'node.labels.name == NEW_NODE' SERVICE_NAME

Volume Migration Template:

# 1. Stop service
docker service scale SERVICE_NAME=0

# 2. Rsync data to target node
rsync -avz --progress OLD_NODE:/path/to/volume/ NEW_NODE:/path/to/volume/

# 3. Update constraint and restart
docker service update --constraint-rm 'node.labels.name == OLD_NODE' \
  --constraint-add 'node.labels.name == NEW_NODE' SERVICE_NAME
docker service scale SERVICE_NAME=1

# 4. Verify
docker service ps SERVICE_NAME --format '{{.Node}} {{.CurrentState}}'

Step 7: Blueprint Generation

Generate a deterministic deployment manifest that can recreate the entire cluster.

Blueprint Format:

# golden-deployment.yaml
cluster:
  name: "example-cluster"
  created: "<ISO-8601-date>"

nodes:
  - hostname: compute-a
    role: compute_leader
    swarm_role: leader
    labels: {workload-class: general}

  - hostname: edge-a
    role: gateway
    swarm_role: worker
    labels: {workload-class: edge}

  - hostname: app-a
    role: app_server
    swarm_role: worker
    labels: {workload-class: application}

placements:
  - service: caddy_caddy
    tier: T0
    node: edge-a
    reason: "Gateway role - reverse proxy with host-mode ports"

  - service: keycloak_keycloak
    tier: T1
    node: edge-a
    reason: "Co-located with Caddy for SSO flows"

networks:
  global:
    - name: caddy
      driver: overlay
      attachable: true
    - name: internet
      driver: overlay
      attachable: true

registry:
  connection_ref: registry://default
  tls_profile_ref: tls://registry-default
  mirror: true

Step 7b: Kubernetes Manifest Emission

The placement decisions from Steps 1–6 are orchestrator-agnostic — only the Step 7 rendering differs by target. To emit Kubernetes manifests instead of the Swarm blueprint, run the companion script:

# native emitter — turns the blueprint's placements into k8s manifests
python scripts/emit_manifests.py --blueprint golden-deployment.yaml \
  --target kubernetes --out k8s/

Add a target: and k8s: block to the blueprint to drive it:

target: kubernetes          # swarm | kubernetes
k8s:
  namespace: example-system
  nodeLabelKey: kubernetes.io/hostname
  storageClass: example-storage  # omit to use the cluster default
  ingressClass: example-ingress

Native emitter mapping (consumes the same placements, enriched from the Step 2 catalog with image/ports/volumes/mode/env):

Two emission paths:

1. Native (above) — deterministic, no external tools; best for planner-owned catalog services. Matches the in-repo golden reference agent-utilities/deploy/k8s/graphos.yaml.

2. kompose transform — for the ~60 existing compose stacks, start from kompose convert -f compose.yml -o k8s/, then apply the deterministic post-fixups kompose drops:

   Swarm/compose feature	kompose drops	Post-fixup
   deploy.placement.constraints	dropped	inject nodeAffinity on name=<host>
   overlay networks (caddy, internet)	NetworkPolicy noise	replace with ClusterIP Service; cross-svc DNS <svc>.<ns>.svc
   named/bind volumes	hostPath/emptyDir	rewrite to local-path PVC pinned to the data's node
   deploy.mode: global	Deployment replicas:1	convert to DaemonSet
   depends_on	dropped	initContainer wait + readiness probe
   host-mode ports (Caddy 80/443)	NodePort guess	hostPort on the edge node or Service type: LoadBalancer

   For services that ship an upstream Helm chart (e.g. graph-os), prefer helm upgrade --install with a values file rendered from the placement.

The emitted k8s/ dir is what the GitLab k8s-deploy CI job applies (kubectl apply -f k8s/), and what the portainer-agent MCP can deploy as a GitOps Kubernetes stack.

Cross-Node Backup Pattern

For critical databases, implement cross-node backup replication:

PRIMARY DB (Node A) → BACKUP CRON (Node B with RAID)

Pattern: The backup service runs on a different node than the database it backs up, ensuring that a node failure doesn't destroy both the primary and the backup. Prefer nodes with RAID arrays (e.g., RAID10) for backup targets.

Implementation:

# db-backup service constraint targets the BACKUP node (different from DB)
deploy:
  placement:
    constraints:
      - node.labels.name == BACKUP_NODE  # NOT the DB node

Verification Checklist

After executing a deployment plan, verify:

1. All services running: docker service ls | grep '0/' → should return empty
2. No cross-node volume errors: Check service logs for mount failures
3. Network connectivity: Each configured service URL returns its expected status
4. Resource utilization: No node exceeds 80% RAM or 90% CPU
5. Registry accessibility: All nodes can pull through the configured registry connection
6. DNS resolution: All overlay service names resolve within containers

KG Schema (Optional)

When Graph-OS is available, persist the deployment topology: