Add FAQ (#27)

* Add FAQ

* add FAQ to menu

* add ask-a-question button

* display excerpts

Author: osterman

config.toml

@@ -70,6 +70,13 @@ identifier = "blog"
 url = "https://cloudposse.com/blog/"
 weight = 40
 
+[[menu.shortcuts]]
+pre = "<h3>More</h3>"
+name = "<i class='fa fa-question'></i> <label>FAQ</label>"
+identifier = "faq"
+url = "/faq/"
+weight = 45
+
 [[menu.shortcuts]]
 pre = "<h3>More</h3>"
 name = "<i class='fa fa-question'></i> <label>Support</label>"

content/faq/_index.md

@@ -0,0 +1,4 @@
+---
+title: "FAQs"
+icon: "fa fa-question-circle"
+---

content/faq/aws-vault-error-failed-to-get-credentials.md

@@ -0,0 +1,23 @@
+---
+title: "aws-vault: error: Failed to get credentials ... aes.KeyUnwrap(): integrity check failed."
+excerpt: "This horribly cryptic error message is a cryptographers way of saying \"wrong password\"."
+tags:
+- aws-vault
+- geodesic
+- faq
+---
+
+# Question
+
+When calling aws-vault exec or attempting to assume-role, I get the following error:
+
+```
+Enter passphrase to unlock /conf/.awsvault/keys/:
+aws-vault: error: Failed to get credentials for peerstreet (source profile for cp-root-admin): aes.KeyUnwrap(): integrity check failed.
+```
+
+# Answer
+
+This horribly cryptic error message is a cryptographers way of saying "wrong password". Just try running the command again, but this time enter the correct password. =)
+
+

content/faq/aws-vault-error-failed-to-start-credential-server.md

@@ -0,0 +1,21 @@
+---
+title: "aws-vault: error: Failed to start credential server"
+excerpt: "This is usually caused by another geodesic shell running."
+tags:
+- geodesic
+- aws-vault
+- faq
+---
+
+# Question
+
+When running `aws-vault` or `assume-role`, I get the following error:
+
+```
+aws-vault: error: Failed to start credential server: listen tcp 127.0.0.1:9099: bind: address already in use
+```
+
+# Answer
+
+This is usually caused by another geodesic shell running. This happens because aws-vault server can only be run once. Try exiting your other geodesic shell.
+

content/faq/aws-vault-outputs-key-and-does-nothing.md

@@ -0,0 +1,21 @@
+---
+title: "aws-vault outputs `'aws_access_key_id'` message and does nothing"
+excerpt: "This is usually because there's a `[default]` section in your `~/.aws/config`"
+tags:
+- geodesic
+- aws-vault
+- faq
+---
+
+# Question
+
+When calling `aws-vault exec` or using `assume-role` in `geodesic`, a single line is output that simply says:
+
+```
+'aws_access_key_id'
+```
+
+# Answer
+
+This is usually because there's a `[default]` section in your `~/.aws/config`. Remove that and it should start to work.
+

content/faq/calling-chamber-write-triggers-error.md

