Skip to content

Commit f3f73c1

Browse files
authored
Replace aws-auth with Leapp (#540)
1 parent 25cc978 commit f3f73c1

File tree

11 files changed

+1566
-997
lines changed

11 files changed

+1566
-997
lines changed

Dockerfile

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,17 @@ ENV HUGO_PORT=1313 \
1111

1212
EXPOSE $HUGO_PORT
1313

14-
ARG APT_PACKAGES="python3 python3-pip locales jq"
14+
ARG APT_PACKAGES="python3 python3-pip locales jq less"
1515
RUN apt-get update && \
1616
apt-get install -y ${APT_PACKAGES} && \
1717
rm -rf /var/lib/apt/lists/* && \
1818
localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8 && \
1919
npm install -g atomic-algolia@0.3.15 cloudflare-cli@4.1.0 && \
2020
pip3 install asciinema
2121

22+
# Update yarn
23+
RUN curl --compressed -o- -L https://yarnpkg.com/install.sh | bash
24+
2225
COPY Makefile ./
2326

2427
RUN make init

Makefile

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ export HUGO_PORT ?= 1313
66
export HUGO_URL ?= http://localhost.cloudposse.com:$(HUGO_PORT)/
77
export HUGO_EDIT_BRANCH ?= $(GIT_BRANCH)
88
export HUGO_EDIT_URL ?= https://github.com/cloudposse/docs/blob/$(HUGO_EDIT_BRANCH)
9-
export HUGO_ARGS ?= --bind 0.0.0.0 --port $(HUGO_PORT) --watch --buildDrafts
9+
# Add --disableLiveReload to HUGO_ARGS if the live reloads are annoying you
10+
export HUGO_ARGS ?= --bind 0.0.0.0 --port $(HUGO_PORT) --buildDrafts --poll 1s
1011
export HUGO_CONFIG ?= config.yaml
1112
export HUGO_PUBLISH_DIR ?= public
1213
export PACKAGES_VERSION ?= 0.93.0

content/documentation/getting-started.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Here are some of the most important tools to be aware of:
2626
- [`chamber`]({{< relref "reference/tools.md#chamber" >}})
2727
- [`terraform`]({{< relref "reference/tools.md#terraform" >}})
2828
- [`gomplate`]({{< relref "reference/tools.md#gomplate" >}})
29-
- [`aws-vault`]({{< relref "reference/tools.md#aws-vault" >}})
29+
- [Leapp]({{< relref "reference/tools.md#leapp" >}})
3030

3131
If using kubernetes, then also review these tools:
3232

content/glossary/aws-vault.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,6 @@ tags:
88
- aws
99
- IAM
1010
---
11-
`aws-vault` is a utility for securely managing secrets with AWS Systems Manager (SSM) Parameter Store and KMS
11+
_(Deprecated)_ `aws-vault` is a utility for securely managing secrets with AWS Systems Manager (SSM)
12+
Parameter Store and KMS. It used to be Cloud Posse's recommended tool for this purpose, but
13+
for various reasons we now recommend using [Leapp](htpps://leapp.cloud) instead.

content/howto/geodesic/authenticate-with-aws-vault.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
11
---
2-
title: "Authenticate with AWS inside Geodesic using `aws-vault`"
2+
title: "Authenticate with AWS inside of Geodesic using `aws-vault` _(Deprecated)_"
33
description: "Learn how to authenticate within Geodesic using AWS IAM Credentials and `aws-vault`."
4-
weight: 1
4+
weight: 99
55
---
66

77
## Intro
88

9-
In this how-to, we'll provide a quick step-by-step guide on authenticating with AWS inside Geodesic.
9+
In this how-to, we'll provide a step-by-step guide on
10+
how we used to recommend authenticating with AWS inside of Geodesic, using `aws-vault`.
11+
This remains for historical reference and for companies who have been using
12+
`aws-vault` for a while and want to train new users. **Cloud Posse no longer
13+
recommends this workflow. See** [Authenticate with AWS using Leapp]({{< relref "howto/geodesic/authenticate-with-leapp.md" >}}) **for the currently recommended procedure.**
1014

1115
## Prerequisites
1216

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
title: "Authenticate with AWS using Leapp"
3+
description: "Learn how to use Leapp to supply AWS credentials to tools used within Geodesic."
4+
weight: 1
5+
---
6+
## Intro
7+
8+
In this how-to, we will help you get started using Geodesic to work with AWS
9+
resources by helping you set up and use [Leapp](https://leapp.cloud) to handle
10+
credentials and authentication. Leapp is an open-source tool that makes this easier.
11+
12+
## Prerequisites
13+
14+
### SweetOps Know-how
15+
16+
We expect you've gone through the tutorial on ["Getting started with Geodesic"]({{< relref "tutorials/geodesic-getting-started.md" >}}) prior to this How-To since that contains some important understanding of what Geodesic is, how it works, and what it's doing.
17+
18+
### AWS Region and Credentials
19+
20+
#### Region
21+
22+
It will be helpful to know which AWS Region you will be primarily working in.
23+
This should be fairly common knowledge among people with AWS access at your
24+
company. If you are doing this on your own, choose the region closest to
25+
you geographically. If you are still in doubt, pick
26+
- `ca-central-1` if in Canada,
27+
- `us-east-2` if in the United States east of the Mississippi,
28+
- `us-west-2` if anywhere else in the North America or anywhere in Central America,
29+
- `sa-east-1` if in South America,
30+
- `eu-north-1` if in Europe,
31+
- `af-south-1` if in Africa,
32+
- `ap-south-1` if in Asia, or
33+
- `ap-southeast-2` if in Australia or Antarctica.
34+
35+
#### Credentials
36+
37+
You will have to have some way of authenticating to AWS already set up, and you
38+
need to know the nature of your credentials. Whoever gave you access to AWS
39+
should be able to tell you what kind of access you have. It should be one of the following:
40+
41+
- **Federated Role** (recommended). This means you log into something you use to
42+
identify yourself to a lot of places (usually refered to as Single Sign-On
43+
or SSO), and it is set up to log you into AWS with a specific IAM Role as well.
44+
At a company, this is usually Google Workspaces (formerly GSuite),
45+
Okta, or Active Directory. This is also known as a SAML IdP.
46+
- **AWS SSO**. This means your company has configured AWS as a Single Sign-On
47+
provider. This is AWS _as_ a Single Sign-On provider, allowing you to access
48+
multiple _permission sets_ within AWS, not using some
49+
other Single Sign-On provider to sign in to AWS as a single IAM Role.
50+
Please note that even if your company has set up AWS _as_ a Single Sign-On provider, you still may be using your company's primary SSO provider to authenticate to AWS SSO.
51+
- **AWS IAM User**. This is the older way of authenticating to AWS, with a basic
52+
username and password to log into the AWS console,
53+
and a long-lived "Access Key" for API access. If you are going to use this
54+
method, we strongly recommend that you enable multi-factor authentication (MFA).
55+
56+
Based on which kind of credentials you have, you will need to gather different
57+
information with which to configure Leapp. Whoever is in charge of setting up
58+
your access to AWS should be able to give you the information you need.
59+
60+
##### Federated Role
61+
62+
If using Federated Login, you will need
63+
- Your IdP Single Sign-On URL.
64+
- For Google Workspaces, it looks something like
65+
`https://accounts.google.com/o/saml2/initsso?idpid=C0asdfasdfal&spid=12344321`.
66+
- For Okta, it looks something like `https://company.okta.com/app/company_samlidp_1/Hka1abcke6h4P1WQr5d7/sso/saml`.
67+
- Most importantly,it should not be confused with the AWS Single Sign-On URLs
68+
like these (**do not use these**)
69+
- `https://signin.aws.amazon.com/saml` (this is used by your IdP admin)
70+
- `https://my-sso-portal.awsapps.com/start` (this means you are using AWS SSO)
71+
- The AWS Identity Provider ARN assigned by AWS to your IdP. Something like
72+
- `arn:aws:iam::123434211234:saml-provider/company-name`
73+
- Your assigned/authorized AWS IAM Role ARN. Something like
74+
- `arn:aws:iam::123434211234:role/role-name`
75+
76+
##### AWS SSO
77+
78+
If using AWS SSO, you will need:
79+
80+
- Your AWS SSO "start URL", also known as your "portal URL". It should be
81+
very close to:
82+
- `https://something.awsapps.com/start`
83+
- The region in which AWS SSO has been deployed. This may or may not be the same
84+
region you will be working in.
85+
86+
##### AWS IAM User
87+
88+
If you are a regular IAM User who can log into the AWS Console, you should
89+
log into the AWS Console while setting up Leapp. Choose "My Security Credentials"
90+
from the Account drop-down menu:
91+
- Copy and paste your MFA ARN or Serial Number from "Assigned MFA device"
92+
- Click on "Create access key" to create a new access key and copy the
93+
Access Key ID and Secret Access Key from the console and paste directly into
94+
the appropriate fields in Leapp.
95+
96+
## How-To
97+
98+
### Start Geodesic
99+
100+
If you are a Cloud Posse client, you will have a customized version of Geodesic
101+
that sets an initial value for the environment variable `AWS_PROFILE`. Alternatively,
102+
you may have customized it yourself, or you may want to. In any case, we will
103+
go with what you have. So start Geodesic, and at the command prompt, type
104+
105+
```bash
106+
echo $AWS_PROFILE
107+
```
108+
109+
This is the value you will give to the profile in Leapp when you configure it.
110+
If the output of `echo` is blank, as would be expected if you are running
111+
our public tutorial image, use "default" for the profile name.
112+
113+
### Install and Configure Leapp
114+
115+
Please refer to the official Leapp documentation
116+
for the latest instructions on installing and configuring Leapp.
117+
Now that you are armed with the information from
118+
the previous steps, it should be pretty easy.
119+
120+
- Visit the [Leapp website](https://leapp.cloud)
121+
- Download and install Leapp as instructed by the website
122+
- Follow the instructions (under "Docs") for configuring AWS
123+
124+
Below is some guidance to the Leapp documentation that applies as of the
125+
time of this writing. By the time you read this it may be out of date, but
126+
hopefully will still be of help in guiding you through the Leapp site.
127+
128+
##### Key Points
129+
130+
- The "AWS Profile" setting in Leapp must match _exactly_ the value of
131+
`$AWS_PROFILE` you found in Geodesic in the earlier step.
132+
- The "AWS Region" you set in the Leapp session should be the AWS Region you
133+
most often use, as discussed [above](#aws-region-and-credentials).
134+
- The "Session Alias" is completely up to you: it is the name for this
135+
set of credentials that you will see in the UI.
136+
137+
The Leapp documentation is at [https://docs.leapp.cloud/](https://docs.leapp.cloud/)
138+
and the best set of instructions to follow are the ones under a sub-menu on the left
139+
side of the page: **Tutorials > AWS**
140+
141+
- If you have a **Federated Login**, pick "AWS IAM Federated Role". Most of the
142+
tutorial is about how to configure Federated Login itself, and you can skip
143+
all that. Just follow the last step: "Setup in Leapp".
144+
- Otherwise, pick "AWS SSO" or "AWS IAM User" and follow the steps.
145+
146+
147+
### Log in using Leapp
148+
149+
Leapp provides 2 UIs for logging into or out of a session. There is a system-wide menu item
150+
in the taskbar on Windows systems or as a "status menu" on the Mac menu bar. Click on it
151+
and a menu will appear with all your configured session names and their corresponding
152+
profile names. An icon for each session will appear either in gray if logged out
153+
or orange if logged in (at least those are the current defaults for the "Light" color
154+
scheme on macOS). Just select the menu item to toggle the state.
155+
156+
Alternately, you can select "Show" from the menu and be shown a richer UI where
157+
you can do more, but still the main thing is that you click on a session name
158+
to change its state and the indicator shows gray for logged out and orange for logged in.
159+
160+
If you are not using IAM user access keys then in order to access AWS you will have
161+
to log in to your "identity provider" (e.g. Okta, Google) like you do for access
162+
to other resources. Therefore, when you try to activate a session in Leapp,
163+
it may open a small web browser window popup or open a window or tab in your
164+
default browser so you can complete the login flow, including supplying
165+
a second factor if you are using MFA, and perhaps solving a CAPTCHA puzzle. This
166+
is normal and expected behavior, not a virus or hacking attempt. When you finish
167+
logging in via the web browser, Leapp uses the credentials provided by your
168+
identity provider to authenticate to AWS, just as if you were logging into
169+
the AWS web console or SSO portal.
170+
171+
Like your web browser, Leapp can store cookies and other information, and
172+
in addition, Leapp is able to use your system keychain for secure
173+
storage of other things like your Secret Access Key. Because of this,
174+
and depending on your identity provider and their settings, simply being
175+
logged into your computer may be enough authentication for Leapp to grant
176+
you access when you enable a session without asking you for anything.
177+
However, AWS requires periodic refreshing of session keys and if you are
178+
using MFA with AWS, you should enable Leapp notifications
179+
so you can receive prompts when your AWS session expires and
180+
Leapp needs a new MFA token in order to start a new session for you.
181+
182+
### It should just work
183+
184+
Once you log in to AWS using Leapp, go back into Geodesic and simply hit return
185+
at the prompt. The prompt should change from having a red ✗ and `[none]` to
186+
having a green √ and `[default]` or whatever your profile name is. This is
187+
Geodesic's way of letting you know you are authorized with AWS, and what
188+
profile you have active.
189+
190+
You can always confirm your current authentication status by running:
191+
192+
```bash
193+
aws sts get-caller-identity
194+
```
195+
196+
When you are properly authenticated, it will output your IAM role and other
197+
information. When you are logged out, it will print some kind of error message,
198+
usually:
199+
```text
200+
Unable to locate credentials. You can configure credentials by running "aws configure".
201+
```

content/howto/geodesic/build-your-own-toolbox.md

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,41 @@ weight: 1
55
draft: true
66
---
77

8-
Note: These are just scratch notes (in "draft") for now while we're building out the tutorial. I orginally had these in the tutorial, but wanted to keep that simple and figured I'd keep the below content around for usage here.
8+
Note: These are just scratch notes (in "draft") for now while we're building out the tutorial. I originally had these in the tutorial, but wanted to keep that simple and figured I'd keep the below content around for usage here.
9+
10+
Copy "Dockerfile.custom" from Geodesic repo and edit to taste (and of course,
11+
rename it to "Dockerfile")
912

1013
```Dockerfile
14+
1115
ARG VERSION=0.142.0
1216
ARG OS=debian
1317

1418
FROM cloudposse/geodesic:$VERSION-$OS
1519

16-
ENV AWS_VAULT_ENABLED=true
17-
ENV AWS_VAULT_SERVER_ENABLED=true
18-
ENV AWS_VAULT_BACKEND=file
19-
20-
RUN apt-get install -y your-needed-package
20+
RUN apt-get update && apt-get install -y your-needed-package
2121

2222
# ... The rest of your configuration
2323
```
2424

25+
Copy "Makefile.custom" from Geodesic repo and edit to taste (and of course,
26+
rename it to "Makefile")
27+
28+
```Dockerfile
29+
30+
export APP_NAME = acme
31+
export DOCKER_ORG ?= acmecorp
32+
export DOCKER_IMAGE ?= $(DOCKER_ORG)/toolbox
33+
```
34+
35+
Then run `make` to build and install your toolbox.
36+
2537
```bash
2638
# Build the toolbox for your Organization (Acme Corp)
27-
docker build . -t acme:latest
39+
make build
2840

2941
# Install on your machine as your own executable toolbox
30-
docker run --rm acme:latest | APP_NAME=acme bash -s latest-debian
42+
make install
3143

3244
# Start a new shell in your toolbox
3345
acme

0 commit comments

Comments
 (0)