rewrite

docs/how-to/aws-sso/create-sso-group.md

@@ -1,49 +1,136 @@
 # AWS SSO: Creating SSO Groups
 
-# About
-
-# Creating SSO Group from existing System Common
-
-# Details
-
-* Below steps documented are for creating a new group called csvd-iac-poc in Lab.
-
-   * Every group uses a data resource to find the user id, so the user has to be in idc already
-   * Anyone in the below yml needs to be in users.csv (infrastructure/global/sso/users.csv)
-
-*   Network Account
-    *  Choose the appropriate network account.
-	*  in `infrastructure/global/sso/permissionsets/{TEMPLATE}`.
-	*  Make new directory
-	    * eg. `infrastructure/global/sso/permissionsets/sc-developer`
-	    * mkdir csvd-iac-poc
-	*  copy TEMPLATE/* {new_directory}
-	    * cp TEMPLATE/* csvd-iac-poc
-	*  cd to the new directory
-        *  eg. cd csvd-iac-poc
-    ## Initialize the environment		
-	   ```script
-	   tf-run init
-	   tf-run apply
-           `````
-	   ```script
-           COMMAND rename GROUP csvd-iac-poc GROUP*
-           ``````
-	*  edit `new-directory*.tf and yml and put in the proper values`
-        *  eg  csvd-iac-poc-sc-developer.yml
-            * group: csvd-iac-poc-sc-developer
-            * description: "CSVD IAC POC SC Developer"
-            * all: false
-            * account_names: 
-               - lab-dev-ew
-            * account_ids: []
-            * org_ous: []
-            * users: []		   
-        *  csvd-iac-poc-sc-developer.group.tf
-            * locals- add the correct group
-            * rename module name
-
-	## Once changes are completed
-            * tf-plan
-            * tf-plan summary
-     	    * commit, push, and PR	
+This describes how to create a new group which uses the System Common (`sc-`) set of pre-defined permission sets.
+These include:
+
+* sc-audit
+* sc-dba
+* sc-developer
+* sc-operator
+* sc-poweruser (not fully ready for use)
+* sc-tagadmin-t2 (will be renaming this to remove the -t2)
+* sc-tester
+
+## Summary of Steps
+
+1. starting point is {management-account-repo}/infrastructure/global/sso
+2. add users for the new group into `users.csv`, if not already there
+3. go to permissionsets
+4. go into the appropriate `sc-{function}` directory
+5. create a new directory with the name of the group, less the `-sc-{function}` suffix
+6. initialize the Terraform files and apply (no code yet)
+7. copy template files
+8. rename files
+9. edit resulting YAML file accordingly
+10. plan (plan will fail until users added to `users.csv`)
+11. once all merged, apply in the new group directory
+
+## Example
+
+* Step 1
+
+In this example, we will be creating a group called `csvd-iac-poc-sc-developer` (in the lab).
+The group uses a data resource to find the user, so the user has to be in Identity Center already.
+Create a branch something like add-group-{groupname}
+
+* Step 2
+
+```script
+cd REPO/infrastructure/global/sso
+git checkout -b add-group-csvd-iac-poc-sc-developer
+# add users to user.csv
+tf-plan
+```
+
+Create a PR using the `sso.md` template.  Add `tf-plan summmary` to the PR text, check the appropriate boxes and enter the appropriate
+text for the group and details about Remedy and/or Jira. Upload the `tf-plan` log. Submit.
+
+Once merged, you can apply.  While waiting for the merge, you can setup the group but you won't be able to plan until users are applied.
+
+* Step 3 and 4
+
+Continue to work in your branch, and pull in the merged master (if you are waiting for the merge; if not, skip the pull step).
+
+```script
+cd REPO/infrastructure/global/sso/permissionsets/sc-developer
+git checkout add-group-csvd-iac-poc-sc-developer
+git pull origin master
+```
+
+* Step 5
+
+Make the new directory. The group will be `csvd-iac-poc-sc-devloper`, and the directory will be `csvd-iac-poc`.
+
+```script
+mkdir csvd-iac-poc  
+```
+
+* Step 6
+
+Initialize the Terraform environment and apply.  This sets up the proper links and all.
+
+```script
+tf-run init
+tf-run apply
+```
+
+* Step 7
+
+Copy the template files.
+
+```script
+cp TEMPLATE/* csvd-iac-poc/
+```
+
+* Step 8
+
+Rename the files.
+
+```script
+rename GROUP csvd-iac-poc GROUP*
+```
+
+* Step 9
+
+Edit the YAML files.  Preserve the `-sc-developer` in the `group` and the `SC Developer` in the `description`.
+
+```yaml
+group: csvd-iac-poc-sc-developer
+description: "CSVD IAC POC SC Developer"
+all: false
+account_names:
+  - lab-dev-ew
+account_ids: []
+org_ous: []
+users:
+  - andra315
+  - morga471
+```
+
+* Step 10 
+
+Create a plan, then create a PR with the appropriate details, plan log and summary, as done earlier, but for this new directory. 
+
+```script
+tf-plan
+```
+
+* Step 11
+
+Once the PR is validated and merged, you can complete the configuration and remove your local branch.
+
+```script
+cd REPO/infrastructure/global/sso/permissionsets/sc-developer/csvd-iac-poc
+git checkout master
+git pull origin master
+tf-apply
+git branch -d add-group-csvd-iac-poc-sc-developer
+```
+
+
+# CHANGELOG
+
+- 1.0.0 -- 2024-01-22
+  - initial
+- 1.0.1 -- 2025-07-17
+  - update example, reference local README.md