From 064be86f08086bef9dfad0b4829d56b8b6b51c00 Mon Sep 17 00:00:00 2001 From: Jye Cusch Date: Wed, 3 Jul 2024 14:58:36 +1000 Subject: [PATCH 1/6] docs(aws): add resource imports docs --- src/nav.config.ts | 4 + .../reference/providers/aws/configuration.mdx | 2 +- src/pages/reference/providers/aws/imports.mdx | 77 +++++++++++++++++++ 3 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 src/pages/reference/providers/aws/imports.mdx diff --git a/src/nav.config.ts b/src/nav.config.ts index e5df448eb..c18147ada 100644 --- a/src/nav.config.ts +++ b/src/nav.config.ts @@ -2963,6 +2963,10 @@ const fullNav: FullNav = { title: 'Topics', href: '/reference/providers/aws/topics', }, + { + title: 'Import Existing Resources', + href: '/reference/providers/aws/imports', + }, ], }, { diff --git a/src/pages/reference/providers/aws/configuration.mdx b/src/pages/reference/providers/aws/configuration.mdx index eb206bd40..0dbaaa385 100644 --- a/src/pages/reference/providers/aws/configuration.mdx +++ b/src/pages/reference/providers/aws/configuration.mdx @@ -2,7 +2,7 @@ export const description = 'Configuring your AWS stacks' # AWS Configuration -# Complete Example with comments +## Complete Example with comments diff --git a/src/pages/reference/providers/aws/imports.mdx b/src/pages/reference/providers/aws/imports.mdx new file mode 100644 index 000000000..71553940a --- /dev/null +++ b/src/pages/reference/providers/aws/imports.mdx @@ -0,0 +1,77 @@ +export const description = 'Importing existing AWS resources' + +# Importing Existing Resources - AWS + +Nitric allows you to import existing AWS resources into your Nitric project. Currently, only [buckets](/storage) and [secrets](/secrets) are supported for import. + +## How imports work + +If you have existing AWS 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](/concepts/project-structure#stack-files). This section allows you to import existing resources and use them in your Nitric project. This indicates to the `nitric/aws` 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 the `nitric/aws` uses 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, 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 identified 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. + +## Importable 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) + +### Buckets + + + Bucket imports are only supported for S3 buckets in the same AWS account and region as the Nitric project. + + +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 +``` + + + Either the bucket's name or ARN can be used to import the bucket. The ARN is recommended as it is more specific. + + +### 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 +``` + +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. From cee85f559f2591287a68e1769dadd08a60af41c5 Mon Sep 17 00:00:00 2001 From: David Moore Date: Wed, 3 Jul 2024 15:25:56 +1000 Subject: [PATCH 2/6] format --- src/pages/reference/providers/aws/imports.mdx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/pages/reference/providers/aws/imports.mdx b/src/pages/reference/providers/aws/imports.mdx index 71553940a..978927c3d 100644 --- a/src/pages/reference/providers/aws/imports.mdx +++ b/src/pages/reference/providers/aws/imports.mdx @@ -27,13 +27,15 @@ The tags added to the resources during deployment may not be removed during the ## Importable 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) + +- [Secrets](/secrets) +- [Buckets](/storage) ### Buckets - Bucket imports are only supported for S3 buckets in the same AWS account and region as the Nitric project. + Bucket imports are only supported for S3 buckets in the same AWS account and + region as the Nitric project. 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. @@ -41,9 +43,9 @@ To import an S3 bucket, you will need to know the bucket's name or ARN. You can 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"; +import { bucket } from '@nitric/sdk' -const images = bucket("images").allow("read", "write", "delete"); +const images = bucket('images').allow('read', 'write', 'delete') ``` ```yaml @@ -53,7 +55,8 @@ import: ``` - Either the bucket's name or ARN can be used to import the bucket. The ARN is recommended as it is more specific. + Either the bucket's name or ARN can be used to import the bucket. The ARN is + recommended as it is more specific. ### Secrets From 418d783bb324231d72e803b03ae8eee74ca28b1a Mon Sep 17 00:00:00 2001 From: David Moore Date: Wed, 3 Jul 2024 15:31:25 +1000 Subject: [PATCH 3/6] spellcheck --- dictionary.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/dictionary.txt b/dictionary.txt index 69d7ef92b..cfbd0407a 100644 --- a/dictionary.txt +++ b/dictionary.txt @@ -195,6 +195,7 @@ VOD todo todos transpiling +ARN ^.+[-:_]\w+$ [a-z]+([A-Z0-9]|[A-Z0-9]\w+) From 00dcff7dd9196e3ae9346f53fd886d30599135b3 Mon Sep 17 00:00:00 2001 From: David Moore Date: Wed, 3 Jul 2024 15:39:52 +1000 Subject: [PATCH 4/6] add import buckets aws config --- src/pages/reference/providers/aws/configuration.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/pages/reference/providers/aws/configuration.mdx b/src/pages/reference/providers/aws/configuration.mdx index 0dbaaa385..4a57f4979 100644 --- a/src/pages/reference/providers/aws/configuration.mdx +++ b/src/pages/reference/providers/aws/configuration.mdx @@ -29,6 +29,10 @@ schedule-timezone: Australia/Sydney # Available since v0.27.0 # Currently only secrets are supported # Available since v0.28.0 import: + # A name ARN map of buckets, where the name matches the nitric name of the bucket you would like to import + buckets: # Available since v1.10.0 + # NOTE: Imported S3 buckets must exist in the same AWS account and region as the Nitric project + my-bucket: arn:... # A name ARN map of secrets, where the name matches the nitric name of the secret you would like to import secrets: # Available since v0.28.0 # In typescript this would import the provided secret reference for a secret declared as From bb4c61da3e7552c60c57263e1ea77a91cb8b3111 Mon Sep 17 00:00:00 2001 From: Jye Cusch Date: Thu, 4 Jul 2024 08:44:27 +1000 Subject: [PATCH 5/6] Update region warning to cover all resources --- src/pages/reference/providers/aws/imports.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/pages/reference/providers/aws/imports.mdx b/src/pages/reference/providers/aws/imports.mdx index 978927c3d..c19abced3 100644 --- a/src/pages/reference/providers/aws/imports.mdx +++ b/src/pages/reference/providers/aws/imports.mdx @@ -31,13 +31,12 @@ The Nitric team is working to expand the list of resources that can be imported. - [Secrets](/secrets) - [Buckets](/storage) -### Buckets - - Bucket imports are only supported for S3 buckets in the same AWS account and - region as the Nitric project. + Only resources in the same AWS account and region as the Nitric project are currently supported. +### 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: From 8cab1945d5854af2820fabb8a5b271c02829c9ca Mon Sep 17 00:00:00 2001 From: Jye Cusch Date: Thu, 4 Jul 2024 08:45:18 +1000 Subject: [PATCH 6/6] lint --- src/pages/reference/providers/aws/imports.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/pages/reference/providers/aws/imports.mdx b/src/pages/reference/providers/aws/imports.mdx index c19abced3..059f99d1f 100644 --- a/src/pages/reference/providers/aws/imports.mdx +++ b/src/pages/reference/providers/aws/imports.mdx @@ -32,7 +32,8 @@ The Nitric team is working to expand the list of resources that can be imported. - [Buckets](/storage) - Only resources in the same AWS account and region as the Nitric project are currently supported. + Only resources in the same AWS account and region as the Nitric project are + currently supported. ### Buckets