1. Packages
  2. AWS
  3. Installation & Configuration
AWS v6.55.0 published on Monday, Oct 7, 2024 by Pulumi

AWS: Installation & Configuration

aws logo
AWS v6.55.0 published on Monday, Oct 7, 2024 by Pulumi

    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 provider is available as a package in all Pulumi languages:

    Credentials

    1. 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.
    2. Set up AWS credentials for your user.
    If you are using temporary security credentials, you will also have to supply an 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

    We recommend using a shared credentials file for most development. However, if you need to temporarily override your credentials file, you can use environment variables. You can do this to quickly switch to a different access key or to configure AWS access from within an environment that might not have an AWS CLI, such as a continuous integration/continuous delivery (CI/CD) system.

    To authenticate using environment variables, set them in your terminal:

    $ 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.<stack-name>.yaml file:

    $ pulumi config set aws:region <your-region> # e.g.`ap-south-1`
    

    Create a 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. We recommend this approach because it supports Amazon’s recommended approach for securely managing multiple roles.

    Option 1: Use the CLI

    To create this file using the CLI, 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]:
    

    Now you’ve created the ~/.aws/credentials file and populated it with the expected settings.

    Option 2: Create by hand

    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>
    

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

    [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>
    

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

    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.yaml

      pulumi 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

    1. When using the default provider:

      pulumi config set aws:skipMetadataApiCheck false
      
    2. 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)
      

    Authenticate with WebIdentity and OpenID Connect (OIDC)

    In this approach, you configure an AWS role to assume and a source for a web identity token, which is an OIDC ID token. The token is used to authenticate with AWS and obtain temporary credentials. The temporary credentials are then used to access AWS resources. This mode of authentication allows you to run Pulumi on a service that supports OIDC like GitHub, GitLab, or Azure DevOps, and access AWS without storing credentials.

    Please refer to the AWS docs About web identity federation and Assume role with web identity for more details. Also, refer to the particular service’s documentation for how to configure the OIDC trust relationship, which is a one-time setup.

    If your Pulumi program runs on GitHub, you don’t need to configure the identity token in most cases. Amazon have published GitHub workflows action configure-aws-credentials which handles the token. You only configure the role to assume in your GitHub workflow definition:

      uses: aws-actions/configure-aws-credentials@v4
      with:
        aws-region: ${{ env.AWS_REGION }}
        role-session-name: <NAME>
        role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>
    

    In other cases, you will need to configure the assumeRoleWithWebIdentity object documented in the Configuration options section of this page. At a minimum, you will need to define the role to assume and the source of the token. In Pulumi config it should look this:

    config:
      aws:assumeRoleWithWebIdentity:
        roleArn: arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>
        # Define either webIdentityToken or webIdentityTokenFile
        webIdentityToken: <your-web-identity-token>
        webIdentityTokenFile: webidentitytokenfile.txt
    

    Dynamically generate credentials via Pulumi ESC

    In addition to configuring the AWS provider locally, you also have the option to centralize your configurations using Pulumi ESC (Environments, Secrets, and Configuration). Using this service will enable you to run AWS or Pulumi CLI commands with dynamically generated credentials, removing the need to configure and manage your credentials locally.

    To do this, you will need to complete the following steps:

    Configure OIDC between Pulumi and AWS

    Refer to the Configuring OpenID Connect for AWS Guide for the step-by-step process on how to do this. Note that when adding your configuration to your environment file, you can also define your AWS region in the environmentVariables section:

    values:
      aws:
        login:
          fn::open::aws-login:
            oidc:
              duration: 1h
              roleArn: <your-oidc-iam-role-arn>
              sessionName: pulumi-environments-session
      environmentVariables:
        AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
        AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
        AWS_SESSION_TOKEN: ${aws.login.sessionToken}
        AWS_REGION: <YOUR_AWS_REGION> # e.g.`ap-south-1`
    

    [Optional] Move Pulumi config to your ESC environment

    It was mentioned earlier in this guide that you can also set your AWS region as a Pulumi configuration value in your project’s stack settings file (Pulumi.<stack-name>.yaml). In addition to this, there may be other values that you have defined in this file, and these values can also be centralized using Pulumi ESC. To expose these values to Pulumi IaC, you will need to add a second-level key called pulumiConfig and nest any desired values underneath it as shown below:

    values:
      aws:
        login:
          fn::open::aws-login:
            oidc:
              duration: 1h
              roleArn: <your-oidc-iam-role-arn>
              sessionName: pulumi-environments-session
      environmentVariables:
        AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
        AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
        AWS_SESSION_TOKEN: ${aws.login.sessionToken}
        AWS_REGION: <YOUR_AWS_REGION>
      pulumiConfig: # exposes Pulumi config values to the Pulumi CLI
        project:environment: 'dev'
        aws:assumeRole:
          roleArn: 'arn:aws:iam::058111598222:role/OrganizationAccountAccessRole'
        aws:dynamodbEndpoint: 'dynamodb.us-east-2.amazonaws.com'
    

    If your workflow does not require the exposure of environment variables, you can also define those variables under the pulumiConfig block so that they are scoped only to your pulumi run.

    values:
      aws:
        login:
          fn::open::aws-login:
            oidc:
              duration: 1h
              roleArn: <your-oidc-iam-role-arn>
              sessionName: pulumi-environments-session
      pulumiConfig:
        aws:region: <YOUR_AWS_REGION>
        aws:accessKey: ${aws.login.accessKeyId}
        aws:secretKey: ${aws.login.secretAccessKey}
        aws:token: ${aws.login.sessionToken}
        project:environment: 'dev'
        aws:assumeRole:
          roleArn: 'arn:aws:iam::058111598222:role/OrganizationAccountAccessRole'
        aws:dynamodbEndpoint: 'dynamodb.us-east-2.amazonaws.com'
    
    The configuration values under pulumiConfig can also be referenced directly from within your Pulumi program code. This is done using the same method to reference values from your project’s stack settings file. You can see examples of how to do this in the Accessing Configuration from Code section of the Pulumi documentation.

    Import your environment

    The last step is to update your project’s stack settings file (Pulumi.<stack-name>.yaml) to import your ESC environment as shown below:

    environment:
      - <your-environment-name>
    

    Make sure to replace <your-environment-name> with the name of the ESC environment you created in the previous steps.

    You can test that your configuration is working by running the pulumi preview command. This will validate that your AWS resources can be deployed using the dynamically generated credentials in your environment file.

    Make sure that your local environment does not have AWS credentials configured before running this command. You can check by running something like the aws s3 ls command which should return the following:

    ‘Unable to locate credentials. You can configure credentials by running “aws configure”.’

    To learn more about projecting environment variables in Pulumi ESC, refer to the relevant Pulumi ESC documentation.

    Configuration options

    Use pulumi config set aws:<option> or pass options to the constructor of new aws.Provider.

    OptionRequired?Description
    regionRequiredThe region where AWS operations will take place. Examples are us-east-1, us-west-2, etc.
    allowedAccountIdsOptionalList 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.
    accessKeyOptionalThe access key for API operations. You can retrieve this from the ‘Security & Credentials’ section of the AWS console.
    assumeRoleOptionalA 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:
    durationSecondsOptionalNumber of seconds to restrict the assume role session duration.
    externalIdOptionalExternal identifier to use when assuming the role.
    policyOptionalIAM Policy JSON describing further restricting permissions for the IAM Role being assumed.
    policyArnsOptionalSet of Amazon Resource Names (ARNs) of IAM Policies describing further restricting permissions for the IAM Role being assumed.
    roleArnOptionalAmazon Resource Name (ARN) of the IAM Role to assume.
    sessionNameOptionalSession name to use when assuming the role.
    tagsOptionalMap of assume role session tags.
    transitiveTagKeysOptionalSet of assume role session tag keys to pass to any subsequent sessions.
    assumeRoleWithWebIdentityOptionalA JSON object representing an IAM role to assume using web identity/OIDC. 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:
    durationSecondsOptionalNumber of seconds to restrict the assume role session duration.
    policyOptionalIAM Policy JSON describing further restricting permissions for the IAM Role being assumed.
    policyArnsOptionalSet of Amazon Resource Names (ARNs) of IAM Policies describing further restricting permissions for the IAM Role being assumed.
    roleArnOptionalAmazon Resource Name (ARN) of the IAM Role to assume.
    sessionNameOptionalSession name to use when assuming the role.
    webIdentityTokenOptionalWeb Identity (OIDC ID) token value.
    webIdentityTokenFileOptionalFile containing the Web Identity (OIDC ID) token.
    dynamodbEndpointOptionalUse this to override the default endpoint URL constructed from the region. It’s typically used to connect to dynamodb-local.
    forbiddenAccountIdsOptionalList 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.
    defaultTagsOptionalA 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:
    tagsOptionalA key value pair of tags to apply across all resources.
    ignoreTagsOptionalA 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:
    keysOptionalA 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.
    keyPrefixesOptionalA 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.
    insecureOptionalExplicitly allow the provider to perform “insecure” SSL requests. If omitted, the default value is false.
    kinesisEndpointOptionalUse this to override the default endpoint URL constructed from the region. It’s typically used to connect to kinesalite.
    maxRetriesOptionalThe maximum number of times an AWS API request is being executed. If the API request still fails, an error is thrown.
    profileOptionalThe profile for API operations. If not set, the default profile created with aws configure will be used.
    retryModeOptionalSpecifies how retries are attempted. Valid values are standard and adaptive. Can also be configured using the AWS_RETRY_MODE environment variable.
    s3ForcePathStyleOptionalSet 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.
    secretKeyOptionalThe secret key for API operations. You can retrieve this from the ‘Security & Credentials’ section of the AWS console.
    sharedCredentialsFileOptionalThe path to the shared credentials file. If not set this defaults to ~/.aws/credentials.
    skipCredentialsValidationOptionalSkip the credentials validation via STS API. Used for AWS API implementations that do not have STS available/implemented.
    skipGetEc2PlatformsOptionalSkip getting the supported EC2 platforms. Used by users that don’t have ec2:DescribeAccountAttributes permissions.
    skipMetadataApiCheckOptionalSkip 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.
    skipRegionValidationOptionalSkip static validation of region name. Used by users of alternative AWS-like APIs or users w/ access to regions that are not public (yet).
    skipRequestingAccountIdOptionalSkip requesting the account ID. Used for AWS API implementations that do not have IAM/STS API and/or metadata API.
    tokenOptionalUse this to set an MFA token. It can also be sourced from the AWS_SESSION_TOKEN environment variable.
    aws logo
    AWS v6.55.0 published on Monday, Oct 7, 2024 by Pulumi