Skip to content
SST
Blog Docs Examples
22K
Console

Reference Resources

Reference externally created resources in your app.

Referencing is the process of using some externally created resources in your SST app; without having SST manage them.

This is for when you have some resources that are either managed by a different team or a different IaC tool. Typically these are low-level resources and not SST’s built-in components.

There are a few different ways this shows up in SST.

Lookup a resource

Let’s say you have an existing resource that you want to use in your SST app.

You can look it up by passing in a property of the resource. For example, to look up a previously created S3 Bucket with the following name.

mybucket-xnbmhcvd

We can use the static aws.s3.BucketV2.get method.

sst.config.ts
const bucket = aws.s3.BucketV2.get("MyBucket", "mybucket-xnbmhcvd");

This gives you the same bucket object that you’d get if you had created this resource in your app.

Here we are assuming the bucket wasn’t created through an SST app. This is why we are using the low-level aws.s3.BucketV2. If this was created in an SST app or in another stage in the same app, there’s a similar static sst.aws.Bucket.get method. Learn more about sharing across stages.

How it works

When you create a resource in your SST app, two things happen. First, the resource is created by making a bunch of calls to your cloud provider. Second, SST makes a call to get the resource from the cloud provider. The data that it gets back is stored in your state.

When you lookup a resource, it skips the creation step and just gets the resource. It does this every time you deploy. But the object you get in both cases is the same.

Lookup properties

The properties used to do a lookup are the same ones that you’d use if you were trying to import them.

We’ve compiled a list of the most commonly lookedup low-level resources and their Import Properties.

Most low-level resources come with a static get method that use this property to look up the resource.

Make it linkable

Let’s take it a step further.

You can use the sst.Linkable component, to be able to link any property of this resource.

sst.config.ts
const storage = new sst.Linkable("MyStorage", {
  properties: {
    domain: bucket.bucketDomainName
  }
});

Here we are using the domain name of the bucket as an example.

And link it to a function.

sst.config.ts
new sst.aws.Function("MyFunction", {
  handler: "src/lambda.handler",
  link: [storage]
});

Now you can use the SDK to access them at runtime.

src/lambda.ts
import { Resource } from "sst";


console.log(Resource.MyStorage.domain);

Pass in a resource

Aside from looking up resources, you can also pass existing resources in to the built-in SST components. This is typically when you are trying to create a new resource and it takes another resource as a part of it.

For example, let’s say you want to add a previously created function as a subscriber to a queue. You can do so by passing its ARN.

sst.config.ts
const queue = new sst.aws.Queue("MyQueue");


queue.subscribe("arn:aws:lambda:us-east-1:123456789012:function:my-function");

How it works

SST is simply asking for the props the underlying resource needs. In this case, it only needs the function ARN.

However, for more complicated resources like VPCs, you might have to pass in a lot more. Here we are creating a new function in an existing VPC.

sst.config.ts
new sst.aws.Function("MyFunction", {
  handler: "src/lambda.handler",
  vpc: {
    subnets: ["subnet-0be8fa4de860618bb"],
    securityGroups: ["sg-0be8fa4de860618bb"]
  }
});

Whereas, for the Cluster component, you might need to pass in a lot more.

sst.config.ts
new sst.aws.Cluster("MyCluster", {
  vpc: {
    id: "vpc-0be8fa4de860618bb",
    securityGroups: ["sg-0be8fa4de860618bb"],
    containerSubnets: ["subnet-0be8fa4de860618bb"],
    loadBalancerSubnets: ["subnet-8be8fa4de850618ff"]
  }
});

These are listed under the vpc prop of the Cluster component.

Attach to a resource

Referencing existing resources also comes in handy when you are attaching to an existing resource. For example, to add a subscriber to an externally created queue:

sst.config.ts
sst.aws.Queue.subscribe("arn:aws:sqs:us-east-1:123456789012:MyQueue", "src/subscriber.handler");

Here we are using the static subscribe method of the Queue component. And it takes the queue ARN that you are trying to attach to.

There are a few other built-in SST components that have static methods like this.

  • Bus
  • Dynamo
  • SnsTopic
  • KinesisStream

With this you can continue to manage the root resource outside of SST, while still being able to attach to them.