From 6f7662949cf71603681ab63c1616c2e785323209 Mon Sep 17 00:00:00 2001
From: Evan Johnson <ejohnson@akamai.com>
Date: Fri, 6 Sep 2024 11:00:26 -0400
Subject: [PATCH] add placement group docs and update firewall docs

---
 docs/src/SUMMARY.md                 |  1 +
 docs/src/topics/firewalling.md      | 62 ++++++++++++++++++++++-------
 docs/src/topics/placement-groups.md | 49 +++++++++++++++++++++++
 3 files changed, 97 insertions(+), 15 deletions(-)
 create mode 100644 docs/src/topics/placement-groups.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 983c7119..fe13d997 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -29,6 +29,7 @@
     - [Autoscaling](./topics/autoscaling.md)
     - [VPC](./topics/vpc.md)
     - [Firewalling](./topics/firewalling.md)
+    - [Placement Groups](./topics/placement-groups.md)
 - [Development](./developers/development.md)
     - [Releasing](./developers/releasing.md)
     - [Testing](./developers/testing.md)
diff --git a/docs/src/topics/firewalling.md b/docs/src/topics/firewalling.md
index ebf1d7a6..c08823aa 100644
--- a/docs/src/topics/firewalling.md
+++ b/docs/src/topics/firewalling.md
@@ -81,17 +81,14 @@ spec:
 ```
 
 ## Cloud Firewalls
+Cloud firewalls are provisioned with all flavors that use VPCs. They are provisioned in disabled mode but can be enabled
+with the environment variable `LINODE_FIREWALL_ENABLED=true`. The default rules allow for all intra-cluster VPC traffic 
+along with any traffic going to the API server. 
 
+### Creating Cloud Firewalls
 For controlling firewalls via Linode resources, a [Cloud Firewall](https://www.linode.com/products/cloud-firewall/) can
-be defined and provisioned via the `LinodeFirewall` resource in CAPL.
-
-The created Cloud Firewall can be used on a `LinodeMachine` or a `LinodeMachineTemplate` by setting the `firewallRef` field.
-Alternatively, the provisioned Cloud Firewall's ID can be used in the `firewallID` field.
-
-```admonish note
-The `firewallRef` and `firewallID` fields are currently immutable for `LinodeMachines` and `LinodeMachineTemplates`. This will
-be addressed in a later release. 
-```
+be defined and provisioned via the `LinodeFirewall` resource in CAPL. Any updates to the cloud firewall CAPL resource
+will be updated in the cloud firewall itself as well.
 
 Example `LinodeFirewall`:
 ```yaml
@@ -104,14 +101,49 @@ spec:
   inboundPolicy: DROP
   inboundRules:
     - action: ACCEPT
-      label: k8s-api
-      ports: "6443"
+      label: intra-cluster
+      ports: "1-65535"
       protocol: "TCP"
       addresses:
         ipv4:
-          - "10.0.0.0/24"
-  # outboundPolicy: ACCEPT
-  # outboundRules: []
+          - "10.0.0.0/8"
+    - action: ACCEPT
+      addresses:
+        ipv4:
+          - 0.0.0.0/0
+        ipv6:
+          - ::/0
+      ports: "6443"
+      protocol: TCP
+      label: inbound-api-server
 ```
 
-Cloud Firewalls are not automatically created for any CAPL flavor at this time.
+### Cloud Firewall Machine Integration
+The created Cloud Firewall can be used on a `LinodeMachine` or a `LinodeMachineTemplate` by setting the `firewallRef` field.
+Alternatively, the provisioned Cloud Firewall's ID can be used in the `firewallID` field.
+
+```admonish note
+The `firewallRef` and `firewallID` fields are currently immutable for `LinodeMachines` and `LinodeMachineTemplates`. This will
+be addressed in a later release. 
+```
+
+Example `LinodeMachineTemplate`:
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: LinodeMachineTemplate
+metadata:
+  name: test-cluster-control-plane
+  namespace: default
+spec:
+  template:
+    spec:
+      firewallRef:
+        apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+        kind: LinodeFirewall
+        name: sample-fw
+      image: linode/ubuntu22.04
+      interfaces:
+        - purpose: public
+      region: us-ord
+      type: g6-standard-4
+```
diff --git a/docs/src/topics/placement-groups.md b/docs/src/topics/placement-groups.md
new file mode 100644
index 00000000..9656a9ba
--- /dev/null
+++ b/docs/src/topics/placement-groups.md
@@ -0,0 +1,49 @@
+# Placement Groups
+
+This guide covers how configure [placement groups](https://techdocs.akamai.com/cloud-computing/docs/work-with-placement-groups) within a CAPL cluster. 
+Placement groups are currently provisioned with any of the `*-full` flavors in the `LinodeMachineTemplate` for the control plane machines only.
+```admonish note
+Currently only 5 nodes are allowed in a single placement group
+```
+
+## Placement Group Creation
+
+For controlling placement groups via Linode resources, a [placement groups](https://techdocs.akamai.com/cloud-computing/docs/work-with-placement-groups) can
+be defined and provisioned via the `PlacementGroup` resource in CAPL.
+
+
+Example `PlacementGroup`:
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: LinodePlacementGroup
+metadata:
+  name: test-cluster
+spec:
+  region: us-ord
+```
+
+## PlacementGroup Machine Integration
+In order to use a placement group with a machine, a `PlacementGroupRef` can be used in the `LinodeMachineTemplate` spec
+to assign any nodes used in that template to the placement group. Due to the limited size of the placement group our templates
+currently only integrate with this for control plane nodes
+
+Example `LinodeMachineTemplate`:
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: LinodeMachineTemplate
+metadata:
+  name: test-cluster-control-plane
+  namespace: default
+spec:
+  template:
+    spec:
+      image: linode/ubuntu22.04
+      interfaces:
+        - purpose: public
+      placementGroupRef:
+        apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+        kind: LinodePlacementGroup
+        name: test-cluster
+      region: us-ord
+      type: g6-standard-4
+```