Skip to content
Ion
Docs Console Examples

Providers

Providers are the services that you can use in your app.

A provider is the infrastructure service that you can use in your app. It’s listed in your sst.config.ts under providers.

sst.config.ts
{
  providers: {
    aws: true
  }
}

Install

To add a provider to your app run.

Terminal window
sst add <provider>

This command adds the provider to your config, installs the packages, and adds the namespace of the provider to your globals.

You can add multiple providers to your app.

{
  providers: {
    aws: true,
    cloudflare: true
  }
}

The name of a provider comes from the URL of the provider in the Pulumi Registry. For example, https://www.pulumi.com/registry/packages/aws/ is the URL of the AWS Classic provider. So the name of the provider here is aws.

Learn more about the sst add command.

Configure

You can configure a provider in your sst.config.ts. For example, to change the region for AWS.

{
  providers: {
    aws: {
      region: "us-west-2"
    }
  }
}

You can check out the available list of options that you can configure for a provider over on the Pulumi docs. For example, here are the ones for AWS and Cloudflare.

Versions

In addition to these options, you can also pass in the version of the provider you want to use. By default, SST uses the latest version.

{
  providers: {
    aws: {
      version: "6.27.0"
    }
  }
}

Credentials

Most providers will read your credentials from the environment. For example, for Cloudflare you might set your token like so.

Terminal window
export CLOUDFLARE_API_TOKEN=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa

However, some providers also allow you to pass in the credentials through the config.

{
  providers: {
    cloudflare: {
      apiToken: "aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa"
    }
  }
}

Learn more about configuring providers.

Components

There are two types of components in your app.

  1. Native SST components, namespaced under sst.*
  2. And Pulumi components, namespaced under <provider>.*

The sst add command injects the provider into the globals of your config.

For example, running sst add aws will allow you to use all the components under the aws namepsace.

new aws.s3.BucketV2("b", {
  bucket: "mybucket",
  tags: {
    Name: "My bucket"
  }
});

Here we are using the BucketV2 component from the AWS Classic provider.

Functions

Aside from the components, there are a collection of functions that are exposed by a provider. These are listed in the Pulumi docs as getXXXXXX on the sidebar.

For example, to get the AWS account being used in your app.

const current = await aws.getCallerIdentity({});


const accountId = current.accountId;
const callerArn = current.arn;
const callerUser = current.userId;

Or to get the current region.

const current = await aws.getRegion({});


const region = current.name;

Output versions

The above are async methods that return promises. That means that if you call these in your app, they’ll block the deployment of any resources that are defined after it.

So we instead recommend using the Output version of these functions. For example, if we wanted to set the above as environment variables in a function, we would do something like this

new sst.aws.Function("MyFunction, {
  handler: "src/lambda.handler",
  environment: {
    ACCOUNT: aws.getCallerIdentityOutput({}).accountId,
    REGION: aws.getRegionOutput().name
  }
}

The aws.getXXXXOutput functions typically return an object of type Output<primitive>. Learn more about Outputs.

Home

The state of the deployed resources and your secrets are uploaded to a bucket in your provider. We call this the home of your app.

{
  home: "aws"
}

You can specify which provider you’d like to use for this. Currently aws and cloudflare are supported.

When you specify your home provider, SST assumes you’d like to use that provider in your app as well and adds it to your providers internally. So the above is equivalent to doing this.

{
  home: "aws",
  providers: {
    aws: true
  }
}

You can read more about the home provider in Config.

Multiple providers

Aside from the providers that are listed in the providers in your config, you can create your own providers. This is useful for multi-region or multi-account deployments.

const useast1 = new aws.Provider("AnotherAWS");

Multi-region

You might want to create multiple providers in cases where some resources in your app need to go to one region, while others need to go to a separate region.

Let’s look at an example. Assume your app is normally deployed to us-west-1. But you need to create an ACM certificate that needs to be deployed to us-east-1.

const useast1 = new aws.Provider("useast1", { region: "us-east-1" });


new sst.aws.Function("MyFunction, "src/lambda.handler");


new aws.acm.Certificate("cert", {
  domainName: "foo.com",
  validationMethod: "EMAIL",
}, { provider: useast1 });

Here the function is created in your default region, us-west-1. While the certificate is created in us-east-1.