AWS Setup

The Pulumi AWS provider uses the AWS SDK to manage and provision resources.

If you do not already have an AWS account, you can create a free account. Most resources in our examples fall within the AWS Free Tier, but we encourage you to follow the cleanup steps at the end of each section to avoid paying for resources you aren't using.

There are multiple ways to connect Pulumi to your AWS credentials. The SDK instructions cover this in detail – including advanced options – however we will look at the two most popular approaches below:

  • Environment variables
  • A shared credentials file, usually managed by the AWS CLI

Getting Your Credentials

In either case, you will need to make sure you have an IAM user in the AWS console with Programmatic access. The IAM user should have sufficient rights to deploy and manage your program’s resources. If you know the precise kinds of resources you wish to create and delete, you can restrict the IAM user accordingly. You’ll also need an access key for your user.

There are two parts to each key, both shown in the IAM console after creating it:

  • <YOUR_ACCESS_KEY_ID>: your access key’s ID
  • <YOUR_SECRET_ACCESS_KEY>: your access key’s secret

No matter which option you pick, Pulumi uses the AWS SDK to authenticate requests from your computer to AWS. As a result, your AWS credentials are never sent to

Shared Credentials File

A credentials file is a plaintext file on your machine that contains your access keys. The file must be named credentials and is located underneath .aws/ directory in your home directory. This approach is recommended because it supports Amazon’s recommended approach for securely managing multiple roles.

Using the CLI

To create this file using the CLI, you must first install the AWS CLI. If you’re using Homebrew on macOS, you can use the community-managed awscli via brew install awscli.

After installing the CLI, configure it with your IAM credentials, typically using the aws configure command. For other configuration options, see the AWS article Configuring the AWS CLI.

$ aws configure
AWS Access Key ID [None]: <YOUR_ACCESS_KEY_ID>
AWS Secret Access Key [None]: <YOUR_SECRET_ACCESS_KEY>
Default region name [None]:
Default output format [None]:

This will have created the ~/.aws/credentials file and populated it with the expected settings.

Creating By Hand

It is possible to create this file by hand. For example:

aws_access_key_id = <YOUR_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>

If you want to specify multiple profiles, those are listed in different sections:

aws_access_key_id = <YOUR_DEFAULT_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_DEFAULT_SECRET_ACCESS_KEY>

aws_access_key_id = <YOUR_TEST_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_TEST_SECRET_ACCESS_KEY>

aws_access_key_id = <YOUR_PROD_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_PROD_SECRET_ACCESS_KEY>

In this case, you will need to set the AWS_PROFILE environment variable to the name of the profile to use.

Environment Variables

Although credentials are recommended, the SDK will prefer environment variables over any other settings:


This makes it easy to temporarily override your credentials settings, quickly switch to a different access key, or configure AWS access from within an environment that might not have an AWS CLI, such as inside of CI.

To configure these, set them in your workstation terminal application.



As an optional step, if you have multiple AWS profiles set up, you can specify a different profile to use with Pulumi through one of the following methods:

  • Set AWS_PROFILE as an environment variable.
  • After creating your project, run pulumi config set aws:profile <profilename>. For more configuration options, see AWS Configuration.