Notes/Docker/proxmox-node/Proxmox.md

Runbook: Docker Host Setup with RBAC and Node Exporter on Proxmox

Purpose

This runbook describes how to prepare a Proxmox host to run Docker services safely and predictably, using:

• ZFS-backed storage (not the OS disk)
• Role-based access control (RBAC)
• Non-root daily administration
• Docker Engine installed from the official repository
• Node Exporter as a first monitoring workload

The goal is to support multiple administrators, minimise risk, and avoid VM sprawl for simple host-level services.

---

Scope

This runbook covers:

• Storage decisions on a Proxmox host
• Admin group and user setup
• Docker installation and configuration
• Docker data-root relocation to ZFS
• Node Exporter deployment via Docker Compose

This runbook does not cover:

• Prometheus or Grafana configuration
• Firewall rules
• Proxmox cluster configuration
• Advanced Docker security hardening

---

Assumptions

• Proxmox VE is already installed and operational
• A ZFS pool exists (e.g. /tank)
• SSH access to the Proxmox host is available
• Root access is available for initial setup

---

High-Level Design

Storage Model

• Proxmox OS and system services remain on the OS disk

• ZFS pool is used for:

  • Docker engine data
  • Docker service directories

• Proxmox-managed VM storage remains isolated (e.g. tank/vmdata)

Access Model (RBAC)

• One top-level admin group with full control
• Sub-admin groups for scoped access (Docker, VMs, monitoring)
• Users operate as themselves, not as root
• Root access is only used when required

---

Admin Groups

Create the following Unix groups:

• sysadmin – full administrative access (sudo)
• docker-admin – Docker administration
• vm-admin – VM and Proxmox-related tasks
• monitoring-admin – monitoring-related services

Groups represent roles, not individuals.

---

User Setup

• Create named user accounts for administrators

• Add full administrators to:

  • sysadmin
  • docker-admin

• Sub-admins may be added only to the groups they require

Sudo Access

• Grant full sudo access to the sysadmin group via /etc/sudoers.d/
• Avoid per-user sudo rules

---

Docker Base Directory

All Docker-related data must live under the ZFS pool.

Recommended structure:

/tank/docker
├── engine/          # Docker internal data-root
├── node-exporter/   # Monitoring exporter
└── <future-services>/

Ownership and permissions:

• Owner: root
• Group: docker-admin
• Permissions: 2775 (setgid enabled)

---

Docker Installation

Install Docker Engine from the official Docker repository.

Reasons:

• Predictable updates
• Supported versions
• Includes Compose plugin

Packages installed:

• docker-ce
• docker-ce-cli
• containerd.io
• docker-buildx-plugin
• docker-compose-plugin

---

Docker Data-Root Configuration

Docker’s internal data-root must be moved off the OS disk.

Configure Docker to use:

/tank/docker/engine

via /etc/docker/daemon.json:

{
  "data-root": "/tank/docker/engine",
  "group": "docker-admin"
}

---

Docker Socket Permissions

Docker access is controlled via the Unix socket:

/var/run/docker.sock

To align with RBAC:

• Override the systemd socket unit
• Set socket group to docker-admin

This allows Docker administration without:

• root shells
• sudo for every command
• use of the default docker group

---

Verification (Docker Access)

As a non-root admin user:

docker version
docker info

Success criteria:

• No permission denied errors
• Docker daemon responds
• Commands run without sudo

---

Node Exporter Deployment

Node Exporter is used to expose host-level metrics.

Deployment Model

• Runs directly on the Proxmox host
• Deployed via Docker Compose
• Uses host networking
• Read-only filesystem access

Service Directory

/tank/docker/node-exporter

Compose Characteristics

• network_mode: host
• pid: host
• Read-only root filesystem
• Bind mounts for /proc, /sys, and /

Verification

curl http://localhost:9100/metrics

A successful response returns a large metrics output.

---

Operational Notes

• No monitoring services (Prometheus, Grafana) should run on the Proxmox host
• Exporters only — no stateful services
• Docker services should remain minimal and infrastructure-focused
• ZFS allows future snapshotting and rollback if required

---

Outcome

After completing this runbook, the Proxmox host will have:

• Clean separation between OS, VM storage, and Docker workloads
• ZFS-backed Docker storage
• Role-based admin access
• Non-root Docker administration
• A working Node Exporter endpoint ready for Prometheus

---

Future Extensions

• Add Prometheus scrape configuration
• Add firewall rules for exporter ports
• Add additional exporters (SMART, Proxmox)
• Automate via Ansible or Terraform
• Convert into a standard “Host Baseline” template