From abb36b385c9f3f0a7b34a9676c3f177b1e23842a Mon Sep 17 00:00:00 2001
From: Shawn Smith <80111+shawnps@users.noreply.github.com>
Date: Tue, 9 Jul 2024 07:50:09 +0900
Subject: [PATCH] add 3.0.0.md to templates/guides dir to prevent it from being
 removed when running "make docs"

---
 templates/guides/3.0.0.md | 121 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 templates/guides/3.0.0.md

diff --git a/templates/guides/3.0.0.md b/templates/guides/3.0.0.md
new file mode 100644
index 0000000..21a12a2
--- /dev/null
+++ b/templates/guides/3.0.0.md
@@ -0,0 +1,121 @@
+## Upgrading to version 3
+
+**Rate limit rules now support non-IP client identifiers**
+
+To add support for non-IP client identifiers within rate limit rules we had to convert them from `TypeMap` to `TypeSet`.
+
+This means that in order to continue using your existing configuration you will need to update your configuration and also update existing resources within your state file.
+
+We have outlined the changes that will need to be made in detail below.
+
+### High Level Overview
+
+1. Backup terraform config and state
+2. Change all `rate_limit = {}` definitions to `rate_limit {}` in main.tf
+3. Add `client_identifiers {}` to `rate_limit {}` section of main.tf
+4. Either manually or using the provided script remove all existing rules and re-import 
+
+### Detailed Overview
+
+#### Backup terraform config and state
+1. Make a copy of your terraform configuration and state files
+
+```
+tar -czvf terraform-backup.tar.gz main.tf terraform.tfstate
+```
+
+#### Change all `rate_limit = {}` definitions to `rate_limit {}`
+2. Any references that have `rate_limit = {}` will need to be converted to `rate_limit {}`.
+
+Existing:
+
+```
+rate_limit = {
+  threshold = 6 
+  interval  = 10
+  duration  = 300 
+}
+```
+
+New:
+```
+rate_limit {
+  threshold = 6 
+  interval  = 10
+  duration  = 300 
+}
+```
+
+#### Add `client_identifiers {}`
+3. Rate limit rules now require that you specify `client_identifiers`. To continue having your rate limit rules operate as they were configured for "ip" based client identifiers you will need to update your `rate_limit {}` section to also specify `client_identifiers`. Example as follows:
+
+```
+rate_limit {
+  threshold = 6 
+  interval  = 10
+  duration  = 300
+    
+  client_identifiers {
+    type = "ip"
+  }
+}
+``` 
+
+The supported values for `client_identifiers` are as follows: `ip`, `requestHeader`, `requestCookie`, `postParameter`, `signalPayload`.
+Each of these (except for `ip`) allow you to specify additional parameters for `name` and `key`.
+
+You can combine up to 2 of these together (e.g. ip+requestHeader).
+
+For example:
+
+```
+rate_limit {
+  threshold = 6
+  interval  = 10
+  duration  = 300
+
+  client_identifiers {
+    type = "ip"
+  }
+  client_identifiers {
+    type = "requestHeader"
+    name = "x-my-header"
+  }
+}
+```
+
+#### Either manually or using the provided script remove all existing rules and re-import
+4. Due to `rate_limit` changing from a `TypeMap` to a `TypeSet` **all** existing site rules need their state removed and re-imported (even those that do not explicitly define `rate_limit`).
+
+Manually this would be as follows:
+
+* Run `terraform state rm sigsci_site_rule.<rule name>` for every rule.
+* Re-import each rule using `terraform import sigsci_site_rule.<rule name> <site_short_name>:<rule_id>`
+
+**IMPORTANT**: You should run `terraform state rm` for every rule before doing the import!
+
+To aid with this, we have provided the below script that can be used to automate this process.
+The script uses `terraform state pull` to gather the existing state and pulls in all of your site rules, their names, and ids. It then removes the existing state and imports it again into the new structure.
+
+**Note: The below script requires that you have installed `jq`**
+```
+#!/bin/bash
+
+TF_STATE=$(terraform state pull)
+IMPORT_CMD=""
+for rule_name in $(echo "$TF_STATE"|jq -r '.resources[]| select(.type=="sigsci_site_rule") | .name'); do
+    site_short_name=$(echo "$TF_STATE"|jq --arg rule_name "$rule_name" -r '.resources[]| select(.type=="sigsci_site_rule") | select(.name==$rule_name) | .instances[].attributes | .site_short_name ');
+    rule_id=$(echo "$TF_STATE"|jq --arg rule_name "$rule_name" -r '.resources[]| select(.type=="sigsci_site_rule") | select(.name==$rule_name) | .instances[].attributes | .id ');
+
+    printf "Removing state for: site:%s rule_name:%s rule_id:%s\n" "$site_short_name" "$rule_name" "$rule_id";
+    terraform state rm sigsci_site_rule."$rule_name"
+    if [ -z "$IMPORT_CMD" ] ; then
+        IMPORT_CMD="terraform import sigsci_site_rule.\"$rule_name\" \"$site_short_name\":\"$rule_id\"";
+    else
+        IMPORT_CMD="$IMPORT_CMD;terraform import sigsci_site_rule.\"$rule_name\" \"$site_short_name\":\"$rule_id\""
+    fi
+done;
+
+echo "Re-importing rules"
+eval $IMPORT_CMD;
+```