Skip to content

Commit 4a2f707

Browse files
ostermanosterman
authored
Add FAQ (#27)
* Add FAQ * add FAQ to menu * add ask-a-question button * display excerpts
1 parent 1537e46 commit 4a2f707

13 files changed

+372
-9
lines changed

‎config.toml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,13 @@ identifier = "blog"
7070
url = "https://cloudposse.com/blog/"
7171
weight = 40
7272

73+
[[menu.shortcuts]]
74+
pre = "<h3>More</h3>"
75+
name = "<i class='fa fa-question'></i> <label>FAQ</label>"
76+
identifier = "faq"
77+
url = "/faq/"
78+
weight = 45
79+
7380
[[menu.shortcuts]]
7481
pre = "<h3>More</h3>"
7582
name = "<i class='fa fa-question'></i> <label>Support</label>"

‎content/faq/_index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "FAQs"
3+
icon: "fa fa-question-circle"
4+
---

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "aws-vault: error: Failed to get credentials ... aes.KeyUnwrap(): integrity check failed."
3+
excerpt: "This horribly cryptic error message is a cryptographers way of saying \"wrong password\"."
4+
tags:
5+
- aws-vault
6+
- geodesic
7+
- faq
8+
---
9+
10+
# Question
11+
12+
When calling aws-vault exec or attempting to assume-role, I get the following error:
13+
14+
```
15+
Enter passphrase to unlock /conf/.awsvault/keys/:
16+
aws-vault: error: Failed to get credentials for peerstreet (source profile for cp-root-admin): aes.KeyUnwrap(): integrity check failed.
17+
```
18+
19+
# Answer
20+
21+
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. =)
22+
23+

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: "aws-vault: error: Failed to start credential server"
3+
excerpt: "This is usually caused by another geodesic shell running."
4+
tags:
5+
- geodesic
6+
- aws-vault
7+
- faq
8+
---
9+
10+
# Question
11+
12+
When running `aws-vault` or `assume-role`, I get the following error:
13+
14+
```
15+
aws-vault: error: Failed to start credential server: listen tcp 127.0.0.1:9099: bind: address already in use
16+
```
17+
18+
# Answer
19+
20+
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.
21+

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: "aws-vault outputs `'aws_access_key_id'` message and does nothing"
3+
excerpt: "This is usually because there's a `[default]` section in your `~/.aws/config`"
4+
tags:
5+
- geodesic
6+
- aws-vault
7+
- faq
8+
---
9+
10+
# Question
11+
12+
When calling `aws-vault exec` or using `assume-role` in `geodesic`, a single line is output that simply says:
13+
14+
```
15+
'aws_access_key_id'
16+
```
17+
18+
# Answer
19+
20+
This is usually because there's a `[default]` section in your `~/.aws/config`. Remove that and it should start to work.
21+

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: "Calling `chamber write` triggers `Error: InvalidKeyId: ... parameter_store_key is not found.`"
3+
excerpt: "Chamber expects to find a KMS key with alias `parameter_store_key`"
4+
---
5+
6+
# Question
7+
8+
```
9+
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)
10+
```
11+
12+
# Answer
13+
14+
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.
15+
16+
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).
17+
18+
We recommend using Terraform:
19+
```
20+
resource "aws_kms_key" "parameter_store" {
21+
description = "Parameter store kms master key"
22+
deletion_window_in_days = 10
23+
enable_key_rotation = true
24+
}
25+
26+
resource "aws_kms_alias" "parameter_store_alias" {
27+
name = "alias/parameter_store_key"
28+
target_key_id = "${aws_kms_key.parameter_store.id}"
29+
}
30+
```
31+
32+
{{% dialog type="info" icon="fa-info-circle" title="Note" %}}
33+
Define `CHAMBER_KMS_KEY_ALIAS` environment variable to override the default of `alias/parameter_store_key`
34+
{{% /dialog %}}
35+
36+
37+
Also, we now have a Terraform Module to manage KMS keys: <https://github.com/cloudposse/terraform-aws-kms-key>
38+
39+
```
40+
module "kms_key" {
41+
source = "git::https://github.com/cloudposse/terraform-aws-kms-key.git?ref=master"
42+
namespace = "cp"
43+
stage = "prod"
44+
name = "app"
45+
description = "KMS key for chamber"
46+
deletion_window_in_days = 10
47+
enable_key_rotation = "true"
48+
}
49+
```
50+
51+
Then tell chamber to use this new key:
52+
53+
```
54+
export CHAMBER_KMS_KEY_ALIAS="alias/cp-prod-app"
55+
```

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

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "Running `kubectl` fails: `The connection to the server localhost:8080 was refused`"
3+
excerpt: "This is most likely caused by not setting the `kubectl` context to use the kops cluster."
4+
tags:
5+
- kubectl
6+
- kubernetes
7+
- faq
8+
- kops
9+
---
10+
11+
# Question
12+
13+
When running `kubectl`, I get the following error:
14+
15+
```
16+
kubectl get nodes
17+
The connection to the server localhost:8080 was refused - did you specify the right host or port?
18+
```
19+
20+
# Answer
21+
22+
This is most likely caused by not setting the `kubectl` context to use the kops cluster.
23+
24+
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). =)
25+
26+
e.g.
27+
```
28+
kubectl export kubecfg --name $KOPS_CLUSTER_NAME
29+
```
30+
31+
This will export the `kubecfg` to `/dev/shm`, temporary flash memory storage that should get erased when the container exits.
32+
33+
After running that command, you should be able to call `kubectl get nodes`.
34+
35+
{{% dialog type="info" icon="fa-info-circle" title="Note" %}}
36+
* You will need to re-run this command everytime you start the shell.
37+
* This command requires that you first have a valid session. Run `assume-role` to login to AWS.
38+
{{% /dialog %}}
39+
40+

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: "Running terraform apply on iam module errors with: The security token included in the request is invalid status code: 403"
3+
excerpt: "This is normally an issue with a bad aws-vault session"
4+
tags:
5+
- aws-vault
6+
- terraform
7+
- geodesic
8+
- aws
9+
- assumed-roles
10+
---
11+
12+
# Question
13+
14+
Running terraform apply on iam module errors with:
15+
```
16+
The security token included in the request is invalid status code: 403
17+
```
18+
19+
# Answer
20+
21+
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.
22+
23+
```
24+
find ~/.awsvault/ -name '* session *' -delete
25+
```
26+
27+
(Also, if running in geodesic, use `/localhost/.awsvault/` instead of `~/.awsvault`)
28+
29+
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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "SignatureDoesNotMatch: Signature expired"
3+
excerpt: "This usually happens due to time drift when running under Docker for Mac"
4+
tags:
5+
- aws-cli
6+
- aws
7+
- aws-vault
8+
- faq
9+
- geodesic
10+
- assume-role
11+
---
12+
13+
# Question
14+
15+
When attempting to `assume-role` or call `aws-vault exec`, it errors with a message like:
16+
17+
```
18+
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.)
19+
status code: 403, request id: ec5b2b11-391e-11e8-8986-bf22dc40d072
20+
```
21+
22+
# Answer
23+
24+
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.
25+
26+
Simply run the following command inside your `geodesic` shell to resync the time inside the VM.
27+
28+
```
29+
hwclock -s
30+
```

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: "xcrun: error: invalid active developer path"
3+
excerpt: "Reinstall xcode developer tools"
4+
tags:
5+
- osx
6+
- darwin
7+
- git
8+
- faq
9+
---
10+
11+
# Question
12+
13+
When using `git`, I get the following error on OSX:
14+
15+
```
16+
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools
17+
```
18+
19+
# Answer
20+
21+
This usually happens when upgrading to a new OSX release or on a new workstation.
22+
23+
Try running the following command:
24+
25+
```
26+
xcode-select --install
27+
```
28+
29+
See: <https://stackoverflow.com/questions/32893412/command-line-tools-not-working-os-x-el-capitan-macos-sierra>
30+
31+
32+

