Pulumi Blog: Rds

Passwordless PostgreSQL: IAM Authentication with Pulumi

Elisabeth Lichtie — Fri, 13 Feb 2026 00:00:00 +0000

Managing database credentials is one of the persistent challenges in cloud infrastructure. Passwords need to be rotated, secrets need to be stored securely, and access needs to be carefully controlled. AWS IAM authentication for RDS offers a better way: instead of managing long-lived passwords, your applications authenticate using short-lived tokens generated from IAM credentials. This approach is more secure, eliminates password rotation overhead, and integrates seamlessly with your existing IAM policies. With Pulumi, you can set up this entire system using reusable components that make IAM authentication a standard part of your infrastructure.

Why IAM authentication for PostgreSQL?

Traditional database authentication relies on usernames and passwords. These credentials need to be stored somewhere secure, rotated regularly, and distributed to applications that need them. Each of these steps introduces complexity and potential security risks.

IAM authentication changes this model fundamentally. Instead of passwords, your applications generate authentication tokens on demand using their IAM credentials. These tokens are valid for only 15 minutes, eliminating the need for password rotation. Access control happens through IAM policies, which you’re already using to manage other AWS resources. The result is a more secure system that’s easier to maintain and audit.

The benefits become even more pronounced when you componentize this setup with Pulumi. Rather than repeating the same configuration steps for each database, you can build reusable components that handle IAM authentication setup automatically. This turns a complex, multi-step process into a simple, repeatable pattern that your entire team can use. In this post, we’ll cover an example that sets up the complete flow: an RDS cluster with IAM authentication, the necessary IAM roles and policies, and a Kubernetes application that connects using IAM tokens.

Architecture overview

This example sets up a complete environment with IAM-authenticated database access from a Kubernetes application. The architecture includes:

VPC with public and private subnets across multiple availability zones
EKS cluster for running containerized applications
Aurora PostgreSQL cluster with IAM authentication enabled
IAM roles and policies that connect Kubernetes service accounts to database access
A demo application that authenticates to the database using IAM tokens

The key integration point is IAM Roles for Service Accounts (IRSA), which allows Kubernetes pods to assume IAM roles. This means your application doesn’t need any AWS credentials stored in environment variables or mounted secrets. The pod’s service account automatically has the permissions it needs to generate database authentication tokens.

Setting up the RDS cluster with IAM authentication

The foundation of this setup is an RDS cluster configured to accept IAM authentication. With Pulumi’s componentized approach, you can encapsulate all the RDS configuration in a reusable component:

const rdsCluster = new RdsCluster("iam-postgres", {
 vpcId: vpc.vpc.id,
 vpcCidrBlock: vpc.vpc.cidrBlock,
 subnetIds: vpc.publicSubnets.map((s) => s.id),
 databaseName: DATABASE_NAME,
 masterUsername: MASTER_USERNAME,
 masterPassword: dbMasterPassword,
 instanceClass: "db.t4g.medium",
 engineVersion: "17.4",
 iamDatabaseUser: IAM_DB_USERNAME,
});

Inside the component, the critical configuration is iamDatabaseAuthenticationEnabled:

this.cluster = new aws.rds.Cluster(
 `${name}-cluster`,
 {
 engine: "aurora-postgresql",
 engineVersion: engineVersion,
 databaseName: args.databaseName,
 masterUsername: args.masterUsername,
 masterPassword: args.masterPassword,
 dbSubnetGroupName: subnetGroup.name,
 vpcSecurityGroupIds: [this.securityGroup.id],
 iamDatabaseAuthenticationEnabled: true,
 skipFinalSnapshot: true,
 tags: { Name: `${name}-cluster` },
 },
 { parent: this }
);

This single flag tells RDS to accept authentication tokens in addition to traditional passwords. The cluster still needs a master password for initial setup and administrative tasks, but your applications can use IAM authentication instead.

Creating the database user with IAM permissions

Enabling IAM authentication on the cluster isn’t enough. You also need to create a database user and grant it the special rds_iam role that allows IAM authentication. This is where Pulumi’s PostgreSQL provider comes in:

const dbSetup = new DbSetup(
 "iam-postgres",
 {
 dbEndpoint: rdsCluster.cluster.endpoint,
 dbName: DATABASE_NAME,
 masterUsername: MASTER_USERNAME,
 masterPassword: dbMasterPassword,
 iamUsername: IAM_DB_USERNAME,
 },
 { dependsOn: [rdsCluster.instance] }
);