@@ -0,0 +1,55 @@
+---
+title: "Calling `chamber write` triggers `Error: InvalidKeyId: ... parameter_store_key is not found.`"
+excerpt: "Chamber expects to find a KMS key with alias `parameter_store_key`"
+---
+
+# Question
+
+```
+Error: InvalidKeyId: Alias arn:aws:kms:us-west-2:671362398325:alias/parameter_store_key is not found. (Service: AWSKMS; Status Code: 400; Error Code: NotFoundException; Request ID: bf9b3240-39f5-11e8-921d-e9dc98bd5b1a)
+```
+
+# Answer
+
+Per the [documentation](https://github.com/segmentio/chamber/blob/master/README.md#setting-up-kms), Chamber expects to find a KMS key with alias `parameter_store_key` in the account that you are writing/reading secrets.
+
+You can follow the [AWS KMS documentation](http://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) to create your key, and follow this guide to [set up your alias](http://docs.aws.amazon.com/kms/latest/developerguide/programming-aliases.html).
+
+We recommend using Terraform:
+```
+resource "aws_kms_key" "parameter_store" {
+  description             = "Parameter store kms master key"
+  deletion_window_in_days = 10
+  enable_key_rotation     = true
+}
+
+resource "aws_kms_alias" "parameter_store_alias" {
+  name          = "alias/parameter_store_key"
+  target_key_id = "${aws_kms_key.parameter_store.id}"
+}
+```
+
+{{% dialog type="info" icon="fa-info-circle" title="Note" %}}
+Define `CHAMBER_KMS_KEY_ALIAS` environment variable to override the default of `alias/parameter_store_key`
+{{% /dialog %}}
+
+
+Also, we now have a Terraform Module to manage KMS keys: <https://github.com/cloudposse/terraform-aws-kms-key>
+
+```
+module "kms_key" {
+  source                  = "git::https://github.com/cloudposse/terraform-aws-kms-key.git?ref=master"
+  namespace               = "cp"
+  stage                   = "prod"
+  name                    = "app"
+  description             = "KMS key for chamber"
+  deletion_window_in_days = 10
+  enable_key_rotation     = "true"
+}
+```
+
+Then tell chamber to use this new key:
+
+```
+export CHAMBER_KMS_KEY_ALIAS="alias/cp-prod-app"
+```

content/faq/running-kubectl-fails-connection-refused.md

@@ -0,0 +1,40 @@
+---
+title: "Running `kubectl` fails: `The connection to the server localhost:8080 was refused`"
+excerpt: "This is most likely caused by not setting the `kubectl` context to use the kops cluster."
+tags:
+- kubectl
+- kubernetes
+- faq
+- kops
+---
+
+# Question
+
+When running `kubectl`, I get the following error:
+
+```
+kubectl get nodes
+The connection to the server localhost:8080 was refused - did you specify the right host or port?
+```
+
+# Answer
+
+This is most likely caused by not setting the `kubectl` context to use the kops cluster. 
+
+To fix this, run `kubectl export kubecfg --name us-west-2.staging.cloudposse.org` (replace our kops cluster name with yours or use the `$KOPS_CLUSTER_NAME` variable, if set). =)
+
+e.g.
+```
+kubectl export kubecfg --name $KOPS_CLUSTER_NAME
+```
+
+This will export the `kubecfg` to `/dev/shm`, temporary flash memory storage that should get erased when the container exits. 
+
+After running that command, you should be able to call `kubectl get nodes`. 
+
+{{% dialog type="info" icon="fa-info-circle" title="Note" %}}
+* You will need to re-run this command everytime you start the shell.
+* This command requires that you first have a valid session. Run `assume-role` to login to AWS.
+{{% /dialog %}}
+
+

content/faq/running-terraform-apply-on-iam-module-errors.md

@@ -0,0 +1,29 @@
+---
+title: "Running terraform apply on iam module errors with: The security token included in the request is invalid status code: 403"
+excerpt: "This is normally an issue with a bad aws-vault session"
+tags:
+- aws-vault
+- terraform
+- geodesic
+- aws
+- assumed-roles
+---
+
+# Question
+
+Running terraform apply on iam module errors with: 
+```
+The security token included in the request is invalid status code: 403
+```
+
+# Answer
+
+This is normally an issue with a bad aws-vault session. While we don't know what the root-cause is, deleting the offending sessions from the `.awsvault` sessions directory usually clears up the problem. 
+
+```
+find ~/.awsvault/ -name '* session *' -delete
+```
+
+(Also, if running in geodesic, use `/localhost/.awsvault/` instead of `~/.awsvault`)
+
+If that still doesn't fix the problem, you can run to delete the entire `.awsvault` folder and reinitialize the vault.

content/faq/signature-does-not-match-signature-expired.md

@@ -0,0 +1,30 @@
+---
+title: "SignatureDoesNotMatch: Signature expired"
+excerpt: "This usually happens due to time drift when running under Docker for Mac"
+tags:
+- aws-cli
+- aws
+- aws-vault
+- faq
+- geodesic
+- assume-role
+---
+
+# Question
+
+When attempting to `assume-role` or call `aws-vault exec`, it errors with a message like:
+
+```
+aws-vault: error: Failed to get credentials for joany (source profile for xxxxx-staging-admin): SignatureDoesNotMatch: Signature expired: 20180405T213414Z is now earlier than 20180405T220101Z (20180405T221601Z - 15 min.)
+        status code: 403, request id: ec5b2b11-391e-11e8-8986-bf22dc40d072
+```
+
+# Answer
+
+This usually happens due to time drift. If using Docker for Mac, this error is pretty common, especially on laptops which go into sleep or hibernation mode.
+
+Simply run the following command inside your `geodesic` shell to resync the time inside the VM.
+
+```
+hwclock -s
+```

content/faq/xcrun-error-invalid-active-developer-path.md

@@ -0,0 +1,32 @@
+---
+title: "xcrun: error: invalid active developer path"
+excerpt: "Reinstall xcode developer tools"
+tags:
+- osx
+- darwin
+- git
+- faq
+---
+
+# Question
+
+When using `git`, I get the following error on OSX:
+
+```
+xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools
+```
+
+# Answer
+
+This usually happens when upgrading to a new OSX release or on a new workstation.
+
+Try running the following command:
+
+```
+xcode-select --install
+```
+
+See: <https://stackoverflow.com/questions/32893412/command-line-tools-not-working-os-x-el-capitan-macos-sierra>
+
+
+