‎layouts/_default/li.html

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,11 @@
33
<h2 class="post-title"><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
44
</header>
55
<section class="post-excerpt">
6-
<p>{{ .Summary | markdownify | plainify | htmlUnescape | default "Read More"}} <a class="read-more" href="{{.RelPermalink}}">&raquo;</a></p>
6+
{{ if .Params.excerpt }}
7+
<p>{{ .Params.excerpt | markdownify | plainify | htmlUnescape | default "Read More"}} <a class="read-more" href="{{.RelPermalink}}">read more &raquo;</a></p>
8+
{{ else }}
9+
<p>{{ .Summary | markdownify | plainify | htmlUnescape | default "Read More"}} <a class="read-more" href="{{.RelPermalink}}">read more &raquo;</a></p>
10+
{{ end }}
711
</section>
812
<footer class=" footline" >
913
{{- with .Params.LastModifierDisplayName -}}

‎layouts/partials/flex/body-beforecontent.html

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,14 +100,17 @@ <h1>The Cloud Posse Developer Hub</h1>
100100
</div>
101101
{{- end}}
102102
<h1 class="title">{{.Title}}</h1>
103-
<div class="github-link">
104-
<a href="{{ .Site.Params.editURL }}/content/{{ .File.Path }}" target="blank"><i class="fa fa-edit"></i>{{T "Edit-this-page"}}</a>
105-
</div>
106103
<div class="excerpt">
107104
{{ if .Params.excerpt }}
108105
<p>{{ .Params.excerpt | markdownify }}</p>
109106
{{ end }}
110107
</div>
108+
<div class="ask-a-question">
109+
<a class="button green" href="https://github.com/cloudposse/docs/issues/new?{{ (querify "title" (printf "Question about %s" .Title) "body" (printf "## Question\n\nDetails about your question...\n\n## References\n- <%s>" (.URL | absURL) ) ) | safeURL }}">Ask a Question</a>
110+
</div>
111+
<div class="github-link">
112+
<a href="{{ .Site.Params.editURL }}/content/{{ .File.Path }}" target="blank"><i class="fa fa-edit"></i>{{T "Edit-this-page"}}</a>
113+
</div>
111114
{{end}}
112115

113116
{{define "breadcrumb"}}

0 commit comments

Comments
 (0)