The DbSetup component handles all the database-level configuration. It creates the IAM user and grants the necessary permissions:

// Create IAM-enabled database user
this.iamRole = new postgresql.Role(
 `${name}-iam-user`,
 {
 name: args.iamUsername,
 login: true,
 },
 { parent: this, provider: this.provider }
);

// Grant rds_iam role to enable IAM authentication
new postgresql.GrantRole(
 `${name}-grant-rds-iam`,
 {
 role: this.iamRole.name,
 grantRole: "rds_iam",
 },
 { parent: this, provider: this.provider }
);

The component also grants the necessary database privileges (CONNECT, USAGE, CREATE, and table operations). By encapsulating this in a component, you ensure that every IAM-authenticated database user is set up consistently with the correct permissions.

Configuring IAM policies for database access

The next piece is the IAM role and policy that allows applications to generate authentication tokens. This involves two parts: the role that the application assumes, and the policy that grants database access.

For Kubernetes applications, this uses IRSA (IAM Roles for Service Accounts). The RdsCluster component includes a method that creates the appropriate IAM role:

const rdsIamRole = rdsCluster.createIamRole(
 eksCluster.oidcProvider,
 NAMESPACE,
 SERVICE_ACCOUNT_NAME
);

This creates an IAM role with a trust policy that allows the specified Kubernetes service account to assume it:

assumeRolePolicy: pulumi
 .all([oidcProvider.arn, oidcProvider.url])
 .apply(([arn, url]) =>
 JSON.stringify({
 Version: "2012-10-17",
 Statement: [
 {
 Effect: "Allow",
 Principal: { Federated: arn },
 Action: "sts:AssumeRoleWithWebIdentity",
 Condition: {
 StringEquals: {
 [`${url}:sub`]: `system:serviceaccount:${namespace}:${serviceAccountName}`,
 },
 },
 },
 ],
 })
 ),

The role is then granted the rds-db:connect permission for the specific database user:

{
 Version: "2012-10-17",
 Statement: [
 {
 Effect: "Allow",
 Action: ["rds-db:connect"],
 Resource: `arn:aws:rds-db:${region}:${accountId}:dbuser:${resourceId}/${iamDatabaseUser}`,
 },
 ],
}

This policy is scoped to exactly one database user on one cluster. This level of granularity is one of the security advantages of IAM authentication: you can control database access with the same precision you use for other AWS resources.

Connecting from Kubernetes with IRSA

The application running in Kubernetes needs a service account annotated with the IAM role ARN:

this.serviceAccount = new k8s.core.v1.ServiceAccount(
 `${name}-sa`,
 {
 metadata: {
 name: args.serviceAccountName,
 namespace: args.namespace,
 annotations: {
 "eks.amazonaws.com/role-arn": args.iamRoleArn,
 },
 },
 },
 { parent: this, provider: args.provider }
);

When a pod uses this service account, EKS automatically configures the pod with temporary AWS credentials for the associated IAM role. The application can then use these credentials to generate database authentication tokens.

How IAM authentication works at runtime

The authentication flow happens at connection time:

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FF9900','primaryTextColor':'#232F3E','primaryBorderColor':'#232F3E','lineColor':'#666','secondaryColor':'#527FFF','tertiaryColor':'#fff'}}}%%
sequenceDiagram
autonumber
participant App as Application Pod
participant SDK as AWS SDK
participant STS as AWS STS
participant IAM as AWS IAM
participant RDS as RDS Aurora
rect rgb(255, 249, 230)
Note over App,SDK: Phase 1: Token Generation
activate App
App->>+SDK: generate_db_auth_token()
SDK->>+STS: Get temporary credentials (IRSA)
STS-->>-SDK: Return AWS credentials
SDK->>SDK: Sign auth request
SDK-->>-App: Return IAM token (15 min TTL)
deactivate App
end
rect rgb(235, 245, 255)
Note over App,RDS: Phase 2: Database Connection
activate App
App->>+RDS: Connect (user + IAM token)
activate RDS
RDS->>+IAM: Validate token & permissions
IAM-->>-RDS: Token valid + rds-db:connect allowed
RDS->>RDS: Verify rds_iam role
RDS-->>-App: Connection established
deactivate App
end
Note over App,RDS: 💡 Token expires after 15 minutes - generate new token per connection

