Import Resources

Import previously created resources into your app.

Importing is the process of bringing some previously created resources into your SST app. This’ll allow SST to manage them moving forward.

This is useful for when you are migrating to SST or if you had manually created some resources in the past.

How it works

SST keeps a state of your app. It contains all the resources that are managed by your app.

When you import a resource, it gets added to this state. This means that if you remove this resource in your code, it’ll also remove the resource.

It’s as if this resource had been created by your app.

When not to import

This is fine for most cases. But for some teams these resources might be managed by other teams. Or they are being managed by a different IaC tool. Meaning that you don’t want to manage it in your app.

In these cases you should not be importing these resources. You are probably looking to reference these resources.

How to import

You import resources by passing in a property of the resource you want to import into your app. Resources have a property that you can import with and this is different for different resources. We’ll look at this below.

If you are importing into an SST component, you’ll need to use a transform to pass it into the underlying resource.

So let’s look at two examples.

Importing into an SST component
Importing into a Pulumi resource

SST component

Let’s start with an existing S3 Bucket with the following name.

mybucket-xnbmhcvd

We want to import this bucket into the Bucket component.

Start by adding the import option in the transform.
sst.config.ts
```
new sst.aws.Bucket("MyBucket", {
  transform: {
    bucket: (args, opts) => {
      opts.import = "mybucket-xnbmhcvd";
    }
  }
});
```
The transform.bucket is telling this component that instead of creating a new underlying S3 Bucket resource, we want to import an existing bucket.

Let’s deploy this.
```
sst deploy
```
This will give you an error that looks something like this.
```
✕  Failed
   inputs to import do not match the existing resource

   Set the following in your transform:
   - `args.bucket = "mybucket-xnbmhcvd";`
   - `args.forceDestroy = undefined;`
```
This is telling us that the resource that the Bucket component is trying to create does not match the one you are trying to import. This makes sense because you might’ve previously created this with a configuration that’s different from what SST creates by default.

Update the args

The above error tells us exactly what we need to do next. Add the given lines to your transform.

new sst.aws.Bucket("MyBucket", {
  transform: {
    bucket: (args, opts) => {
      args.bucket = "mybucket-xnbmhcvd";
      args.forceDestroy = undefined;

      opts.import = "mybucket-xnbmhcvd";
    }
  }
});

Now if you deploy this again.

sst deploy

You’ll notice that the bucket has been imported.

|  Imported    MyBucket aws:s3:BucketV2

Finally, to clean things up we can remove the import line.
sst.config.ts
```
new sst.aws.Bucket("MyBucket", {
  transform: {
    bucket: (args, opts) => {
      args.bucket = "mybucket-xnbmhcvd";
      args.forceDestroy = undefined;

      opts.import = "mybucket-xnbmhcvd";
    }
  }
});
```
This bucket is now managed by your app and you can now deploy as usual.

You do not want to remove the args changes. This matters for the args.bucket prop because the name is generated by SST. So if you remove this, SST will generate a new bucket name and remove the old one!

Pulumi resource

You might want to also import resources into your SST app that don’t have a built-in SST component. In these cases, you can import them into a low-level Pulumi resource.

Let’s take the same S3 Bucket example. Say you have an existing bucket with the following name.

mybucket-xnbmhcvd

We want to import this bucket into the aws.s3.BucketV2 resource.

Start by adding the import option.
sst.config.ts
```
new aws.s3.BucketV2("MyBucket",
  {
    objectLockEnabled: undefined
  },
  {
    import: "mybucket-xnbmhcvd"
  }
);
```
The objectLockEnabled prop here, is for illustrative purposes. We are trying to demonstrate a case where you are importing a resource in a way that it wasn’t created.

Let’s deploy this.
```
sst deploy
```
This will give you an error that looks something like this.
```
✕  Failed
   inputs to import do not match the existing resource

   Set the following:
   - `objectLockEnabled: undefined,`
```
This is telling us that the resource that the BucketV2 component is trying to create does not match the one you are trying to import.

This makes sense because you might’ve previously created this with a configuration that’s different from what you are defining. Recall the objectLockEnabled prop we had added above.
Update the args

The above error tells us exactly what we need to do next. Add the given lines in your args.
sst.config.ts
```
new aws.s3.BucketV2("MyBucket",
  {
    objectLockEnabled: undefined
  },
  {
    import: "mybucket-xnbmhcvd"
  }
);
```
Now if you deploy this again.
```
sst deploy
```
You’ll notice that the bucket has been imported.
```
|  Imported    MyBucket aws:s3:BucketV2
```
Finally, to clean things up we can remove the import line.
sst.config.ts
```
new aws.s3.BucketV2("MyBucket",
  {
    objectLockEnabled: undefined
  },
  {
    import: "mybucket-xnbmhcvd"
  }
);
```
This bucket is now managed by your app and you can now deploy as usual.

Import properties

In the above examples we are importing a bucket using the bucket name. We need the bucket name because that’s what AWS internally uses to do a lookup. But this is different for different resources.

So we’ve compiled a list of the most common resources you might import, along with the property to import them with.

You can look this up by going to the Import section of a resource’s doc. For example, here’s the one for a aws.s3.BucketV2.

The following table lists the properties you need to pass in to the import prop of the given resource to be able to import it.

For example, for aws.s3.BucketV2, the property is bucket name and it looks something like, some-unique-bucket-name.

Resource	Property	Example
`aws.ec2.Vpc`	VPC ID	`vpc-a01106c2`
`aws.iam.Role`	Role name	`role-name`
`aws.sqs.Queue`	Queue URL	`https://queue.amazonaws.com/80398EXAMPLE/MyQueue`
`aws.sns.Topic`	Topic ARN	`arn:aws:sns:us-west-2:0123456789012:my-topic`
`aws.rds.Cluster`	Cluster identifier	`aurora-prod-cluster`
`aws.ecs.Service`	Cluster and service name	`cluster-name/service-name`
`aws.ecs.Cluster`	Cluster name	`cluster-name`
`aws.s3.BucketV2`	Bucket name	`bucket-name`
`aws.kinesis.Stream`	Stream name	`my-kinesis-stream`
`aws.dynamodb.Table`	Table name	`table-name`
`aws.lambda.Function`	Function name	`function-name`
`aws.apigatewayv2.Api`	API ID	`12345abcde`
`aws.cognito.UserPool`	User Pool ID	`us-east-1_abc123`
`aws.apigateway.RestApi`	REST API ID	`12345abcde`
`aws.cloudwatch.LogGroup`	Log Group name	`my-log-group`
`aws.cognito.IdentityPool`	Identity Pool ID	`us-east-1:1a234567-8901-234b-5cde-f6789g01h2i3`
`aws.cloudfront.Distribution`	Distribution ID	`E74FTE3EXAMPLE`

Feel free to Edit this page and submit a PR if you want to add to this list.