From e916e6014a337c1e8c7b5d05c02f21a8a83c234d Mon Sep 17 00:00:00 2001 From: David Moore Date: Tue, 17 Dec 2024 11:57:01 +1100 Subject: [PATCH 1/5] move pulumi aws imports into aws page --- .../pulumi/{aws/index.mdx => aws.mdx} | 57 ++++++++++++- docs/providers/pulumi/aws/imports.mdx | 82 ------------------- next.config.mjs | 6 ++ 3 files changed, 62 insertions(+), 83 deletions(-) rename docs/providers/pulumi/{aws/index.mdx => aws.mdx} (77%) delete mode 100644 docs/providers/pulumi/aws/imports.mdx diff --git a/docs/providers/pulumi/aws/index.mdx b/docs/providers/pulumi/aws.mdx similarity index 77% rename from docs/providers/pulumi/aws/index.mdx rename to docs/providers/pulumi/aws.mdx index 310e80a56..5fcb53514 100644 --- a/docs/providers/pulumi/aws/index.mdx +++ b/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. -## 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,61 @@ 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) + + + 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: + +```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. + ## Stack Configuration ```yaml title:nitric.[stack ID].yaml diff --git a/docs/providers/pulumi/aws/imports.mdx b/docs/providers/pulumi/aws/imports.mdx deleted file mode 100644 index bafa40b28..000000000 --- a/docs/providers/pulumi/aws/imports.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -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](/get-started/foundations/deployment#stacks). 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) - - - 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: - -```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. diff --git a/next.config.mjs b/next.config.mjs index 2345b2e30..cf05be12e 100644 --- a/next.config.mjs +++ b/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', From 210707e90217ae53c073e6fc7639711095084f11 Mon Sep 17 00:00:00 2001 From: David Moore Date: Tue, 17 Dec 2024 12:14:19 +1100 Subject: [PATCH 2/5] add generic importing resources section to foundations deployment --- .../foundations/deployment/index.mdx | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/get-started/foundations/deployment/index.mdx b/docs/get-started/foundations/deployment/index.mdx index 0b8fa2d04..549fe3b01 100644 --- a/docs/get-started/foundations/deployment/index.mdx +++ b/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. +## 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. + + + 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. + + +### 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 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, 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 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. + ## CI/CD Deploying Nitric applications with CI/CD automation tools is simple. Explore the guides below for examples with common CI/CD tools: From c41b7bdf41b853222be24dbec66dbd3d39fb6212 Mon Sep 17 00:00:00 2001 From: David Moore Date: Tue, 17 Dec 2024 12:17:49 +1100 Subject: [PATCH 3/5] add gcp importing resources section --- docs/providers/pulumi/gcp.mdx | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/providers/pulumi/gcp.mdx b/docs/providers/pulumi/gcp.mdx index 6bb32c539..13b697ff6 100644 --- a/docs/providers/pulumi/gcp.mdx +++ b/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) + + + Only resources in the same GCP project as specified by gcp-project-id are + currently supported. + + +### 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 From 462652c7ed463525fa75375967be79d537437f96 Mon Sep 17 00:00:00 2001 From: David Moore <4121492+davemooreuws@users.noreply.github.com> Date: Thu, 19 Dec 2024 12:03:15 +1100 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Ryan Cartwright <39504851+HomelessDinosaur@users.noreply.github.com> --- docs/get-started/foundations/deployment/index.mdx | 4 ++-- docs/providers/pulumi/aws.mdx | 14 +++++++++----- docs/providers/pulumi/gcp.mdx | 2 +- 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/get-started/foundations/deployment/index.mdx b/docs/get-started/foundations/deployment/index.mdx index 549fe3b01..d721d925b 100644 --- a/docs/get-started/foundations/deployment/index.mdx +++ b/docs/get-started/foundations/deployment/index.mdx @@ -188,9 +188,9 @@ Imports are stack specific, meaning that you can import resources into a specifi 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 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. +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 identified the type of nitric resource, and the name tag is the name of the resource in the Nitric project. +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` diff --git a/docs/providers/pulumi/aws.mdx b/docs/providers/pulumi/aws.mdx index 5fcb53514..a93d77c92 100644 --- a/docs/providers/pulumi/aws.mdx +++ b/docs/providers/pulumi/aws.mdx @@ -96,15 +96,15 @@ 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. + Currently, only resources in the same AWS account and region as the Nitric project + are 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: +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' @@ -120,14 +120,14 @@ import: Either the bucket's name or ARN can be used to import the bucket. The ARN is - recommended as it is more specific. + recommended as it is less likely to have a conflict during lookup. ### 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: +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 @@ -141,6 +141,10 @@ import: credentials: arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret ``` + + Unlike some other imported resources, secret imports require the ARN to be used. + Providing only the secret's name will be invalid. + 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 diff --git a/docs/providers/pulumi/gcp.mdx b/docs/providers/pulumi/gcp.mdx index 13b697ff6..a9689a29b 100644 --- a/docs/providers/pulumi/gcp.mdx +++ b/docs/providers/pulumi/gcp.mdx @@ -72,7 +72,7 @@ The Nitric team is working to expand the list of resources that can be imported. 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: +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 From 3902c5f29107494d75ab6ba146fcea0e43ce2dd2 Mon Sep 17 00:00:00 2001 From: Ryan Cartwright <39504851+HomelessDinosaur@users.noreply.github.com> Date: Thu, 19 Dec 2024 12:13:06 +1100 Subject: [PATCH 5/5] Update docs/providers/pulumi/aws.mdx --- docs/providers/pulumi/aws.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/providers/pulumi/aws.mdx b/docs/providers/pulumi/aws.mdx index a93d77c92..606a027df 100644 --- a/docs/providers/pulumi/aws.mdx +++ b/docs/providers/pulumi/aws.mdx @@ -145,6 +145,7 @@ import: Unlike some other imported resources, secret imports require the ARN to be used. Providing only the secret's name will be invalid. + 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