The application uses the AWS SDK to call generate_db_auth_token(), passing the database endpoint, port, and username
The SDK uses the pod’s IAM credentials (provided automatically by IRSA) to sign the request and generate a token
The application connects to PostgreSQL using the IAM username and the token as the password
RDS validates the token against IAM, verifying that the caller has rds-db:connect permission for that database user
If the token is valid, the connection is established

Here’s what this looks like in Python:

def get_iam_token():
 """Generate an IAM authentication token for RDS"""
 client = boto3.client('rds', region_name=AWS_REGION)
 token = client.generate_db_auth_token(
 DBHostname=DB_ENDPOINT,
 Port=DB_PORT,
 DBUsername=DB_USER,
 Region=AWS_REGION
 )
 return token

def get_db_connection():
 """Create a database connection with IAM auth"""
 token = get_iam_token()
 return psycopg2.connect(
 host=DB_ENDPOINT,
 port=DB_PORT,
 database=DB_NAME,
 user=DB_USER,
 password=token,
 sslmode='require',
 sslrootcert=RDS_CA_CERT
 )

The token is valid for 15 minutes. Applications should generate a new token for each connection or implement token caching with refresh logic.

Testing the setup with the demo application

The example includes an interactive demo application that lets you test the IAM authentication setup. Once deployed, the application provides a web interface for creating tables, adding messages, and querying the database:

Deploy the infrastructure and access the demo app:

pulumi up
export APP_URL=$(pulumi stack output appUrl)
echo "Demo app: http://$APP_URL"

The application shows the database endpoint and IAM username it’s using, and provides buttons to create tables and add data. Behind the scenes, every database operation authenticates using IAM tokens, demonstrating that the entire authentication flow is working correctly.

The full code for this example is available at https://github.com/pulumi-demos/examples/tree/main/typescript/aws-iam-for-postgres. The example includes all the component code referenced in this post.

Make passwordless access your default

Wrap this IAM authentication setup in a Pulumi component and apply the same passwordless pattern to every RDS cluster your team runs.

Get started

Production considerations

This example demonstrates IAM authentication in a working environment, but you’ll want to make several adjustments for production use:

Network security: The example places RDS in public subnets to allow the PostgreSQL provider to connect during deployment. In production, place RDS in private subnets and ensure your deployment environment (like GitHub Actions or Pulumi Cloud) can reach the database for initial setup, either through a bastion host or VPN.

Connection pooling and performance: IAM tokens expire after 15 minutes. If you’re using connection pooling, you’ll need logic to refresh tokens before they expire. AWS recommends using IAM authentication only when your application creates fewer than 200 new connections per second. For higher connection rates, consider using Amazon RDS Proxy, which manages connection pooling and can reduce the overhead of IAM token generation.

Master password management: You still need a master password for database administration and for the initial user setup. Store this in AWS Secrets Manager or Pulumi ESC, and restrict access to it carefully.

Monitoring and auditing: Token generation via the AWS SDK is logged in CloudTrail. Note that CloudWatch and CloudTrail do not log database authentication attempts themselves, so you’ll need to rely on PostgreSQL’s native logging for connection monitoring.

Multi-region considerations: If your application runs in multiple regions, ensure that IAM policies and database access work correctly across regions. Token generation and validation must happen in the same region as the RDS cluster.

Cost: IAM authentication itself is free, but be aware that cross-AZ data transfer costs still apply for database connections.

Conclusion

IAM authentication for PostgreSQL transforms database credential management from a security burden into a seamless part of your infrastructure. By eliminating long-lived passwords, you reduce your attack surface and remove the operational overhead of password rotation. By integrating with IAM, you gain fine-grained access control and comprehensive audit logs.

Pulumi makes this setup practical and repeatable through componentization. The components in this example encapsulate the complexity of IAM authentication setup, making it easy to apply the same pattern across multiple databases and applications. This turns security best practices into your team’s default approach.

Whether you’re building a new application or improving the security posture of existing infrastructure, IAM authentication for RDS deserves consideration. The investment in setup pays dividends in security, maintainability, and operational simplicity.

AWS RDS - Blue/Green Deployments for Low-Downtime Updates

Elisabeth Lichtie — Mon, 23 Jun 2025 00:00:00 +0000

