docs: add three node installation notes

README.md

@@ -2,4 +2,92 @@
 
 A snap for managing charmed MAAS deployments.
 
-## NOT A PRODUCTION READY PRODUCT. STILL UNDER DEVELOPMENT AND IN ALPHA PHASE.
+## NOT A PRODUCTION READY PRODUCT. STILL UNDER DEVELOPMENT AND IN ALPHA PHASE
+
+## Multi-node installation steps
+
+The following instructions assume that nodes `infra1`, `infra2`, `infra3` are deployed with Ubuntu > 22.04 LTS and their networking is properly configured.
+
+In addition, the instructions assume that all three nodes have all components (roles) installed:
+
+- MAAS region controller
+- MAAS rack controller (agent)
+- PostgreSQL
+- HAProxy
+
+### Preparation steps for each node
+
+```bash
+ubuntu@infra{1,2,3}:~$ sudo snap install maas-anvil
+ubuntu@infra{1,2,3}:~$ maas-anvil prepare-node-script | bash -x
+ubuntu@infra{1,2,3}:~$ sudo snap connect maas-anvil:juju-bin juju:juju-bin
+ubuntu@infra{1,2,3}:~$ sudo snap connect maas-anvil:dot-local-share-juju
+ubuntu@infra{1,2,3}:~$ newgrp snap_daemon
+```
+
+### Bootstrap the first node
+
+```bash
+ubuntu@infra1:~$ maas-anvil cluster bootstrap \
+    --role database --role region --role agent --role haproxy \
+    --accept-defaults
+```
+
+### Add new nodes to the MAAS cluster
+
+```bash
+ubuntu@infra1:~$ maas-anvil cluster add --name infra2.
+Token for the Node infra2.: eyJuYW1lIjoibWFhcy00Lm1hYXMiLCJzZWNyZXQiOiI3MmE512342abcdEASWWxOWNlYWNkYmJjMWRmMjk4OThkYWFkYzQzMDAzZjk4NmRkZDI2MWRhYWVkZTIxIiwiZmluZ2VycHJpbnQiOiJlODU5ZmY5NjAwMDU4OGFjZmQ5ZDM0NjFhMDk5NmU1YTU3YjhjN2Q2ZjE4M2NjZDRlOTg2NGRkZjQ3NWMwZWM1Iiwiam9pbl9hZGRyZXNzZXMiOlsiMTAuMjAuMC43OjcwMDAiLCIxMC4yMC4wLjg6NzAwMCJdfQ==
+
+ubuntu@infra1:~$ maas-anvil cluster add --name infra3.
+Token for the Node infra3.: eyJuYW1lIjoibWFhcy00Lm1hYXMiLCJzZWNyZXQiOiI3MmE512342abcdEASWWxOWNlYWNkYmJjMWRmMjk4OThkYWFkYzQzMDAzZjk4NmRkZDI2MWRhYWVkZTIxIiwiZmluZ2VycHJpbnQiOiJlODU5ZmY5NjAwMDU4OGFjZmQ5ZDM0NjFhMDk5NmU1YTU3YjhjN2Q2ZjE4M2NjZDRlOTg2NGRkZjQ3NWMwZWM1Iiwiam9pbl9hZGRyZXNzZXMiOlsiMTAuMjAuMC43OjcwMDAiLCIxMC4yMC4wLjg6NzAwMCJdfQ==
+```
+
+### Join new nodes to the MAAS cluster
+
+```bash
+ubuntu@infra2:~$ anvil cluster join \
+    --role database --role region --role agent --role haproxy \
+    --token eyJuYW1lIjoibWFhcy00Lm1hYXMiLCJzZWNyZXQiOiI3MmE512342abcdEASWWxOWNlYWNkYmJjMWRmMjk4OThkYWFkYzQzMDAzZjk4NmRkZDI2MWRhYWVkZTIxIiwiZmluZ2VycHJpbnQiOiJlODU5ZmY5NjAwMDU4OGFjZmQ5ZDM0NjFhMDk5NmU1YTU3YjhjN2Q2ZjE4M2NjZDRlOTg2NGRkZjQ3NWMwZWM1Iiwiam9pbl9hZGRyZXNzZXMiOlsiMTAuMjAuMC43OjcwMDAiLCIxMC4yMC4wLjg6NzAwMCJdfQ==
+```
+
+```bash
+ubuntu@infra3:~$ anvil cluster join \
+    --role database --role region --role agent --role haproxy \
+    --token eyJuYW1lIjoibWFhcy00Lm1hYXMiLCJzZWNyZXQiOiI3MmE512342abcdEASWWxOWNlYWNkYmJjMWRmMjk4OThkYWFkYzQzMDAzZjk4NmRkZDI2MWRhYWVkZTIxIiwiZmluZ2VycHJpbnQiOiJlODU5ZmY5NjAwMDU4OGFjZmQ5ZDM0NjFhMDk5NmU1YTU3YjhjN2Q2ZjE4M2NjZDRlOTg2NGRkZjQ3NWMwZWM1Iiwiam9pbl9hZGRyZXNzZXMiOlsiMTAuMjAuMC43OjcwMDAiLCIxMC4yMC4wLjg6NzAwMCJdfQ==
+```
+
+### Confirm the cluster status
+
+```bash
+ubuntu@infra1:~$ maas-anvil cluster list
+┏━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
+┃ Node   ┃ Status ┃ Region ┃ Agent ┃ Database ┃ HAProxy ┃
+┡━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
+│ infra1 │   up   │   x    │   x   │    x     │    x    │
+│ infra2 │   up   │   x    │   x   │    x     │    x    │
+│ infra3 │   up   │   x    │   x   │    x     │    x    │
+└────────┴────────┴────────┴───────┴──────────┴─────────┘
+```
+
+### Create MAAS admin user
+
+```bash
+ubuntu@infra1:~$ juju run maas-region/0 create-admin username=admin password=pass email=admin@maas.io ssh-import=lp:maasadmin
+```
+
+### (Optional) Add VIP functionality through Keepalived charm
+
+```bash
+ubuntu@infra1:~$ juju deploy containers/keepalived
+ubuntu@infra1:~$ juju relate haproxy:juju-info keepalived:juju-info
+ubuntu@infra1:~$ juju config keepalived virtual_ip=<ip_address>
+```
+
+### Charm documentation
+
+- MAAS Region: <https://charmhub.io/maas-region>
+- MAAS Region: <https://charmhub.io/maas-agent>
+- PostgreSQL: <https://charmhub.io/postgresql>
+- HAProxy: <https://charmhub.io/haproxy>
+- Keepalived: <https://charmhub.io/keepalived>