AWS Cloud Control: Installation & Configuration

Installation

The AWS Cloud Control provider is available as a package in all Pulumi languages:

• JavaScript/TypeScript: @pulumi/aws-native
• Python: pulumi-aws-native
• Go: github.com/pulumi/pulumi-aws-native/sdk/go/aws
• .NET: Pulumi.AwsNative
• Java: com.pulumi.awsnative

Credentials

To provision resources with the Pulumi AWS Cloud Control provider, you need to have AWS credentials. To do so:

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.

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_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
$ export AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>

> $env:AWS_ACCESS_KEY_ID = "<YOUR_ACCESS_KEY_ID>"
> $env:AWS_SECRET_ACCESS_KEY = "<YOUR_SECRET_ACCESS_KEY>"

You may alternatively set the AWS region in your Pulumi.<stack-name>.yaml file:

$ pulumi config set aws-native: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-native:profile in your Pulumi.yaml

  pulumi config set aws-native:profile <profilename>
  

Dynamically generate credentials

In addition to configuring the AWS Cloud Control 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-native:roleArn: 'arn:aws:iam::058111598222:role/OrganizationAccountAccessRole'

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-native:region: <YOUR_AWS_REGION>
    aws-native:accessKey: ${aws.login.accessKeyId}
    aws-native:secretKey: ${aws.login.secretAccessKey}
    aws-native:token: ${aws.login.sessionToken}
    project:environment: 'dev'
    aws-native:roleArn: 'arn:aws:iam::058111598222:role/OrganizationAccountAccessRole'

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.

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

Configuration options

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