AWS RDS supports blue/green deployments to support database maintenance. In a blue/green deployment, you have one production (blue) and one staging (green) database. You can safely make changes to the green instance without affecting production and promote it to be the main instance. When you enable blue/green updates, Pulumi will temporarily set up a blue/green deployment for the duration of the update to minimize downtime.

There are many benefits to using blue/green deployments for updates, especially for critical databases that need to be kept available and safe from untested changes.

How it works

By default, updates to a database will be applied in-place, meaning there may be service interruptions while a database is modified especially when making long-running updates like changing the engine version, parameter groups, or storage settings.

blueGreenUpdate can be enabled for Low-Downtime Updates. When this setting is on and an update is performed, the program starts the update by creating a blue/green deployment to maintain availability. Then, it performs the requested update on the green instance, performs a guardrail check, promotes the green instance, and finally deletes the old instance and removes the blue/green deployment. This leaves just the updated database running with minimal downtime during the update while minimizing the downtime.

Though this strategy typically increases the amount of time that updates need to run, it minimizes downtime for the application by keeping a current version of the database available during the update process.

How to use

Please see the full example code here: Blue/Green Deployment Updates on RDS. To use blue/green deployments for your database updates, start by creating a database and corresponding parameter group.

const dbVersion = "14.18";

const parameterGroup = new aws.rds.ParameterGroup(
 "parameter-group",
 {
 family: `postgres${dbVersion.split(".")[0]}`,
 parameters: [
 {
 name: "rds.logical_replication",
 value: "1",
 applyMethod: "pending-reboot",
 },
 ],
 },
 { deleteBeforeReplace: false } // This explicitly calls out that the new group should be created before the old is deleted so that database availability can be maintained
);

const database = new aws.rds.Instance(
 "rds-instance",
 {
 allocatedStorage: storageAllocation,
 engine: "postgres",
 engineVersion: dbVersion,
 instanceClass: aws.rds.InstanceType.T3_Micro,
 username: dbUsername,
 password: dbPW,
 storageEncrypted: true,
 backupRetentionPeriod: 7,
 blueGreenUpdate: { enabled: true },
 skipFinalSnapshot: true,
 parameterGroupName: parameterGroup.name,
 },
 { dependsOn: [parameterGroup] } //This line can be omitted since the dependency is also inferred by the reference to parameterGroup.name
);

After running pulumi up with the above code, you’ll have a database deployed and attached to your custom parameter group. It’s important to create and attach a custom parameter group so that you can keep it up to date with any engine version upgrades. If you use the default parameter group, updates to the database version may fail when the green deployment is created since its parameter group family won’t match the new version. You can avoid a failure by ensuring that the parameter group’s family and engineVersion are always changed in the same update.

You won’t see the effects of having blueGreenUpdate enabled until you run your first update. Change any part of the database configuration and run pulumi up again to start the update. In the example above, you can change dbVersion to 15.13 to trigger an update to both the parameter group and the instance.

Once the update kicks off, you can watch on AWS as the blue/green deployment is created and the original settings are copied to the green instance.

Then, the green instance will be updated with the new settings and the program will switch over to the green instance and clean up.

After that, your update has been completed with minimal disruption!

Additional Considerations

General limitations and considerations for Amazon RDS blue/green deployments are listed in the AWS documentation, but there are a few other considerations that should be taken into account when using them for updates with infrastructure as code (IaC).

No Custom Checks: Because IaC will automatically perform the switchover when the update is complete, you will not have the opportunity to perform custom checks on the green instance before promoting it. RDS will run some basic guardrails checks before performing the switchover, but you will not be able to perform any additional checks.
No Cluster Support: This feature only works with database instances, not with clusters or instances that are in a cluster.
Long Update Times: Because the IaC program will deploy temporary resources before performing the update and destroy them after, blue/green updates will take considerably longer than their in-place counterparts.
Manual Cleanup: Because the green instance and blue/green deployment are temporary resources designed to decrease downtime during the update, they are not tracked in the IaC state. If the update fails partway through, these temporary resources may have to be cleaned up manually. If the update is interrupted, you can delete the blue/green deployment and green database to get back into a manageable state.
Resource ID Change: On an update, the resource ID of the database might change since a new instance has been created. The endpoint and other details about the database will be maintained by AWS during switchover, but the resource ID should be dynamically retrieved from the stack outputs whenever it is used to ensure it stays up to date. Usually, no application or connection details will need to be updated since they don’t rely on the resource ID itself.
Types Of Updates: The blue/green update strategy will be used for changes that require a maintenance window including updates to the engine version, parameter group, storage and performance settings, and optimized writes.

