From e421840541ef13aa110821c5dedbcfd95da7917b Mon Sep 17 00:00:00 2001
From: Julian Sommer <115516918+juliansommer@users.noreply.github.com>
Date: Tue, 31 Mar 2026 11:42:29 +1000
Subject: [PATCH] feat: placment group docs

---
 docs/launching-instances/README.md |   2 -
 docs/placement-groups/README.md    | 113 +++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+), 2 deletions(-)
 create mode 100644 docs/placement-groups/README.md

diff --git a/docs/launching-instances/README.md b/docs/launching-instances/README.md
index 3cc70af94..46ec2e673 100644
--- a/docs/launching-instances/README.md
+++ b/docs/launching-instances/README.md
@@ -53,8 +53,6 @@ Spinifex provides EC2-compatible VM management built on QEMU/KVM. Instances supp
 ## Launch
 
 ```bash
-export AWS_PROFILE=spinifex
-
 aws ec2 run-instances \
   --image-id $SPINIFEX_AMI \
   --instance-type t3.small \
diff --git a/docs/placement-groups/README.md b/docs/placement-groups/README.md
new file mode 100644
index 000000000..eac300165
--- /dev/null
+++ b/docs/placement-groups/README.md
@@ -0,0 +1,113 @@
+---
+title: "Placement Groups"
+description: "Create and manage spread and cluster placement groups for hardware-level instance placement control."
+category: "Environments"
+tags:
+  - ec2
+  - placement
+  - spread
+  - cluster
+resources:
+  - title: "Spinifex Repository"
+    url: "https://github.com/mulgadc/spinifex"
+  - title: "AWS Placement Groups"
+    url: "https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/placement-groups.html"
+---
+
+# Placement Groups
+
+> Create and manage spread and cluster placement groups for hardware-level instance placement control.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Create](#create)
+- [Launch Into a Placement Group](#launch-into-a-placement-group)
+- [Describe](#describe)
+- [Delete](#delete)
+- [Troubleshooting](#troubleshooting)
+  - [InsufficientInstanceCapacity Error](#insufficientinstancecapacity-error)
+  - [Cannot Delete Placement Group](#cannot-delete-placement-group)
+
+---
+
+## Overview
+
+Placement groups control how Spinifex distributes instances across physical hosts. Two strategies are supported:
+
+- **Spread** — One instance per physical host, maximising fault isolation
+- **Cluster** — All instances on the same host, minimising latency
+
+The `partition` strategy is not supported.
+
+**Supported operations:**
+
+- `create-placement-group` — Create a new group
+- `describe-placement-groups` — Query groups with optional filters
+- `delete-placement-group` — Remove an empty group
+
+## Instructions
+
+## Create
+
+```bash
+aws ec2 create-placement-group \
+  --group-name my-spread-group \
+  --strategy spread
+```
+
+```bash
+aws ec2 create-placement-group \
+  --group-name my-cluster-group \
+  --strategy cluster
+```
+
+## Launch Into a Placement Group
+
+```bash
+aws ec2 run-instances \
+  --image-id $SPINIFEX_AMI \
+  --instance-type t3.small \
+  --key-name spinifex-key \
+  --placement GroupName=my-spread-group \
+  --count 3
+```
+
+## Describe
+
+```bash
+aws ec2 describe-placement-groups
+aws ec2 describe-placement-groups --group-names my-spread-group
+aws ec2 describe-placement-groups --group-ids pg-abc123
+aws ec2 describe-placement-groups \
+  --filters Name=strategy,Values=spread
+```
+
+## Delete
+
+The group must have no running instances before it can be deleted:
+
+```bash
+aws ec2 terminate-instances --instance-ids $INSTANCE_ID
+aws ec2 delete-placement-group --group-name my-spread-group
+```
+
+## Troubleshooting
+
+### InsufficientInstanceCapacity Error
+
+Not enough distinct physical hosts for a spread launch. Reduce `--count` or terminate existing instances to free host slots:
+
+```bash
+./bin/spx admin nodes list
+```
+
+### Cannot Delete Placement Group
+
+The group still has running instances. Terminate them first:
+
+```bash
+aws ec2 describe-instances \
+  --filters Name=placement-group-name,Values=my-spread-group
+aws ec2 terminate-instances --instance-ids $INSTANCE_ID
+```