improve importing resources docs (#687)

Co-authored-by: Ryan Cartwright <39504851+HomelessDinosaur@users.noreply.github.com>

docs/get-started/foundations/deployment/index.mdx

@@ -167,6 +167,37 @@ Provider specific stack configuration, including advanced configuration options,
   the stack files that target your provider.
 </Note>
 
+## Importing Existing Resources
+
+Nitric allows you to import existing resources into your Nitric project.
+Currently, the [AWS standard provider](/providers/pulumi/aws#importing-existing-resources) supports importing both [buckets](/providers/pulumi/aws#buckets) and [secrets](/providers/pulumi/aws#secrets), while the [Google Cloud standard provider](/providers/pulumi/gcp#importing-existing-resources) supports importing [secrets](/providers/pulumi/gcp#secrets) only. Importing resources via other providers is not yet supported.
+
+<Note>
+  Need to import another resource type or want support for additional providers?
+  Chat with us on [Discord](https://nitric.io/chat) or [open an
+  issue](https://github.com/nitrictech/nitric/issues) on GitHub.
+</Note>
+
+### How imports work
+
+If you have existing resources that you would like to use in your Nitric project, you may be able to import them using the `import` section of your Nitric [stack file](#stacks). This section allows you to import existing resources and use them in your Nitric project. This indicates to the provider that you would like to use the existing resources in your Nitric project, rather than create a new one.
+
+Imports are stack specific, meaning that you can import resources into a specific stack file, and they will only be available in that stack. Other stacks for the same project can either create or import those resources as needed.
+
+### What happens during `nitric up`
+
+When deploying a stack that has imported resources, the resources will not be created. Instead, Nitric will use the referenced resources from the stack file. If the resources can't be located or accessed, the deployment will fail.
+
+Nitric attempts to make the minimum changes needed to the imported resources to make them compatible with the Nitric project. Since Nitric standard providers use custom tags for resource location, the resources will have these tags added during deployment. Additionally, Nitric will add the necessary permissions to the resources to allow the Nitric project to access them, just like it would with resources it creates.
+
+The tags created are extremely unlikely to conflict with existing tags. For example, with the AWS standard provider, an S3 bucket will have these two tags created `x-nitric-{project}-{stack}-{randomId}-type` and `x-nitric-{project}-{stack}-{randomId}-name`. The type tag identifies the type of Nitric resource, and the name tag is the name of the resource in the Nitric project.
+
+### What happens during `nitric down`
+
+When tearing down a stack that has imported resources, the resources will not be deleted. This is because the resources were not created by Nitric, so for safety they're always set to 'retainOnDelete'. If you would like to delete the resources, you will need to do so manually or using whichever tools created those resources initially.
+
+The tags added to the resources during deployment may not be removed during the `nitric down` process. If you intend to redeploy the stack with an updated import, you may need to remove these tags manually.
+
 ## CI/CD
 
 Deploying Nitric applications with CI/CD automation tools is simple. Explore the guides below for examples with common CI/CD tools:

docs/providers/pulumi/aws/index.mdx → docs/providers/pulumi/aws.mdx

@@ -55,7 +55,7 @@ You can create an Access Key by logging into the [AWS console](https://aws.amazo
   for full details on credentials and configuration.
 </Note>
 
-## Locating deployed resources
+## Locating Deployed Resources
 
 This Nitric AWS provider creates a resource tag manager group and tags all possible resources to be referenced by this group. You can locate resources using the [AWS Console](https://console.aws.amazon.com/).
 
@@ -88,6 +88,66 @@ API Endpoints:
 main: https://example.execute-api.us-east-2.amazonaws.com
 ```
 
+## Importing Existing Resources
+
+The Nitric team is working to expand the list of resources that can be imported. Currently, only the following resources are supported:
+
+- [Secrets](/secrets)
+- [Buckets](/storage)
+
+<Note>
+  Currently, only resources in the same AWS account and region as the Nitric project 
+  are supported.
+</Note>
+
+### Buckets
+
+To import an S3 bucket, you will need to know the bucket's name or ARN. You can find the ARN of an S3 bucket in the AWS console or by using the AWS CLI.
+
+First, add the bucket to your project as you usually would if it wasn't imported. Then add the bucket to the `import` section of your stack file. Here's an example of how to import an S3 bucket:
+
+```javascript
+import { bucket } from '@nitric/sdk'
+
+const images = bucket('images').allow('read', 'write', 'delete')
+```
+
+```yaml
+import:
+  buckets:
+    images: arn:aws:s3:::images-bucket-example
+```
+
+<Note>
+  Either the bucket's name or ARN can be used to import the bucket. The ARN is
+  recommended as it is less likely to have a conflict during lookup.
+</Note>
+
+### Secrets
+
+To import a secret, you will need to know the secret's ARN. You can find the ARN of a secret in the AWS console or by using the AWS CLI.
+
+First, add the secret to your project as you usually would if it wasn't imported. Then add the secret to the `import` section of your stack file. Here's an example of how to import a secret:
+
+```javascript
+import { secret } from "@nitric/sdk
+
+const mySecret = secret("credentials").allow("access");
+```
+
+```yaml
+import:
+  secrets:
+    credentials: arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret
+```
+
+<Note>
+  Unlike some other imported resources, secret imports require the ARN to be used. 
+  Providing only the secret's name will be invalid.
+</Note>
+
+Need to import another resource type or have another question? Chat with us on [Discord](https://nitric.io/chat) or [open an issue](https://github.com/nitrictech/nitric/issues) on GitHub.
+
 ## Stack Configuration
 
 ```yaml title:nitric.[stack ID].yaml

docs/providers/pulumi/gcp.mdx

@@ -57,6 +57,37 @@ Download & install the [latest CLI release](https://cloud.google.com/sdk/install
 
 For Google Cloud to allow deployments, a billing account must be [created and attached](https://console.cloud.google.com/billing) to the project you deploy to.
 
+## Importing Existing Resources
+
+The Nitric team is working to expand the list of resources that can be imported. Currently, only the following resources are supported:
+
+- [Secrets](/secrets)
+
+<Note>
+  Only resources in the same GCP project as specified by gcp-project-id are
+  currently supported.
+</Note>
+
+### Secrets
+
+To import a secret, you will need to know the secret's unique name. You can find the name of a secret in the Google Cloud Secret Manager in the browser or by using the gcloud CLI.
+
+First, add the secret to your project as you usually would if it wasn't imported. Then add the secret to the `import` section of your stack file. Here's an example of how to import a secret:
+
+```javascript
+import { secret } from "@nitric/sdk
+
+const mySecret = secret("credentials").allow("access");
+```
+
+```yaml
+import:
+  secrets:
+    credentials: existing-secret
+```
+
+Need to import another resource type or have another question? Chat with us on [Discord](https://nitric.io/chat) or [open an issue](https://github.com/nitrictech/nitric/issues) on GitHub.
+
 ## Stack Configuration
 
 ```yaml title:nitric.[stack ID].yaml

next.config.mjs

@@ -517,6 +517,12 @@ const nextConfig = {
         basePath: false,
         permanent: true,
       },
+      {
+        source: '/docs/providers/pulumi/aws/imports',
+        destination: '/docs/providers/pulumi/aws#importing-existing-resources',
+        basePath: false,
+        permanent: true,
+      },
       {
         source: '/docs/reference/providers/aws/configuration',
         destination: '/docs/providers/pulumi/aws#stack-configuration',