Deploy Infrastructure to Multiple Cloud Regions at Once

Joe Duffy — Wed, 03 Aug 2022 08:00:00 -0700

Pulumi makes it easy to flexibly deploy your cloud infrastructure using code. Usually deployments encompass a single slack and a single region in your cloud of choice. If you need to go multi-region, that usually means creating a stack per-region, which Pulumi’s configuration system makes easy. A stack per region isn’t required, though! Sometimes we want a single stack to span regions for performance, scalability, resilience, or just hard requirements. In these cases, Pulumi can seamlessly orchestrate deployments to, or even across, multiple regions, accounts, or clusters. In this article, we’ll see this in action by provisioning an AWS RDS primary database into one region and a read replica in an entirely different region – all from a single Pulumi program, stack, and pulumi up incantation.

Recap of Stack Configuration

Before seeing how to span regions, let’s review how you’d typically configure your region. Every Pulumi project can have any number of stacks. These stacks are often things like dev, test, prod – and sometimes, things like prod-us-east, prod-us-west, prod-euro, and so on, to represent instances of our infrastructure running in different regions. Each stack is isolated from all others and it’s easy to switch between them.

The standard way to vary regions between stacks is to use Pulumi’s configuration system. If you’ve used Pulumi to deploy to AWS, for instance, you’ve probably uttered a CLI command like this:

$ pulumi config set aws:region us-east-1

This isn’t just about regions: it applies to anything that varies between stacks. It might include accounts, secrets like tokens and passwords, sizes or counts of instances, among many other things.

This is normally very convenient and aligns with how we want to configure our projects and stacks. But there are some relatively common circumstances in which it breaks down:

Managing a large number of multi-tenanted resources spanning multiple accounts or clusters.
Cases where a few pieces of infrastructure must run somewhere different than most of it, as is often the case with DNS or SSL/TLS certificate management services.
Situations where we want to provision resources in many places for performance, scalability, or resilience purposes.
Highly programmatic scenarios where some configuration might be fetched dynamically from an external resource.

In all of these cases, thankfully Pulumi has an answer: explicit provider configuration.

How Explicit Provider Configuration Works

Before diving into our example, let’s take a quick look at how explicit provider configuration works. Unlike ordinary configuration, which is set at the CLI, provider configuration is set programmatically inside your Pulumi program. Every Pulumi package exports a Provider resource class which can be instantiated like any other resource, with the sole difference that these resources exist to pass around to configure other resources, and don’t represent infrastructure that is to be provisioned in a cloud of any kind.

For instance, if we wanted to programmatically create an AWS provider that targets a different region than us-east-1, as shown earlier, we can do so as follows:

const awsWest2 = new aws.Provider("aws-west-2", { region: "us-west-2" });

aws_west_2 = aws.Provider('aws-west-2', region='us-west-2')

awsWest2, err := aws.NewProvider(ctx, "aws-west-2", &aws.ProviderArgs{
 Region: pulumi.String("aws-west-2")
})
if err != nil {
 return err
}

var awsWest2 = new Aws.Provider("aws-west-2", new Aws.ProviderArgs
{
 Region = "us-west-2"
});

resources:
 awsWest2:
 type: pulumi:providers:aw
 properties:
 region: us-west-2

This configuration is not used automatically, however. You must pass it to any resources you’d like to use it:

const buck = new aws.s3.Bucket("my-bucket", {
 // ...
}, { provider: awsWest2 });

buck = aws.s3.Bucket('my-bucket',
 # ...
 opts=pulumi.ResourceOptions(provider=aws_west_2)
)

buck, err := s3.NewBucket("my-bucket",
 &s3.BucketArgs{
 // ...
 },
 pulumi.Provider(awsWest2)
)
if err != nil {
 return err
}

var buck = new Aws.S3.Bucket("my-bucket",
 new Aws.S3.BucketArgs
 {
 // ...
 },
 new ResourceArgs
 {
 Provider = awsWest2
 }
);

resources:
 # ...
 buck:
 type: aws:s3:Bucket
 properties:
 # ...
 options:
 provider: ${awsWest2}

