Skip to content

Commit aad1565

Browse files
mnapolimnapoli
committed
Restore the credentials documentation
1 parent ddad8f4 commit aad1565

File tree

2 files changed

+209
-111
lines changed

2 files changed

+209
-111
lines changed

‎docs/guides/credentials.md

+209
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# AWS Credentials
2+
3+
The Serverless Framework needs access to your cloud provider account so that it can create and manage resources on your behalf.
4+
5+
This guide is for the Amazon Web Services (AWS) provider, so we'll step through the process of setting up credentials for AWS and using them with Serverless.
6+
7+
## Sign up for an AWS account
8+
9+
If you already have an AWS account, skip to the next step to [create an IAM User and Access Key](#create-an-iam-user-and-access-key)
10+
11+
To create an AWS account:
12+
13+
1. Open https://aws.amazon.com/, and then choose Create an AWS Account.
14+
2. Follow the online instructions.
15+
16+
- Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad.
17+
18+
Note your AWS account ID, because you'll need it for the next task.
19+
20+
All AWS users get access to the Free Tier for [AWS Lambda](https://aws.amazon.com/lambda/pricing/). AWS Lambda is part of the non-expiring [AWS Free Tier](https://aws.amazon.com/free/#AWS_FREE_TIER). While in the AWS Free Tier, you can build an entire application on AWS Lambda, AWS API Gateway, and more, without getting charged for one year or longer, in some cases, as long as you don't exceed the resources in the free tier.
21+
22+
If you're new to Amazon Web Services, make sure you put in a credit card. If you don't have a credit card set up, you may not be able to deploy your resources and you may run into this error:
23+
24+
```
25+
AWS Access Key Id needs a subscription for the service
26+
```
27+
28+
## Create an IAM User and Access Key
29+
30+
Now that you have an AWS account, you need to configure AWS credentials so that `serverless` can deploy to AWS. For that, you can create AWS access keys and configure them on your machine.
31+
32+
### Creating AWS Access Keys
33+
34+
Follow these steps to create new AWS access keys:
35+
36+
1. Login to your AWS account and go to the Identity & Access Management (IAM) page.
37+
38+
2. Click on **Users** and then **Add user**. Enter a name in the first field to remind you this user is related to the Serverless Framework, like `serverless-admin`. Enable **Programmatic access** by clicking the checkbox. Click **Next** to go through to the Permissions page. Click on **Attach existing policies directly**. Search for and select **AdministratorAccess** then click **Next: Review**. Check to make sure everything looks good and click **Create user**.
39+
40+
3. View and copy the **API Key** & **Secret** to a temporary place. These are your AWS access keys.
41+
42+
Note that the above steps grant Serverless Framework administrative access to your account. While this makes things simple when starting out, we recommend that you create and use more fine-grained permissions once you determine the scope of your serverless applications and move them into production.
43+
44+
To limit the Serverless Framework’s access your AWS account, follow these steps to **create an IAM User** and attach a custom JSON file policy to your new IAM User. This IAM User will have its own set of AWS Access Keys.
45+
46+
1. Login to your AWS Account and go to the Identity & Access Management (IAM) page.
47+
48+
2. Click on **Users** and then **Add user**. Enter a name in the first field to remind you this User is related to the Service you are deploying with the Serverless Framework, like `serverless-servicename-agent`. Enable **Programmatic access** by clicking the checkbox. Click **Next** to go through to the Permissions page. Click on **Create policy**. Select the **JSON** tab, and add a JSON file. You can use [this gist](https://gist.github.com/ServerlessBot/7618156b8671840a539f405dea2704c8) as a guide.
49+
50+
When you are finished, select **Review policy**. You can assign this policy a **Name** and **Description**, then choose **Create Policy**. Check to make sure everything looks good and click **Create user**. Later, you can create different IAM Users for different apps and different stages of those apps. That is, if you don't use separate AWS accounts for stages/apps, which is most common.
51+
52+
3. View and copy the **API Key** & **Secret** to a temporary place. These are your AWS access keys.
53+
54+
### Using AWS Access Keys
55+
56+
You can configure the Serverless Framework to use your AWS access keys in two ways:
57+
58+
#### Quick Setup
59+
60+
As a quick setup to get started you can export them as environment variables so they would be accessible to Serverless and the AWS SDK in your shell:
61+
62+
```bash
63+
export AWS_ACCESS_KEY_ID=<your-key-here>
64+
export AWS_SECRET_ACCESS_KEY=<your-secret-key-here>
65+
# AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are now available for serverless to use
66+
serverless deploy
67+
68+
# 'export' command is valid only for unix shells
69+
# In Windows use 'set' instead of 'export'
70+
```
71+
72+
**Please note:** _If you are using a self-signed certificate you'll need to do one of the following:_
73+
74+
```bash
75+
# String example:
76+
# if using the 'ca' variable, your certificate contents should replace the newline character with '\n'
77+
export ca="-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----"
78+
# or multiple, comma separated
79+
export ca="-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----,-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----"
80+
81+
# File example:
82+
# if using the 'cafile' variable, your certificate contents should not contain '\n'
83+
export cafile="/path/to/cafile.pem"
84+
# or multiple, comma separated
85+
export cafile="/path/to/cafile1.pem,/path/to/cafile2.pem"
86+
87+
# 'export' command is valid only for unix shells
88+
# In Windows use 'set' instead of 'export'
89+
```
90+
91+
#### Using AWS Profiles
92+
93+
For a more permanent solution you can also set up credentials through AWS profiles. Here are different methods you can use to do so.
94+
95+
##### Setup with `serverless config credentials` command
96+
97+
Serverless provides a convenient way to configure AWS profiles with the help of the `serverless config credentials` command.
98+
99+
Here's an example how you can configure the `default` AWS profile:
100+
101+
```bash
102+
serverless config credentials \
103+
--provider aws \
104+
--key AKIAIOSFODNN7EXAMPLE \
105+
--secret wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
106+
```
107+
108+
Take a look at the [`config` CLI reference](../cli-reference/config-credentials.md) for more information about credential configuration.
109+
110+
##### Setup with the `aws-cli`
111+
112+
To set them up through the `aws-cli` [install it first](http://docs.aws.amazon.com/cli/latest/userguide/installing.html) then run `aws configure` [to configure the aws-cli and credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html):
113+
114+
```bash
115+
$ aws configure
116+
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
117+
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
118+
Default region name [None]: us-west-2
119+
Default output format [None]: ENTER
120+
```
121+
122+
Credentials are stored in INI format in `~/.aws/credentials`, which you can edit directly if needed. You can change the path to the credentials file via the AWS_SHARED_CREDENTIALS_FILE environment variable. Read more about that file in the [AWS documentation](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)
123+
124+
You can even set up different profiles for different accounts, which can be used by Serverless as well. To specify a default profile to use, you can add a `profile` setting to your `provider` configuration in `serverless.yml`:
125+
126+
```yml
127+
service: new-service
128+
provider:
129+
name: aws
130+
runtime: nodejs14.x
131+
stage: dev
132+
profile: devProfile
133+
```
134+
135+
##### Use an existing AWS Profile
136+
137+
To easily switch between projects without the need to do `aws configure` every time you can use environment variables.
138+
For example you define different profiles in `~/.aws/credentials`
139+
140+
```ini
141+
[profileName1]
142+
aws_access_key_id=***************
143+
aws_secret_access_key=***************
144+
145+
[profileName2]
146+
aws_access_key_id=***************
147+
aws_secret_access_key=***************
148+
```
149+
150+
Now you can switch per project (/ API) by executing once when you start your project:
151+
152+
`export AWS_PROFILE="profileName2"`.
153+
154+
in the Terminal. Now everything is set to execute all the `serverless` CLI options like `sls deploy`.
155+
156+
##### Using the `aws-profile` option
157+
158+
You can always specify the profile which should be used via the `aws-profile` option like this:
159+
160+
```bash
161+
serverless deploy --aws-profile devProfile
162+
```
163+
164+
##### Using web identity token
165+
166+
To use web identity token authentication the `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN` environment need to be set. It is automatically set if you specify a service account in AWS EKS.
167+
168+
#### Per Stage Profiles
169+
170+
As an advanced use-case, you can deploy different stages to different accounts by using different profiles per stage. In order to use different profiles per stage, you must leverage [variables](./variables.md) and the provider profile setting.
171+
172+
This example `serverless.yml` snippet will load the profile depending upon the stage specified in the command line options (or default to 'dev' if unspecified);
173+
174+
```yml
175+
service: new-service
176+
provider:
177+
name: aws
178+
runtime: nodejs14.x
179+
profile: ${self:custom.profiles.${sls:stage}}
180+
custom:
181+
profiles:
182+
dev: devProfile
183+
prod: prodProfile
184+
```
185+
186+
#### Profile in place with the 'invoke local' command
187+
188+
**Be aware!** Due to the way AWS IAM and the local environment works, if you invoke your lambda functions locally using the CLI command `serverless invoke local -f ...` the IAM role/profile could be (and probably is) different from the one set in the `serverless.yml` configuration file.
189+
Thus, most likely, a different set of permissions will be in place, altering the interaction between your lambda functions and other AWS resources.
190+
191+
_Please, refer to the [`invoke local`](../cli-reference/invoke-local.md#aws---invoke-local) CLI command documentation for more details._
192+
193+
## Assuming a role when deploying
194+
195+
It is possible to use local AWS credentials to _assume_ another AWS role.
196+
197+
That allows the deployment (and all other CLI commands) to be performed under a different role. To achieve this, [follow this documentation from AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html).
198+
199+
Note that `serverless.yml` also offers the `provider.iam.deploymentRole` option. This lets us force CloudFormation to use a different role when deploying:
200+
201+
```yml
202+
provider:
203+
iam:
204+
deploymentRole: arn:aws:iam::123456789012:role/deploy-role
205+
```
206+
207+
It is important to understand that `deploymentRole` only affects the role CloudFormation will assume. All other interactions from the `serverless` CLI with AWS will not use that `deploymentRole`.
208+
209+
This is why we usually recommend using the "assume role" method described above instead of `deploymentRole`.

0 commit comments

Comments
 (0)