# Import Resources

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](https://sst.dev/docs/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](https://sst.dev/docs/reference-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`](https://sst.dev/docs/components/#transform) to pass it into the underlying resource.

So let’s look at two examples.

1. Importing into an SST component
2. 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`](https://sst.dev/docs/component/aws/bucket/) component.

1. Start by adding the `import` option in the `transform`.

```
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.

2. 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
```

3. Finally, to clean things up we can remove the `import` line.

```
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`](https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketv2/) resource.

1. Start by adding the `import` option.

```
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.

2. Update the `args`

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

```
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
```

3. Finally, to clean things up we can remove the `import` line.

```
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**.

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

Feel free to _Edit this page_ and submit a PR if you want to add to this list.