This overrides the default of using whatever was set at the CLI, and will instead use the programmatically configured settings. Note also that anything you can set at the CLI is available, not just the region. You can see the full settings available in the package’s registry documentation for its Provider class (for instance, the AWS Provider.

Multi-Region Deployment In Action!

The architecture for our multi-region setup is going to be relatively straightforward so we can focus on the essentials. We will provision a single RDS primary database in one region (us-east-1) and backup to a read replica in an entirely different region – in fact, on an entirely different continent (eu-west-2)! This is relatively straightforward because many scenarios demand that we deploy to a dynamic number of regions, perhaps across dozens or hundreds of resources. By keeping it to just two resources across two regions, we can see the fundamentals in action which can scale easily to more sophisticated use cases.

This is described in AWS’s docs and is depicted in this diagram:

Now let’s dive into some infrastructure as code. There’s a bit of preamble before getting to the meat of the example:

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as random from "@pulumi/random";

// Code from below will goes here.

import pulumi
import pulumi_aws as aws
import pulumi_random as random

# Code from below goes here.

package main

import (
 "github.com/pulumi/pulumi-aws/sdk/v5/go/aws"
 "github.com/pulumi/pulumi-aws/sdk/v5/go/aws/rds"
 "github.com/pulumi/pulumi-random/sdk/v4/go/random"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi/config"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // Code from below goes here.
 })
}

using System.Collections.Generic;
using Pulumi;
using Aws = Pulumi.Aws;
using Random = Pulumi.Random;

return await Deployment.RunAsync(() =>
{
 // Code from below goes here.
});

name: aws-multireg-rds
runtime: yaml
description: A multi-region example creating an RDS primary and read-replica in different regions

# Code from below goes here.

Next, we’ll make the retention period configurable, by default it is 30 days. Note how we can still use standard configuration features as well as explicit providers alongside one another:

// Enable backup retention to be configured, but default to 30 days.
const config = new pulumi.Config();
const retentionPeriod = config.getNumber("retentionPeriod") || 30;

# Enable backup retention to be configured, but default to 30 days.
config = pulumi.Config()
retention_period = config.get_float('retentionPeriod') or 30

// Enable backup retention to be configured, but default to 30 days.
cfg := config.New(ctx, "")
retentionPeriod := 30
if param := cfg.GetFloat("retentionPeriod"); param != 0 {
 retentionPeriod = param
}

// Enable backup retention to be configured, but default to 30 days.
var config = new Config();
var retentionPeriod = config.GetNumber("retentionPeriod") ?? 30;

# Enable backup retention to be configured, but default to 30 days.
configuration:
 retentionPeriod:
 type: Number
 default: 30

Next, we’ll create a random password for our database so we don’t need to hard-code one:

// Create a random password for the database's admin user.
const dbPassword = new random.RandomPassword("dbPassword", { length: 12 });

# Create a random password for the database's admin user.
db_password = random.RandomPassword('dbPassword', length = 12)

// Create a random password for the database's admin user.
dbPassword, err := random.NewRandomPassword(ctx, "dbPassword", &random.RandomPasswordArgs{
 Length: pulumi.Int(12),
})

// Create a random password for the database's admin user.
var dbPassword = new Random.RandomPassword("dbPassword", new()
{
 Length = 12,
});

 # Create a random password for the database's admin user.
 dbPassword:
 type: random:RandomPassword
 properties:
 length: 12

Now we’re ready to create the providers. We’ll create one per region that we will deploy into:

// Create two AWS providers, one for each region we'll deploy into.
const euProvider = new aws.Provider("euProvider", { region: "eu-west-2" });
const usProvider = new aws.Provider("usProvider", { region: "us-east-1" });

# Create two AWS providers, one for each region we'll deploy into.
eu_provider = aws.Provider('euProvider', region = 'eu-west-2')
us_provider = aws.Provider('usProvider', region = 'us-east-1')

// Create two AWS providers, one for each region we'll deploy into.
euProvider, err := aws.NewProvider(ctx, "euProvider", &aws.ProviderArgs{
 Region: pulumi.String("eu-west-2"),
})
if err != nil {
 return err
}
usProvider, err := aws.NewProvider(ctx, "usProvider", &aws.ProviderArgs{
 Region: pulumi.String("us-east-1"),
})
if err != nil {
 return err
}

// Create two AWS providers, one for each region we'll deploy into.
var euProvider = new Aws.Provider("euProvider", new()
{
 Region = "eu-west-2",
});

var usProvider = new Aws.Provider("usProvider", new()
{
 Region = "us-east-1",
});

