Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Commit 9b40949

Browse files
raksivjyecuschdavemooreuwselisselockhart
authored
Add extension guides to terraform provider (#590)
API Gateway Throttle S3 Server Side Encryption S3 Replicate --------- Co-authored-by: Jye Cusch <[email protected]> Co-authored-by: David Moore <[email protected]> Co-authored-by: Elisse Lockhart <[email protected]>
1 parent 85be073 commit 9b40949

File tree

10 files changed

+565
-2
lines changed

10 files changed

+565
-2
lines changed

‎dictionary.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,9 @@ transpiling
198198
ARN
199199
HTTPS
200200
monorepos
201+
decrypts
202+
deploytf
203+
href
201204

202205
^.+[-:_]\w+$
203206
[a-z]+([A-Z0-9]|[A-Z0-9]\w+)

‎public/images/guides/api-gateway-throttle/throttle.png‎

132 KB
Loading

‎public/images/guides/s3-encryption/encrypt.png‎

98.7 KB
Loading

‎public/images/guides/s3-replicate/replication.png‎

180 KB
Loading

‎src/nav.config.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -571,6 +571,24 @@ const fullNav: FullNav = {
571571
],
572572
},
573573
],
574+
['guides/terraform']: [
575+
{
576+
links: [
577+
{
578+
title: 'AWS S3 Server-side Encryption',
579+
href: '/guides/terraform/s3-encryption',
580+
},
581+
{
582+
title: 'AWS S3 Replication',
583+
href: '/guides/terraform/s3-replicate',
584+
},
585+
{
586+
title: 'AWS API Gateway Throttle',
587+
href: '/guides/terraform/api-gateway-throttle',
588+
},
589+
],
590+
},
591+
],
574592
['guides/deploying']: [
575593
{
576594
links: [
@@ -631,6 +649,11 @@ const fullNav: FullNav = {
631649
href: '/guides/deploying',
632650
icon: BoltIcon,
633651
},
652+
{
653+
title: 'Terraform Guides',
654+
href: '/guides/terraform',
655+
icon: SiTerraform,
656+
},
634657
{
635658
title: 'Examples',
636659
href: '/guides/examples',

‎src/pages/guides.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { FaNodeJs, FaPython, FaJava } from 'react-icons/fa'
2-
import { SiDart } from 'react-icons/si'
2+
import { SiDart, SiTerraform } from 'react-icons/si'
33
import { BiLogoGoLang } from 'react-icons/bi'
44

55
# Nitric Guides
@@ -56,7 +56,14 @@ import { BiLogoGoLang } from 'react-icons/bi'
5656
pattern={2}
5757
/>
5858
</GuidesGrid>
59-
59+
<GuidesGrid title="Extend your Provider">
60+
<Guide
61+
customIcon={SiTerraform}
62+
href="/guides/terraform"
63+
name="Terraform Guides"
64+
description="Learn about using and extending the Nitric Terraform Providers."
65+
/>
66+
</GuidesGrid>
6067
<GuidesGrid title="Resources">
6168
<Guide
6269
href="/guides/examples"

‎src/pages/guides/terraform.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import { SiTerraform } from 'react-icons/si'
2+
3+
export const description = 'How to work with the Terraform Providers'
4+
5+
# Terraform Guides
6+
7+
<GuidesGrid title="Recommended Terraform Guides">
8+
<Guide
9+
customIcon={SiTerraform}
10+
href="/guides/terraform/s3-encryption"
11+
name="AWS S3 Server-side Encryption"
12+
description="Extend the Nitric AWS S3 Terraform provider to add server-side encryption"
13+
14+
/>
15+
16+
<Guide
17+
customIcon={SiTerraform}
18+
href="/guides/terraform/s3-replicate"
19+
name="AWS S3 Replication"
20+
description="Extend the Nitric AWS S3 Terraform provider to replicate S3 buckets"
21+
22+
/>
23+
24+
<Guide
25+
customIcon={SiTerraform}
26+
href="/guides/terraform/api-gateway-throttle"
27+
name="AWS API Gateway Throttle"
28+
description="Extend the Nitric AWS Terraform provider to set API Gateway throttling limits"
29+
/>
30+
</GuidesGrid>

‎src/pages/guides/terraform/api-gateway-throttle.mdx‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
export const description =
2+
'Extend the Nitric AWS Terraform provider to set API Gateway throttling limits'
3+
4+
# Add Throttle Limits to API Gateway
5+
6+
Throttling helps prevent your backend services from being overwhelmed by too many requests at once. This is particularly important if your backend services have limited capacity and can only handle a certain number of requests per second.
7+
8+
Without throttling, a single client could potentially consume all available resources, leaving others with degraded service or no service at all.
9+
10+
## What we'll be doing
11+
12+
1. Review the existing module
13+
2. Configure throttle limits
14+
15+
## Review the existing module
16+
17+
Start by cloning the [Nitric repository](https://github.com/nitrictech/nitric), then examine how the Terrraform provider [provisions an API Gateway](https://github.com/nitrictech/nitric/tree/main/cloud/aws/deploytf/.nitric/modules/api).
18+
19+
```bash
20+
git clone https://github.com/nitrictech/nitric
21+
cd nitric
22+
```
23+
24+
The AWS API module in the default Terraform provider performs the following tasks:
25+
26+
1. Defines an HTTP API Gateway with specified name, protocol, and API specification.
27+
2. Sets up a "$default" deployment stage with automatic deployment enabled.
28+
3. Allows the API Gateway to invoke specified Lambda functions.
29+
4. Looks up existing certificates for specified domains.
30+
5. Configures custom domain names for the API Gateway using the retrieved certificates.
31+
32+
To begin our customization, we will start adding configuration to the existing module.
33+
34+
## Configure throttle limits
35+
36+
Update `aws_apigatewayv2_stage.stage` in `aws/deploytf/.nitric/modules/bucket/main.tf` to add `default_route_settings` which include throttling limits:
37+
38+
```hcl {{ tag: 'aws/deploytf/.nitric/modules/bucket/main.tf' }}
39+
resource "aws_apigatewayv2_stage" "stage" {
40+
api_id = aws_apigatewayv2_api.api_gateway.id
41+
name = "$default"
42+
auto_deploy = true
43+
44+
default_route_settings {
45+
throttling_burst_limit = 1000
46+
throttling_rate_limit = 500
47+
}
48+
}
49+
```
50+
51+
<Note>
52+
Full documentation can be found on the [Terraform
53+
registry](https://registry.terraform.io/providers/hashicorp/aws/2.70.2/docs/resources/apigatewayv2_stage#throttling_burst_limit).
54+
</Note>
55+
56+
## Build and use your updated provider
57+
58+
The Nitric project includes a make file that will build and install your provider as `nitric/[email protected]` by default.
59+
60+
Navigate to `nitric/cloud/aws` and run `make install` to build and install the modified provider binary.
61+
62+
```bash
63+
cd nitric/cloud/aws
64+
65+
make install
66+
```
67+
68+
The provider can then be used directly in your project's stack file as follows.
69+
70+
```yaml
71+
# The nitric provider to use
72+
provider: nitric/[email protected]
73+
74+
# The target aws region to deploy to
75+
region: us-east-2
76+
```
77+
78+
<Note>
79+
If you don't have a stack file use `nitric stack new` to create one.
80+
</Note>
81+
82+
Because the [Terraform providers](/reference/providers/terraform) are in preview, you'll also need to enable `beta-providers` in your Nitric project by adding the following to your project's nitric.yaml file:
83+
84+
```yaml {{ tag: 'nitric.yaml' }}
85+
preview:
86+
- beta-providers
87+
```
88+
89+
You can generate the Terraform project as usual by running the `nitric up` command:
90+
91+
```bash
92+
nitric up
93+
```
94+
95+
To deploy the application using Terraform, you can navigate into your Terraform stack directory and use the standard Terraform commands:
96+
97+
```bash
98+
terraform init
99+
terraform plan
100+
terraform apply
101+
```
102+
103+
Finally, log into the [AWS console](https://us-east-1.console.aws.amazon.com/apigateway/main/apis?region=us-east-2) to verify the configuration was applied.
104+
105+
<img
106+
src="/docs/images/guides/api-gateway-throttle/throttle.png"
107+
className="rounded"
108+
alt="aws console api gateway throttle settings"
109+
/>

‎src/pages/guides/terraform/s3-encryption.mdx‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
export const description =
2+
'Extend the Nitric AWS S3 Terraform provider to add server-side encryption'
3+
4+
# Add server-side encryption
5+
6+
Server-side encryption (SSE) in Amazon S3 automatically encrypts data when it is written to the storage service and decrypts it when accessed, providing robust data protection, compliance with regulatory requirements, and ease of management.
7+
8+
<Note>
9+
Server-side encryption with Amazon S3 managed keys (SSE-S3) is free. Other
10+
encryption options may incur costs. Amazon offers pricing details on their
11+
[pricing page](https://aws.amazon.com/s3/pricing/).
12+
</Note>
13+
14+
## What we'll be doing
15+
16+
1. Review the existing module
17+
2. Configure server-side encryption (SSE)
18+
19+
## Review the existing module
20+
21+
Start by cloning the [Nitric repository](https://github.com/nitrictech/nitric), then examine how the Terrraform provider [provisions an S3 bucket](https://github.com/nitrictech/nitric/tree/main/cloud/aws/deploytf/.nitric/modules/bucket).
22+
23+
```bash
24+
git clone https://github.com/nitrictech/nitric
25+
cd nitric
26+
```
27+
28+
The AWS S3 module in the default Terraform provider performs the following tasks:
29+
30+
1. Creates a unique ID for the S3 bucket to ensure unique naming.
31+
2. Provisions an S3 bucket with a unique name using the generated ID.
32+
3. Tags the bucket for identification.
33+
4. Grants S3 permission to invoke specified Lambda functions.
34+
5. Configures S3 bucket notifications to trigger Lambda functions based on specified events using dynamic blocks.
35+
36+
To begin our customization, we will start adding configuration to this module.
37+
38+
## Add server-side encryption (SSE)
39+
40+
Add the following at the end of `aws/deploytf/.nitric/modules/bucket/main.tf`:
41+
42+
```hcl {{ tag: 'aws/deploytf/.nitric/modules/bucket/main.tf' }}
43+
# AWS S3 bucket server-side encryption configuration
44+
resource "aws_s3_bucket_server_side_encryption_configuration" "bucket_encryption" {
45+
bucket = aws_s3_bucket.bucket.bucket
46+
47+
rule {
48+
apply_server_side_encryption_by_default {
49+
sse_algorithm = "AES256"
50+
}
51+
}
52+
}
53+
```
54+
55+
<Note>
56+
Full documentation can be found on the [Terraform
57+
registry](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_server_side_encryption_configuration).
58+
</Note>
59+
60+
## Build and use your modified provider
61+
62+
The Nitric project includes a make file that will build and install your provider as `nitric/[email protected]` by default.
63+
64+
Navigate to `nitric/cloud/aws` and run `make install` to build and install the modified provider binary.
65+
66+
```bash
67+
cd nitric/cloud/aws
68+
69+
make install
70+
```
71+
72+
The provider can then be used directly in your project's stack file as follows.
73+
74+
```yaml
75+
# The nitric provider to use
76+
provider: nitric/[email protected]
77+
78+
# The target aws region to deploy to
79+
region: us-east-2
80+
```
81+
82+
<Note>
83+
If you don't have a stack file use `nitric stack new` to create one.
84+
</Note>
85+
86+
Because the [Terraform providers](/reference/providers/terraform) are in preview, you'll also need to enable `beta-providers` in your Nitric project by adding the following to your project's nitric.yaml file:
87+
88+
```yaml {{ tag: 'nitric.yaml' }}
89+
preview:
90+
- beta-providers
91+
```
92+
93+
You can generate the Terraform project as usual by running the `nitric up` command:
94+
95+
```bash
96+
nitric up
97+
```
98+
99+
To deploy the application using Terraform, you can navigate into your Terraform stack directory and use the standard Terraform commands:
100+
101+
```bash
102+
terraform init
103+
terraform plan
104+
terraform apply
105+
```
106+
107+
Finally, log into the [AWS console](https://us-east-1.console.aws.amazon.com/s3/buckets?region=us-east-2) to verify the encryption configuration was applied.
108+
109+
<img
110+
src="/docs/images/guides/s3-encryption/encrypt.png"
111+
className="rounded"
112+
alt="aws console s3 management for replication."
113+
/>

0 commit comments

Comments
 (0)