Try AWS Native preview for resources not in the classic version.
AWS Classic: Installation & Configuration
Try AWS Native preview for resources not in the classic version.
If you do not already have an AWS account, you can create a free AWS 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.
Installation
The AWS Classic provider is available as a package in all Pulumi languages:
- JavaScript/TypeScript:
@pulumi/aws
- Python:
pulumi-aws
- Go:
github.com/pulumi/pulumi-aws/sdk/v5
- .NET:
Pulumi.Aws
- Java:
com.pulumi.aws
Credentials
- Create an IAM user in the AWS console with programmatic access and ensure it has sufficient permissions to deploy and manage your Pulumi program’s resources.
- Set up AWS credentials for your user.
AWS_SESSION_TOKEN
value before you can use Pulumi to create resources on your behalf.Your AWS credentials are never sent to pulumi.com. Pulumi uses the AWS SDK and the credentials in your environment to authenticate requests from your computer to AWS.
Configuration
There are a few different ways you can configure your AWS credentials to work with Pulumi.
Set credentials as environment variables
You can authenticate using environment variables. Doing so will temporarily override the settings in your credentials file.
$ export AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
$ export AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
$ export AWS_REGION=<YOUR_AWS_REGION> # e.g.`ap-south-1`
$ export AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
$ export AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
$ export AWS_REGION=<YOUR_AWS_REGION> # e.g.`ap-south-1`
> $env:AWS_ACCESS_KEY_ID = "<YOUR_ACCESS_KEY_ID>"
> $env:AWS_SECRET_ACCESS_KEY = "<YOUR_SECRET_ACCESS_KEY>"
> $env:AWS_REGION = "<YOUR_AWS_REGION>"
You may alternatively set the AWS region in your Pulumi.yaml:
$ pulumi config set aws:region <your-region> # e.g.`ap-south-1`
Create a shared credentials file using the AWS CLI
Configure your AWS credentials.
$ aws configure AWS Access Key ID [None]: <YOUR_ACCESS_KEY_ID> AWS Secret Access Key [None]: <YOUR_SECRET_ACCESS_KEY> Default region name [None]: <YOUR_AWS_REGION> Default output format [None]:
Your AWS credentials file is now located in your home directory at .aws/credentials
.
You can also create the shared credentials file by hand. For example:
[default]
aws_access_key_id = <YOUR_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>
Set up multiple profiles
As an optional step, you can set up multiple profiles Here’s what that looks like in your ~/.aws/credentials file:
[default]
aws_access_key_id = <YOUR_DEFAULT_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_DEFAULT_SECRET_ACCESS_KEY>
[test-account]
aws_access_key_id = <YOUR_TEST_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_TEST_SECRET_ACCESS_KEY>
[prod-account]
aws_access_key_id = <YOUR_PROD_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_PROD_SECRET_ACCESS_KEY>
You can specify which profile to use with Pulumi through one of the following methods:
Set AWS_PROFILE as an environment variable
$ export AWS_PROFILE=<YOUR_PROFILE_NAME>
Set
aws:profile
in your Pulumi.yamlpulumi config set aws:profile <profilename>
Authenticating via EC2 Instance Metadata?
As of pulumi-aws v3.28.1, the default behaviour for the provider was changed to disable MetadataApiCheck by default. This means, you need to do either of the following
When using the default provider:
pulumi config set aws:skipMetadataApiCheck false
When using a named provider
const myProvider = new aws.Provider("named-provider", { // other config skipMetadataApiCheck: false, });
var provider = new Aws.Provider("named-provider", new Aws.ProviderArgs { // other config SkipMetadataApiCheck = false, });
provider, err := aws.NewProvider(ctx, "named-provider", &aws.ProviderArgs{ // other config SkipMetadataApiCheck: pulumi.Bool(false), })
provider = pulumi_aws.Provider('named-provider', skip_metadata_api_check=False)
Configuration options
Use pulumi config set aws:<option>
or pass options to the constructor of new aws.Provider
.
Option | Required? | Description |
---|---|---|
region | Required | The region where AWS operations will take place. Examples are us-east-1 , us-west-2 , etc. |
allowedAccountIds | Optional | List of allowed AWS account IDs to prevent you from mistakenly using an incorrect one (and potentially end up destroying a live environment). Conflicts with forbiddenAccountIds . |
accessKey | Optional | The access key for API operations. You can retrieve this from the ‘Security & Credentials’ section of the AWS console. |
assumeRole | Optional | A JSON object representing an IAM role to assume. To set these nested properties, see docs on structured configuration, for example pulumi config set --path aws:assumeRole.roleArn arn:aws:iam::058111598222:role/OrganizationAccountAccessRole . The object contains the properties marked with a ↳ below: |
↳ durationSeconds | Optional | Number of seconds to restrict the assume role session duration. |
↳ externalId | Optional | External identifier to use when assuming the role. |
↳ policy | Optional | IAM Policy JSON describing further restricting permissions for the IAM Role being assumed. |
↳ policyArns | Optional | Set of Amazon Resource Names (ARNs) of IAM Policies describing further restricting permissions for the IAM Role being assumed. |
↳ roleArn | Optional | Amazon Resource Name (ARN) of the IAM Role to assume. |
↳ sessionName | Optional | Session name to use when assuming the role. |
↳ tags | Optional | Map of assume role session tags. |
↳ transitiveTagKeys | Optional | Set of assume role session tag keys to pass to any subsequent sessions. |
dynamodbEndpoint | Optional | Use this to override the default endpoint URL constructed from the region . It’s typically used to connect to dynamodb-local. |
forbiddenAccountIds | Optional | List of forbidden AWS account IDs to prevent you from mistakenly using the wrong one (and potentially end up destroying a live environment). Conflicts with allowedAccountIds . |
defaultTags | Optional | A JSON block with resource tag settings to apply across all resources handled by this provider. Additional tags can be added/overridden at a per resource level. The object contains the properties marked with a ↳ below: |
↳ tags | Optional | A key value pair of tags to apply across all resources. |
ignoreTags | Optional | A JSON block with resource tag settings to ignore across all resources handled by this provider (except any individual service tag resources such as aws.ec2.Tag ) for situations where external systems are managing certain resource tags. The object contains the properties marked with a ↳ below: |
↳ keys | Optional | A list of exact resource tag keys to ignore across all resources handled by this provider. This configuration prevents Pulumi from returning the tag in any tags properties and displaying any diffs for the tag value. If any resource still has this tag key configured in the tags argument, it will display a perpetual diff until the tag is removed from the argument or ignoreChanges is also used. |
↳ keyPrefixes | Optional | A list of resource tag key prefixes to ignore across all resources handled by this provider. This configuration prevents Pulumi from returning the tag in any tags properties and displaying any diffs for the tag value. If any resource still has this tag key configured in the tags argument, it will display a perpetual diff until the tag is removed from the argument or ignoreChanges is also used. |
insecure | Optional | Explicitly allow the provider to perform “insecure” SSL requests. If omitted, the default value is false . |
kinesisEndpoint | Optional | Use this to override the default endpoint URL constructed from the region . It’s typically used to connect to kinesalite. |
maxRetries | Optional | The maximum number of times an AWS API request is being executed. If the API request still fails, an error is thrown. |
profile | Optional | The profile for API operations. If not set, the default profile created with aws configure will be used. |
s3ForcePathStyle | Optional | Set this to true to force the request to use path-style addressing, i.e., http://s3.amazonaws.com/BUCKET/KEY . By default, the S3 client will use virtual hosted bucket addressing when possible (http://BUCKET.s3.amazonaws.com/KEY ). Specific to the Amazon S3 service. |
secretKey | Optional | The secret key for API operations. You can retrieve this from the ‘Security & Credentials’ section of the AWS console. |
sharedCredentialsFile | Optional | The path to the shared credentials file. If not set this defaults to ~/.aws/credentials . |
skipCredentialsValidation | Optional | Skip the credentials validation via STS API. Used for AWS API implementations that do not have STS available/implemented. |
skipGetEc2Platforms | Optional | Skip getting the supported EC2 platforms. Used by users that don’t have ec2:DescribeAccountAttributes permissions. |
skipMetadataApiCheck | Optional | Skip the AWS Metadata API check. Useful for AWS API implementations that do not have a metadata API endpoint. Setting to true prevents Pulumi from authenticating via the Metadata API. You may need to use other authentication methods like static credentials, configuration variables, or environment variables. |
skipRegionValidation | Optional | Skip static validation of region name. Used by users of alternative AWS-like APIs or users w/ access to regions that are not public (yet). |
skipRequestingAccountId | Optional | Skip requesting the account ID. Used for AWS API implementations that do not have IAM/STS API and/or metadata API. |
token | Optional | Use this to set an MFA token. It can also be sourced from the AWS_SESSION_TOKEN environment variable. |
Try AWS Native preview for resources not in the classic version.