diff --git a/tech_docs/its_the_new_style_design.md b/tech_docs/its_the_new_style_design.md index 7f261df..b81c86a 100644 --- a/tech_docs/its_the_new_style_design.md +++ b/tech_docs/its_the_new_style_design.md @@ -1,3 +1,170 @@ +Below is a **complete, end-to-end recipe** to spin up a **proper three-node Docker Swarm** on **Debian 12 minimal VMs** while honoring: + +- the **dual-stack IPv4/IPv6 numbering** you already locked in +- the **symmetrical naming schema** +- a **private, non-routed VLAN** for management / HA traffic + +Copy-paste ready; zero drift. + +──────────────────────────────────────── +1. Lab topology (logical) + +| VM | Role | Public VLAN (DMZ) | Private VLAN (Mgmt/HA) | DNS name | +|---|---|---|---|---| +| vm-01 | Swarm manager + worker | 10.0.1.10/24 2001:db8:c0de:2000::10/64 | 192.168.255.10/24 | mgr-01.dmz.mycorp.net | +| vm-02 | Swarm manager + worker | 10.0.1.11/24 2001:db8:c0de:2000::11/64 | 192.168.255.11/24 | mgr-02.dmz.mycorp.net | +| vm-03 | Swarm manager + worker | 10.0.1.12/24 2001:db8:c0de:2000::12/64 | 192.168.255.12/24 | mgr-03.dmz.mycorp.net | + +Private VLAN **only** carries Swarm control plane (TCP 2377, 7946, 4789). +Public VLAN carries application traffic. + +──────────────────────────────────────── +2. Debian 12 minimal VM prep (repeat on every node) + +```bash +# 1. base update +sudo apt update && sudo apt -y upgrade +sudo apt -y install vim curl + +# 2. add Docker repo & install +curl -fsSL https://download.docker.com/linux/debian/gpg | \ + sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \ + https://download.docker.com/linux/debian $(lsb_release -cs) stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +sudo apt update +sudo apt -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +sudo usermod -aG docker $USER && newgrp docker +``` + + +──────────────────────────────────────── +3. VLAN interface on the **private** network + +Assume host physical NIC is `ens18`; create VLAN 255 for mgmt/HA. + +```bash +# /etc/network/interfaces.d/mgmt +auto ens18.255 +iface ens18.255 inet static + address 192.168.255.10/24 # change per node + gateway none # non-routed +``` + +`systemctl restart networking` or reboot. + +──────────────────────────────────────── +4. Firewall (ufw example) + +```bash +sudo ufw allow 22/tcp +sudo ufw allow 2377/tcp # swarm management +sudo ufw allow 7946/tcp +sudo ufw allow 7946/udp +sudo ufw allow 4789/udp # overlay vxlan +sudo ufw enable +``` + +──────────────────────────────────────── +5. Initialize the swarm (on vm-01) + +```bash +# use the **private** IP so traffic never leaves VLAN 255 +docker swarm init --advertise-addr 192.168.255.10 --listen-addr 192.168.255.10:2377 +``` +Copy the **join-token** that is printed. + +On vm-02 / vm-03 run: + +```bash +docker swarm join --token SWMTKN-... 192.168.255.10:2377 +``` + +Verify quorum: + +```bash +docker node ls +``` + +──────────────────────────────────────── +6. Dual-stack overlay network + +```bash +docker network create \ + --driver overlay \ + --attachable \ + --subnet 10.0.255.16/28 \ + --subnet 2001:db8:c0de:ffff:2000::/80 \ + sym-net +``` + +──────────────────────────────────────── +7. DNS A/AAAA & reverse records (dnsmasq) + +Append to `/etc/dnsmasq-static-hosts`: + +``` +# Swarm managers +10.0.1.10 mgr-01.dmz.mycorp.net +2001:db8:c0de:2000::10 mgr-01.dmz.mycorp.net +10.0.1.11 mgr-02.dmz.mycorp.net +2001:db8:c0de:2000::11 mgr-02.dmz.mycorp.net +10.0.1.12 mgr-03.dmz.mycorp.net +2001:db8:c0de:2000::12 mgr-03.dmz.mycorp.net +``` + +Reload: + +```bash +sudo systemctl reload dnsmasq +``` + +──────────────────────────────────────── +8. Deploy a test stack + +`/opt/stacks/hello.yml` + +```yaml +version: "3.9" +services: + web: + image: nginx:alpine + deploy: + replicas: 3 + ports: + - "80:80" +networks: + default: + external: true + name: sym-net +``` + +```bash +docker stack deploy -c /opt/stacks/hello.yml hello +``` + +Access: + +```bash +curl http://mgr-01.dmz.mycorp.net +curl -6 http://mgr-01.dmz.mycorp.net +``` + +──────────────────────────────────────── +9. Daily ops cheat-sheet + +| Task | Command | +|---|---| +| List nodes | `docker node ls` | +| Drain manager | `docker node update --availability drain mgr-01` | +| Remove node | `docker node rm mgr-03` then re-join | +| Show logs | `docker service logs hello_web` | + +You now have a **production-ready, three-manager Docker Swarm** on Debian 12, **isolated on a private mgmt VLAN**, yet fully dual-stack and symmetrical. + +--- + Complete, symmetry-first DNS name & function list (ready to drop straight into **dnsmasq-static-hosts** or NetBox)