You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/2.0/docs/library/tutorials/creating-service-module.md
+44-31Lines changed: 44 additions & 31 deletions
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,27 @@
1
-
# Creating your own Service Module
1
+
# Creating your own Service Module
2
2
3
-
We offer a collection of [service modules](/2.0/docs/library/concepts/service-modules) that piece together individual [modules](/2.0/docs/library/concepts/modules)for specific use cases such as EKS clusters and VPCs with public and private subnets. While we strive to make our service catalog as a complete as possible, you may need to create your own service to suit a specific use case or need for your company.
3
+
We offer a collection of [service modules](/2.0/docs/library/concepts/service-modules) that combine individual [modules](/2.0/docs/library/concepts/modules)to address specific use cases, such as provisioning EKS clusters or VPCs with public and private subnets. While we strive to make the service catalog as comprehensive as possible, you may need to create a custom service to meet a unique requirement for your company.
4
4
5
-
In this guide, you will learn how to create a service that provisions a simple API using the [AWS Lambda Function](/reference/modules/terraform-aws-lambda/lambda/) and [API Gateway](/reference/modules/terraform-aws-lambda/lambda-http-api-gateway/) modules from the Gruntwork Infrastructure as Code (IaC) Library.
5
+
In this guide, you will learn how to create a service that provisions a simple API using the [AWS Lambda Function](/reference/modules/terraform-aws-lambda/lambda/) and [API Gateway](/reference/modules/terraform-aws-lambda/lambda-http-api-gateway/) modules from the Gruntwork Infrastructure as Code (IaC) Library.
6
6
7
-
## Prerequisites
7
+
## Prerequisites
8
8
9
-
- An AWS account with permissions to create the necessary resources
10
-
- An [AWS Identity and Access Management](https://aws.amazon.com/iam/) (IAM) user or role with permissions to create AWS IAM roles, Lambda functions, and API Gateways
11
-
-[AWS Command Line Interface](https://aws.amazon.com/cli/) (AWS CLI) installed on your local machine
12
-
-[Terraform](https://www.terraform.io) installed on your local machine
9
+
- An AWS account with permissions to create the necessary resources
10
+
- An [AWS Identity and Access Management](https://aws.amazon.com/iam/) (IAM) user or role with permissions to create AWS IAM roles, Lambda functions, and API Gateways
11
+
-[AWS Command Line Interface](https://aws.amazon.com/cli/) (AWS CLI) installed on your local machine
12
+
-[Terraform](https://www.terraform.io) installed on your local machine
13
13
14
-
## Create the service
14
+
## Create the service
15
15
16
-
In this section we’ll define a service that provisions an AWS Lambda Function and HTTP API Gateway, with a single proxy route on the API Gateway pointing to the Lambda. This service exposes a simple set of inputs for configuring the Lambda code configuration and name of the provisioned resources.
16
+
In this section, we will define a service that provisions an AWS Lambda Function and an HTTP API Gateway. The API Gateway will include a single proxy route that forwards requests to the Lambda function. This service will expose a simple set of inputs for configuring the Lambda function’s code and naming the provisioned resources.
17
17
18
-
### Create the basic file structure
18
+
### Create the basic file structure
19
+
20
+
Start by creating the basic file structure to contain the service definition. You will need three files:
19
21
20
-
First, create the basic file structure that will contain the service definition. We’ll create three files — `main.tf` which will contain the resource definitions, `variables.tf`, which specifies the possible inputs to the module, and `outputs.tf`, which specifies the values that can be used to pass references to attributes from the resources in the module.
22
+
-`main.tf`: Contains the resource definitions.
23
+
-`variables.tf`: Specifies the possible inputs to the module.
24
+
-`outputs.tf`: Defines the outputs, which allow you to reference attributes from the resources created by the module.
Next, define the module blocks for the AWS Lambda function and HTTP API Gateway. For the Lambda, we will use the [Lambda function module](/reference/modules/terraform-aws-lambda/lambda/), for the HTTP API Gateway we will use the [HTTP API Gateway module](/reference/modules/terraform-aws-lambda/lambda-http-api-gateway/).
35
+
Next, define the module blocks for the AWS Lambda function and HTTP API Gateway. Use the [Lambda function module](/reference/modules/terraform-aws-lambda/lambda/) for the Lambda function, and the [HTTP API Gateway module](/reference/modules/terraform-aws-lambda/lambda-http-api-gateway/) for the HTTP API Gateway.
36
+
37
+
To simplify the configuration for this guide, we define a single route — `ANY /{proxy+}`. This configuration directs the API Gateway to forward all requests matching the path `/*` to the Lambda function. This approach is particularly effective when using an API framework within the Lambda function code to handle request routing.
32
38
33
-
To keep the configuration simple for this guide, we define a single route — `ANY /{proxy+}`. This tells the API Gateway to send any requests matching the path `/*` to the Lambda. This is an effective approach if you are using an API framework in the Lambda function code that can handle request routing. We will also set some defaults for the Lambda to not run in a VPC, have a maximum run time of 30 seconds, and 128MB of memory.
39
+
We will also configure some sensible defaults for the Lambda function, including:
Now that you’ve defined the resources you want to create, you need to define the variables that you want to allow users to pass into the module. You can reference these values in the module using the var syntax, as visible in `gw_service_guide/serverless-api/main.tf`.
70
+
Now that you’ve defined the resources to create, define the variables that users can pass into the module. These variables enable flexible configuration of the module. You can reference these values within the module using the `var` syntax, as shown in `gw_service_guide/serverless-api/main.tf`.
Next, define the outputs from the module. Outputs are convenient ways to pass values between modules when composing a service comprised of many modules. For this guide, we only want a single output — the URL for the API we are provisioning. You may want to define more outputs when developing a module for your company or team. Refer to the Library Reference for the [Lambda function module](/reference/modules/terraform-aws-lambda/lambda/#reference) and [HTTP API Gateway module](/reference/modules/terraform-aws-lambda/lambda-http-api-gateway/#reference) for a full list of outputs available.
96
+
Next, define the outputs for the module. Outputs provide a convenient way to pass values between modules when building a service composed of multiple modules. For this guide, we will define a single output — the URL for the provisioned API. When developing a module for your company or team, you may need to include additional outputs. Refer to the Library Reference for the [Lambda function module](/reference/modules/terraform-aws-lambda/lambda/#reference) and the [HTTP API Gateway module](/reference/modules/terraform-aws-lambda/lambda-http-api-gateway/#reference) for a complete list of available outputs.
Now that you have defined the service, you can reference the service to create the resources in AWS.
107
+
Now that you have defined the service, you can reference it to provision the resources in AWS.
99
108
100
109
### Create the basic file structure
101
110
102
-
First, create the files that will contain the reference to the service. Typically, you would create a module in one repository, then reference it in a different repository. For this tutorial, we’ll just create the reference in the toplevel directory for the sake of simplicity.
111
+
Start by creating the files needed to reference the service. In a typical setup, the module would reside in one repository, while the reference would exist in a separate repository. For this tutorial, we will simplify the structure by creating the reference in the top-level directory.
103
112
104
-
Create a file called `main.tf`, which will contain a reference to the module, a directory called `/src`, which will contain all source code for the Lambda function, and a file called `main.py`, which will contain the Lambda function code.
113
+
Create the following:
114
+
115
+
- A `main.tf` file to reference the module.
116
+
- A `/src` directory to store the Lambda function's source code.
117
+
- A `main.py` file inside the `/src` directory that contains the Lambda function code.
Define a module block in `gw_service_guide/main.tf`that references the relative location of the `serverless-api` service definition for the `source` attribute. In this guide, we are defining a Lambda function running Python 3.9, with the source path pointing to our`/src` directory, and the handler function `lambda_handler` defined in `gw_service_guide/src/main.py`.
128
+
In `gw_service_guide/main.tf`, define a module block that references the relative path of the `serverless-api` service definition for the `source` attribute. In this example, the Lambda function is configured to use Python 3.9, with the source path pointing to the`/src` directory and the handler function set to `lambda_handler` in `gw_service_guide/src/main.py`.
116
129
117
130
```hcl title=gw_service_guide/main.tf
118
131
module "serverless_api" {
@@ -129,7 +142,7 @@ output "api_endpoint" {
129
142
}
130
143
```
131
144
132
-
Next, write a Python function that returns a status code of 200 and a response body stating "Hello from Gruntwork!". The response format is required for API Gateway to successfully return the response, to learn more refer to the [Lambda function response format documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.response).
145
+
Next, write a Python function that returns a status code of 200 and a response body stating "Hello from Gruntwork!". The response must adhere to the required format for API Gateway to successfully process and return the response. To learn more, refer to the [Lambda function response format documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.response).
Now that you have created a service and a reference to the service, you can run `plan` to see the infrastructure resources that will be provisioned by the module and `apply` to create the resources.
157
+
Now that you have created a service and a reference to it, you can run `plan` to preview the infrastructure resources that will be provisioned by the module, and `apply` to create those resources.
145
158
146
159
### Init
147
160
148
-
Before you can run a `plan` or `apply`, you need to run`terraform init`, which performs a series of initialization steps to prepare the working directory for use with Terraform.
161
+
Before running a `plan` or `apply`, you need to execute`terraform init`. This command performs a series of initialization steps to prepare the working directory for use with terraform.
149
162
150
163
```bash
151
164
terraform init
152
165
```
153
166
154
167
### Plan
155
168
156
-
Terraform will generate an execution plan using the `plan` action. The plan shows what resources Terraform determines need to be created or modified.
169
+
Terraform generates an execution plan using the `plan` action. The plan displays the resources that terraform determines need to be created or modified.
157
170
158
171
```bash
159
172
terraform plan
160
173
```
161
174
162
-
In your plan output, you should expect to see 11 resources created, including an AWS Lambda function and permissions, AWS API Gateway, AWS IAM role and policy, and AWS Cloudwatch Log group.
175
+
In your plan output, you should expect to see 11 resources created, including an AWS Lambda function and its permissions, AWS API Gateway, AWS IAM role and policy, and AWS CloudWatch Log group.
163
176
164
177
### Apply
165
178
166
-
After running a `plan` and confirming that all expected resources show that they will be provisioned in the plan, run an `apply` to create the resources.
167
-
179
+
After running a `plan` and confirming that all expected resources will be provisioned, run an `apply` to create the resources.
168
180
169
-
Terraform will create resources when using the `apply` action. Like with the `plan` action, Terraform will determine which resources need to be created or modified. You should expect to see the same resources to be created when running `apply`that are shown when running`plan`.
181
+
Terraform creates resources when using the `apply` action. Similar to the `plan` action, terraform determines which resources need to be created or modified. You should expect the same resources to be created during `apply`as shown in the`plan` output.
170
182
171
183
172
184
```bash
173
185
terraform apply
174
186
```
175
187
176
-
You should see `Apply complete! Resources: 11 added, 0 changed, 0 destroyed.` when the `apply`has completed successfully.
188
+
You should see `Apply complete! Resources: 11 added, 0 changed, 0 destroyed.` when the `apply`process completes successfully.
177
189
178
190
## Curl the endpoint
179
191
180
-
Finally, curl the endpoint to confirm the AWS API Gateway and Lambda function were created successfully. Use `terraform output` to get the URL for the API that was provisioned, then curl the endpoint.
192
+
Finally, use `curl`to confirm that the AWS API Gateway and Lambda function were created successfully. Use the `terraform output`command to retrieve the URL for the API that was provisioned, then curl the endpoint.
@@ -188,4 +200,5 @@ You should receive `{"message": "Hello from Gruntwork!"}` as a response.
188
200
189
201
## What’s next
190
202
191
-
Now that you've defined your own service, consider how you would make this module available to others in your organization. At Gruntwork, we share services using a Github repository called `terraform-aws-service-catalog`, for more information refer to the [Library Reference](/library/reference). Further, try adding tests to this service using [Terratest](https://terratest.gruntwork.io) to ensure that resources are created successfully as changes are made to the service. Finally, consider what other resources you might add to this module. For example, adding authentication via AWS Cognito to the HTTP API Gateway or a DynamoDB table to store data.
203
+
Now that you've defined your own service, consider how you would make this module available to others in your organization. At Gruntwork, we share services using a GitHub repository called `terraform-aws-service-catalog`. For more information, refer to the [Library Reference](/library/reference). Next, try adding tests to this service using [Terratest](https://terratest.gruntwork.io) to ensure resources are created successfully as changes are made to the service. Finally, think about what additional resources you might include in this module. For example, you could add authentication via AWS Cognito to the HTTP API Gateway or a DynamoDB table to store data.
0 commit comments