resources:
 # Create two AWS providers, one for each region we'll deploy into.
 euProvider:
 type: pulumi:providers:aws
 properties:
 region: eu-west-2
 usProvider:
 type: pulumi:providers:aws
 properties:
 region: us-east-1

To keep things straightforward, we’ve hard-coded the regions into the program. There are more sophisticated possibilities, however. For example, we could have made the regions themselves configurable too, much like the retention period. Even more powerfully, we could use our programming language’s expressiveness to create them dynamically. For instance, we could have looped over a list of them so that the number of regions isn’t even known in advance. These advanced capabilities are helpful for many real-world scenarios.

Next up, we’ll create the primary database instance in us-east-1:

// Create the primary RDS database instance.
const primaryDb = new aws.rds.Instance("primary", {
 allocatedStorage: 10,
 engine: "mysql",
 engineVersion: "5.7",
 instanceClass: "db.t3.micro",
 username: "admin",
 password: dbPassword.result,
 backupRetentionPeriod: retentionPeriod,
 skipFinalSnapshot: true,
}, {
 provider: usProvider,
});

# Create the primary RDS database instance.
primary_db = aws.rds.Instance('primary',
 allocated_storage=10,
 engine='mysql',
 engine_version='5.7',
 instance_class='db.t3.micro',
 username='admin',
 password=db_password.result,
 backup_retention_period=retention_period,
 skip_final_snapshot=True,
 opts=pulumi.ResourceOptions(provider=us_provider)
)

// Create the primary RDS database instance.
primaryDb, err := rds.NewInstance(ctx, "primary", &rds.InstanceArgs{
 AllocatedStorage: pulumi.Int(10),
 Engine: pulumi.String("mysql"),
 EngineVersion: pulumi.String("5.7"),
 InstanceClass: pulumi.String("db.t3.micro"),
 Username: pulumi.String("admin"),
 Password: dbPassword.Result,
 BackupRetentionPeriod: pulumi.Float64(retentionPeriod),
 SkipFinalSnapshot: pulumi.Bool(true),
}, pulumi.Provider(usProvider))
if err != nil {
 return err
}

// Create the primary RDS database instance.
var primaryDb = new Aws.Rds.Instance("primary", new()
{
 AllocatedStorage = 10,
 Engine = "mysql",
 EngineVersion = "5.7",
 InstanceClass = "db.t3.micro",
 Username = "admin",
 Password = dbPassword.Result,
 BackupRetentionPeriod = retentionPeriod,
 SkipFinalSnapshot = true,
}, new CustomResourceOptions
{
 Provider = usProvider,
});

 # Create the primary RDS database instance.
 primary:
 type: aws:rds:Instance
 properties:
 allocatedStorage: 10
 engine: mysql
 engineVersion: "5.7"
 instanceClass: db.t3.micro
 username: admin
 password: ${dbPassword.result}
 backupRetentionPeriod: ${retentionPeriod}
 skipFinalSnapshot: true
 options:
 provider: ${usProvider}

The key here is that we explicitly passed the provider that was configured to use us-east-1, instructing Pulumi to use that configuration rather than the implicit default configuration set at the CLI as usual.

Now we will create the secondary database instance in eu-west-2:

// Now set up our secondary read replica database in an entirely different region.
const secondaryDb = new aws.rds.Instance("secondary", {
 instanceClass: "db.t3.micro",
 replicateSourceDb: primaryDb.arn,
 backupRetentionPeriod: retentionPeriod,
 skipFinalSnapshot: true,
}, {
 provider: euProvider,
});

# Now set up our secondary read replica database in an entirely different region.
secondary_db = aws.rds.Instance("secondary",
 instance_class="db.t3.micro",
 replicate_source_db=primary_db.arn,
 backup_retention_period=retention_period,
 skip_final_snapshot=True,
 opts=pulumi.ResourceOptions(provider=eu_provider)
)

// Now set up our secondary read replica database in an entirely different region.
secondaryDb, err := rds.NewInstance(ctx, "secondary", &rds.InstanceArgs{
 InstanceClass: pulumi.String("db.t3.micro"),
 ReplicateSourceDb: primaryDb.Arn,
 BackupRetentionPeriod: pulumi.Float64(retentionPeriod),
 SkipFinalSnapshot: pulumi.Bool(true),
}, pulumi.Provider(euProvider))
if err != nil {
 return err
}

