Merge pull request #167 from synfinatic/docs

Add a FAQ

Makefile

@@ -224,3 +224,9 @@ $(DARWINARM64_BIN): $(wildcard */*.go) .prepare
 
 $(OUTPUT_NAME): $(wildcard */*.go) .prepare
 	go build -ldflags='$(LDFLAGS)' -o $(OUTPUT_NAME) cmd/*.go
+
+docs: docs/default-region.png 
+
+docs/default-region.png:
+	dot -o docs/default-region.png -Tpng docs/default-region.dot
+

README.md

@@ -13,6 +13,7 @@
  * [Environment Varables](#environment-varables)
  * [Release History](#release-history)
  * [License](#license)
+ * [Frequently Asked Questions](docs/FAQ.md)
 
 
 ## About

docs/.gitignore

@@ -0,0 +1 @@
+*.png

docs/FAQ.md

@@ -0,0 +1,38 @@
+# Frequently Asked Questions
+
+ * [How do I change the password for the macOS Keychain?](#how-do-i-change-the-password-for-the-macos-keychain)
+ * [How does AWS SSO manage the $AWS\_DEFAULT\_REGION?](#how-does-aws-sso-manage-the-aws_default_region)
+
+### How do I change the password for the macOS Keychain?
+
+You can use `Keychain Access` to do this.  From a terminal, type:
+
+`open ~/Library/Keychains/AWSSSOCli.keychain-db`
+
+Then make sure to select the `AWSSSOCli` keychain.  Then:
+
+`Edit -> Change password for AWSSSOCli...`
+
+### How does AWS SSO manage the $AWS_DEFAULT_REGION?
+
+AWS SSO will leave the `$AWS_DEFAULT_REGION` environment variable alone
+unless the following are all true:
+
+ * The `$AWS_DEFAULT_REGION` is not already defined in your shell
+ * You have specified the region in the `config.yaml` via `DefaultRegion`
+ * You have not set the `--no-region` flag on the CLI
+ * If `$AWS_SSO_DEFAULT_REGION` is set, does it match `$AWS_DEFAULT_REGION?`
+
+If the above are true, then AWS SSO will define both:
+
+ * `$AWS_DEFAULT_REGION`
+ * `$AWS_SSO_DEFAULT_REGION`
+
+to the default region as defined by `config.yaml`.  If the user changes
+roles and the two variables are set to the same region, then AWS SSO will 
+update the region.   If the user ever overrides the `$AWS_DEFAULT_REGION`
+value or deletes the `$AWS_SSO_DEFAULT_REGION` then AWS SSO will no longer
+manage the variable.
+
+<!-- https://github.com/synfinatic/aws-sso-cli/issues/166 -->
+![](https://user-images.githubusercontent.com/1075352/143502947-1465f68f-0ef5-4de7-a997-ea716facc637.png)

docs/default-region.dot

@@ -0,0 +1,33 @@
+digraph g {
+    Start -> ADR_SET
+
+    ADR_SET [label="Is $AWS_DEFAULT_REGION defined?"]
+    ADR_SET -> Have_ASDR [label="Yes"]
+    ADR_SET -> Have_DR [label="No"]
+
+    Have_ASDR [label="Is $AWS_SSO_DEFAULT_REGION defined?"]
+    Have_ASDR -> No_Change [label="No"]
+    Have_ASDR -> Var_Match [label="Yes"] 
+
+    Var_Match [label="Does $AWS_DEFAULT_REGION match $AWS_SSO_DEFAULT_REGION?"]
+    Var_Match -> Delete_ADSR [label="No"]
+    Var_Match -> Have_DR [label="Yes"]
+
+    Have_DR [label="Is DefaultRegion defined in config.yaml?"]
+    Have_DR -> No_Change [label="No"]
+    Have_DR -> No_Region [label="Yes"]
+
+    No_Change [label="No changes to environment"]
+    No_Change -> End
+
+    No_Region [label="Is --no-region set?"]
+    No_Region -> No_Change [label="Yes"]
+    No_Region -> Set_ADR [label="No"]
+
+    Set_ADR [label="Set $AWS_DEFAULT_REGION"]
+
+    Delete_ADSR [label="Unset $AWS_SSO_DEFAULT_REGION"]
+
+    Delete_ADSR -> End
+    Set_ADR -> End
+}