// Now set up our secondary read replica database in an entirely different region.
var secondaryDb = new Aws.Rds.Instance("secondary", new()
{
 InstanceClass = "db.t3.micro",
 ReplicateSourceDb = primaryDb.Arn,
 BackupRetentionPeriod = retentionPeriod,
 SkipFinalSnapshot = true,
}, new CustomResourceOptions
{
 Provider = euProvider,
});

 # Now set up our secondary read replica database in an entirely different region.
 secondary:
 type: aws:rds:Instance
 properties:
 instanceClass: db.t3.micro
 replicateSourceDb: ${primary.arn}
 backupRetentionPeriod: ${retentionPeriod}
 skipFinalSnapshot: true
 options:
 provider: ${euProvider}

As expected, we passed the provider configured to use eu-west-2. Notice also that, although these resources are deployed into entirely different regions, they can reference one another! Thanks to Pulumi’s dependency system, it understands that referencing primary.arn means the secondary database depends on the primary, which Pulumi will use to ensure correct ordering of operations.

Finally, we’ll emit the primary and secondary database endpoints plus auto-generated password:

// Output the primary and secondary database ARNs, and the auto-generated admin password.
export const primary = primaryDb.endpoint;
export const secondary = secondaryDb.endpoint;
export const password = dbPassword.result;

# Output the primary and secondary database ARNs, and the auto-generated admin password.
pulumi.export('primary', primary_db.endpoint)
pulumi.export('secondary', secondary_db.endpoint)
pulumi.export('password', db_password.result)

// Output the primary and secondary database ARNs, and the auto-generated admin password.
ctx.Export("primary", primaryDb.Endpoint)
ctx.Export("secondary", secondaryDb.Endpoint)
ctx.Export("password", dbPassword.Result)
return nil

// Output the primary and secondary database ARNs, and the auto-generated admin password.
return new Dictionary<string, object?>
{
 ["primary"] = primaryDb.Endpoint,
 ["secondary"] = secondaryDb.Endpoint,
 ["password"] = dbPassword.Result,
};

# Output the primary and secondary database ARNs, and the auto-generated admin password.
outputs:
 primary: ${primary.endpoint}
 secondary: ${secondary.endpoint}
 password: ${dbPassword.result}

Using these, we can easily access our new instance. Don’t worry, the password is automatically encrypted!

For good measure, since all of our AWS resources are meant to use the explicit providers, and not the ambient default configuration, we can disable default providers altogether:

$ pulumi config set --path pulumi:disable-default-providers[0] "aws"

If we forget to pass an explicit provider, we now get an error:

error: Default provider for 'aws' disabled. 'urn:pulumi:dev::aws-multireg-rds::aws:rds/instance:Instance::primary' must use an explicit provider.

Now that we’ve got everything set up, we run pulumi up which orchestrates everything end-to-end:

$ pulumi up
Updating (dev)

 Type Name Status
 + pulumi:pulumi:Stack aws-multireg-rds-dev created
 + ├─ pulumi:providers:aws euProvider created
 + ├─ pulumi:providers:aws usProvider created
 + ├─ random:index:RandomPassword dbPassword created
 + ├─ aws:rds:Instance primary created
 + └─ aws:rds:Instance secondary created

Outputs:
 password : [secret]
 primary : "primarybe35b53.c0q7bvujknic.us-east-1.rds.amazonaws.com:3306"
 secondary: "secondaryacb6a3d.c8qninoaapw8.eu-west-2.rds.amazonaws.com:3306"

Resources:
 + 6 created

Duration: 27m0s

Deploy across regions from one stack

Configure explicit providers in your Pulumi program to provision resources across regions, accounts, and clusters from a single stack. Build and ship your multi-region infrastructure with one pulumi up.

Learn more

Winding Down

In this article, you saw some reasons why deploying your infrastructure across multiple regions, accounts, or clusters may be necessary. You saw that Pulumi supports two forms of configuration – implicit configuration set at the CLI with pulumi config as well as explicit provider configuration which is constructed and passed programmatically – and how and when to use them, often in tandem with one another.

The specific example shown to demonstrate multi-region in action deployed an AWS RDS primary database to a US region and a secondary read replica to Europe, which is a common architecture to improve resilience and performance. The power of full programming languages gives you a ton of flexibility in how you orchestrate such complex architectures.

Hopefully this post put a new tool in your infrastructure as code toolbelt! Happy cloud spelunking.