Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
90 commits
Select commit Hold shift + click to select a range
a44ed30
Add example IA for IaC
MoonMoon1919 May 3, 2023
f5f067b
add library reference to IaC docs
MoonMoon1919 May 4, 2023
26d4750
remove other reference to library
MoonMoon1919 May 4, 2023
fd19cf4
tidy up
MoonMoon1919 May 4, 2023
b8154e7
more tidy
MoonMoon1919 May 4, 2023
5e27875
remove guides from nav
MoonMoon1919 May 4, 2023
d2faecd
Lots of stuff:
eak12913 May 4, 2023
992ee43
add label for IaC docs
MoonMoon1919 May 4, 2023
7f72b06
add sidebars for placeholder product docs
MoonMoon1919 May 5, 2023
ef733e6
fix typo
MoonMoon1919 May 5, 2023
247ad92
Add pipelines scaffolding
May 5, 2023
dc65acd
add some fun placeholder text
May 5, 2023
481f17f
Check in current progress on RefArch
zackproser May 5, 2023
341c185
Fix URL
eak12913 May 5, 2023
d4c855e
Add more refarch scaffolding
zackproser May 5, 2023
f8fa6cb
Update dropdown Ref Arch link
zackproser May 5, 2023
23d7516
fold in Ebens feedback
MoonMoon1919 May 5, 2023
2167c93
add tear down section
MoonMoon1919 May 5, 2023
10aa959
address feedback from Eben
MoonMoon1919 May 8, 2023
c3f1d99
Implement refarch sections: overview + bootstrapping
zackproser May 8, 2023
e7300de
Begin building out refarch/usage section
zackproser May 8, 2023
7edd9a1
add stubbed support page for refarch to make PR app work again
MoonMoon1919 May 8, 2023
283a174
Check in accessing the Ref Arch docs
zackproser May 9, 2023
9d310f4
shift things around per feedback
MoonMoon1919 May 10, 2023
1ef702e
make pipelines sidebar be always open
MoonMoon1919 May 10, 2023
d676684
make library reference a page
MoonMoon1919 May 10, 2023
b5f75cf
Implement initial RefArch section feedback:
zackproser May 10, 2023
d62d0cb
fix sidebar for refarch
MoonMoon1919 May 10, 2023
4555a01
remove unused pages
MoonMoon1919 May 10, 2023
4680574
minor wording tweaks
MoonMoon1919 May 10, 2023
a5b9f35
Build out new bootstrapping sections per feedback
zackproser May 10, 2023
8347e45
Modify bootstrap sections, add preflight checks page
zackproser May 10, 2023
ff315d4
Split maintenance tasks out into separate pages
zackproser May 10, 2023
55105a3
Finish implementing RefArch IA feedback
zackproser May 10, 2023
5f6d5cc
rename Learning Pipelines to Getting Started
MoonMoon1919 May 10, 2023
46b8b35
revert stay-up-to-date
MoonMoon1919 May 11, 2023
7c1f11b
add overview to pipelines sidebar
May 11, 2023
da4ab09
Implement IA feedback on RefArch section
zackproser May 11, 2023
354961c
rework parts of the intro section (lots more stuff)
eak12913 May 11, 2023
2ac57bc
Reworked the intro section.
eak12913 May 11, 2023
3924f68
Update link to us docId link format
eak12913 May 11, 2023
9919138
Update link to us docId link format
eak12913 May 11, 2023
2180bb2
Fix link
eak12913 May 11, 2023
c1962be
change port
MoonMoon1919 May 11, 2023
7bf1f0e
change port back
MoonMoon1919 May 11, 2023
4912a33
fix link
MoonMoon1919 May 11, 2023
7de742b
Added the TFC/TFE to the IaC library docs sidebar.
eak12913 May 12, 2023
f2b7e07
restore stay-up-to-date
MoonMoon1919 May 18, 2023
e247a34
[CORE-911] Doc updates for the intro section (#797)
eak12913 May 18, 2023
128e531
Feat(CORE-940): add IAC getting started page (#790)
MoonMoon1919 May 18, 2023
e335af0
Feat(CORE-942): Add staying up to date docs for IaC library (#791)
MoonMoon1919 May 18, 2023
c959289
Add FAQ link to developer portal sidebar (#800)
oredavids May 18, 2023
8eb5626
Add IaC Overview Pages - CORE-908 (#792)
arsci May 22, 2023
a46d0e0
[CORE-950] Pipelines single account tutorial (#806)
May 22, 2023
f2e0919
[CORE-948] pipelines how it works (#808)
May 22, 2023
c2ed66a
[CORE-910] pipelines intro (#807)
May 22, 2023
f961659
IaC Overview Updates - CORE-908 (#811)
arsci May 23, 2023
005092c
feat(CORE-949): Add pipelines maintenance guide (#801)
MoonMoon1919 May 24, 2023
e7d4f3d
Fix Dev portal FAQ link and sort results (#813)
oredavids May 24, 2023
a15e8d3
Chore: Address feedback from review session (#814)
MoonMoon1919 May 25, 2023
931b2c5
Add related FAQ section to dev portal pages (#820)
oredavids May 25, 2023
7754a29
add review fixes for pipelines comments (#822)
May 25, 2023
fe47051
flip order of sidebar for iac library reference (#819)
MoonMoon1919 May 25, 2023
1dc5d27
feat(CORE-944): RefArch configuration (#802)
zackproser May 25, 2023
38dbfb2
Pipelines maintain changes after review session (#817)
MoonMoon1919 May 25, 2023
c9849a5
[CORE-911] Review comments for intro section (#816)
eak12913 May 25, 2023
d12093c
[CORE-945] Add content to RefArch usage section (#815)
eak12913 May 25, 2023
2400d39
Fixup Pipelines docs (#824)
MoonMoon1919 May 25, 2023
f9b51a8
Add Library Reference placeholder page (#821)
arsci May 25, 2023
3d84b64
IaC Overview live fixes (#825)
arsci May 25, 2023
01d3ac0
Remove links to incomplete pages for IaC library docs (#830)
MoonMoon1919 May 26, 2023
8966cea
Merge branch 'master' into example/CORE-861/demonstrate-iac-ia
eak12913 May 26, 2023
1356133
Address live review comments (#827)
May 26, 2023
472b32e
Turn on syntax highlighting for additional languages that we use. Tho…
eak12913 May 26, 2023
eec1f9d
Update IaC sections after live team feedback (#828)
MoonMoon1919 May 26, 2023
879d6c8
Added docker to be syntax highlighted
eak12913 May 26, 2023
6d0b0da
Updated the staying up to date section to fill in instructions from o…
eak12913 May 26, 2023
e27e533
Updated to remove the issues page for now. Also updated iac sidebar t…
eak12913 May 26, 2023
66cef51
Finish caution for installing tools manually (#832)
MoonMoon1919 May 26, 2023
10522ef
fix oxford comma
MoonMoon1919 May 26, 2023
1350fcb
Reworded to make clearer
eak12913 May 26, 2023
37c3769
[CORE-926] Add knowledge-base sidebar link to Pipelines and RefArch (…
oredavids May 26, 2023
eccb194
Added releases and update guides to footer
eak12913 May 26, 2023
47d6778
Ref Arch Intro (#809)
May 26, 2023
2c37ce6
redo landing page (#833)
MoonMoon1919 May 26, 2023
e1077f0
Implement RefArch Access / Set up AWS Auth (#798)
zackproser May 26, 2023
7d3d7e5
Update docusaurus.config.js
MoonMoon1919 May 26, 2023
daf061d
remove guides sidebar
MoonMoon1919 May 30, 2023
8b7c479
Remove lorem pages fro example (#834)
MoonMoon1919 May 30, 2023
db4b9b5
add using our modules page to iac sidebar
MoonMoon1919 May 30, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,8 @@ For security, sign in emails expire after 10 minutes. You can enter your email a

If you are the admin for your organization, you'll be prompted to confirm details including your company address and phone number, as well as a billing email. Provide the required information and click **Continue** to finish signing in.

## Related Knowledge Base Discussions

<!-- ##DOCS-SOURCER-START
{
"sourcePlugin": "local-copier",
"hash": "01375ec9b14d989af4af205eba101d88"
}
##DOCS-SOURCER-END -->
- [Invitation to the Developer Portal not received](https://github.com/orgs/gruntwork-io/discussions/716)
- [Trouble logging into the Portal with email](https://github.com/orgs/gruntwork-io/discussions/395)
- [How can the email associated with an account be changed?](https://github.com/orgs/gruntwork-io/discussions/714)
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,8 @@ This change will take effect immediately. Any team members who have accepted the

The number of licenses available depends on the level of your subscription. You can see the total number of licenses as well as the number remaining at the top of the [Team](https://app.gruntwork.io/team) page. If you need to invite more team members than your current license limit allows, you may request additional licenses, which are billed at a standard monthly rate. To do so, contact sales@gruntwork.io.

## Related Knowledge Base Discussions

<!-- ##DOCS-SOURCER-START
{
"sourcePlugin": "local-copier",
"hash": "702a33b934d092e229bc9c8d17e92387"
}
##DOCS-SOURCER-END -->
- [Invitation to the Developer Portal not received](https://github.com/orgs/gruntwork-io/discussions/716)
- [Trouble logging into the Portal with email](https://github.com/orgs/gruntwork-io/discussions/395)
- [How can the email associated with an account be changed?](https://github.com/orgs/gruntwork-io/discussions/714)
Original file line number Diff line number Diff line change
@@ -1,22 +1,20 @@
# Link Your GitHub ID
# Link Your GitHub Account

Gruntwork provides all code included in your subscription through GitHub. You’ll need to link a GitHub ID to your account in order to access the IaC Library on GitHub. Follow the steps below to link your GitHub ID.

## Linking your GitHub account
Gruntwork provides all code included in your subscription through GitHub. You need to link a GitHub ID to your Gruntwork Developer Portal account in order to access the IaC Library on GitHub. Follow the steps below to link your GitHub ID.

1. First, sign in to the [Gruntwork Developer Portal](https://app.gruntwork.io).
2. Click the **Link my GitHub Account** button in the notice at the top of the home page, or the corresponding button located in your [Profile Settings](https://app.gruntwork.io/settings/profile).
3. Sign in to your GitHub account, then click the **Authorize** button to confirm the connection.
4. After being redirected back to the Gruntwork Developer Portal, click the **Accept My Invite** button. This will take you to GitHub again, where you can accept an invitation to join the Gruntwork organization. (You can ignore the corresponding invite email you receive from GitHub.)
5. Click **Join Gruntwork** to accept the invitation and access the IaC Library.

Once you’ve linked your account, the notice on the home page will disappear and you’ll find your GitHub ID recorded in your [Profile Settings](https://app.gruntwork.io/settings/profile). Going forward, you’ll have access to all private repositories included in your subscription. If you haven’t yet done so, we strongly recommend [adding an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) to your GitHub account. An SSH key is required to access the Gruntwork IaC library without adding a password in your Terraform code.
:::info

Once you’ve linked your account, the notice on the home page will disappear and you’ll find your GitHub ID recorded in your [Profile Settings](https://app.gruntwork.io/settings/profile). Going forward, you’ll have access to all private repositories included in your subscription. If you haven’t done so yet, we strongly recommend [adding an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) to your GitHub account. An SSH key is required to access the Gruntwork IaC library without adding a password in your Terraform code.

## Linking a new GitHub account
:::

To link a new GitHub ID, you’ll first have to unlink the current one. Although uncommon, note that any private forks of Gruntwork repos will be deleted when you unlink your account.
## Related Knowledge Base Discussions

1. Sign in to the Gruntwork Developer Portal and navigate to your [Profile Settings](https://app.gruntwork.io/settings/profile).
2. Click **Unlink** in the description under the **GitHub Account** section.
3. Click **Yes, Unlink My Account** in the confirmation dialog that appears.
4. Proceed with the [steps above](#linking-your-github-account) to link a new GitHub account *using a private/incognito browser window*. (This guarantees you’ll have an opportunity to specify the new account you wish to link.)
- [I have linked my GitHub Account but do not have code access](https://github.com/orgs/gruntwork-io/discussions/715)
- [How can I change my GitHub account (unlink/link)?](https://github.com/orgs/gruntwork-io/discussions/713)
2 changes: 1 addition & 1 deletion _docs-sources/guides/working-with-code/using-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ This code pulls in a module using Terraform’s native `module` functionality. F

The `source` URL in the code above uses a Git URL with SSH authentication (see
[module sources](https://www.terraform.io/docs/modules/sources.html) for all the types of `source` URLs you can use).
If you followed the [SSH key instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) when [linking your GitHub ID](/intro/dev-portal/link-github-id.md), this will allow you to access private repos in the Gruntwork
If you followed the [SSH key instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) when [linking your GitHub ID](/developer-portal/link-github-id.md), this will allow you to access private repos in the Gruntwork
Infrastructure as Code Library without having to hard-code a password in your Terraform code.

#### Versioned URL
Expand Down
9 changes: 9 additions & 0 deletions _docs-sources/iac/getting-started/accessing-the-code.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Accessing the code

Gruntwork provides all code included in your subscription to the Infrastructure as Code (IaC) library through GitHub. To gain access to the IaC Library, you must first [create an account in the Developer Portal](../../developer-portal/create-account.md). Once you have an account, you must [link your GitHub ID](../../developer-portal/link-github-id) to your Developer Portal account to gain access to the IaC Library.

## Accessing Modules and Services in the IaC library

Once you have gained access to the Gruntwork IaC library, you can view the source code for our modules and services in [GitHub](https://github.com/orgs/gruntwork-io/repositories). For a full list of modules and services, check the [Library Reference](../../iac/reference/index.md).

In GitHub, each IaC repository is prefixed with `terraform-aws-` then a high level description of the modules it contains. For example, Amazon SNS, SQS, MSK, and Kinesis are located in the `terraform-aws-messaging` repository. In each repository, the modules are located in the `modules` directory. Example usage and tests are provided for each module in the `examples` and `tests` directories, respectively.
254 changes: 254 additions & 0 deletions _docs-sources/iac/getting-started/deploying-a-module.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,254 @@
# Deploying your first module

[Modules](../overview/modules.md) allow you to define an interface to create one or many resources in the cloud or on-premise, similar to how in object oriented programming you can define a class that may have different attribute values across many instances.

This tutorial will teach you how to develop a Terraform module that deploys an AWS Lambda function. We will create the required file structure, define an AWS Lambda function and AWS IAM role as code, then plan and apply the resource in an AWS account. Then, we’ll verify the deployment by invoking the Lambda using the AWS CLI. Finally, we'll clean up the resources we create to avoid unexpected costs.

## Prerequisites
- An AWS account with permissions to create the necessary resources
- An [AWS Identity and Access Management](https://aws.amazon.com/iam/) (IAM) user or role with permissions to create AWS IAM roles and Lambda functions
- [AWS Command Line Interface](https://aws.amazon.com/cli/) (AWS CLI) installed on your local machine
- [Terraform](https://www.terraform.io) installed on your local machine

## Create the module

In this section you’ll create a Terraform module that can create an AWS Lambda function and IAM role. This module will include 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.

This module could be referenced many times to create any number of AWS Lambda functions and IAM roles.


### Create a basic file structure
First, create the directories and files that will contain the Terraform configuration.

```bash
mkdir -p terraform-aws-gw-lambda-tutorial/modules/lambda
touch terraform-aws-gw-lambda-tutorial/modules/lambda/main.tf
touch terraform-aws-gw-lambda-tutorial/modules/lambda/variables.tf
touch terraform-aws-gw-lambda-tutorial/modules/lambda/outputs.tf
```

### Define the module resources

First, define the resources that should be created by the module. This is where you define resource level blocks provided by Terraform. For this module, we need an AWS Lambda function and an IAM role that will be used by the Lambda function.

Paste the following snippet in `terraform-aws-gw-lambda/modules/lambda/main.tf`.
```hcl title="terraform-aws-gw-lambda/modules/lambda/main.tf"
resource "aws_iam_role" "lambda_role" {
name = "${var.lambda_name}-role"

assume_role_policy = <<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Effect": "Allow",
"Sid": ""
}
]
}
EOF
}

data "archive_file" "zip" {
type = "zip"

source_file = var.source_file
output_path = "${path.module}/${var.lambda_name}.zip"
}

resource "aws_lambda_function" "lambda" {
function_name = var.lambda_name
handler = var.handler
filename = data.archive_file.zip.output_path
runtime = var.runtime
memory_size = var.memory_size
timeout = var.timeout

role = aws_iam_role.lambda_role.arn
}
```

### Specify the variables for the module

Now that you’ve defined the resources you want to create, you need to list out all of 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 `terraform-aws-gw-lambda/modules/lambda/main.tf`.

Copy the following snippet into `terraform-aws-gw-lambda-tutorial/modules/lambda/variables.tf`.

```hcl title="terraform-aws-gw-lambda-tutorial/modules/lambda/variables.tf"
variable "lambda_name" {
type = string
description = "Name that will be used for the AWS Lambda function"
}

variable "handler" {
type = string
description = "The name of the handler function that will be called as the entrypoint of the lambda"
}

variable "source_file" {
type = string
description = "The path to the source file to be deployed to lambda"
}

variable "runtime" {
type = string
description = "The runtime of the Lambda. Options include go, python, ruby, etc."
}

variable "memory_size" {
type = number
description = "The amount of memory, in MB, to give to the Lambda. Defaults to 128."
default = 128
}

variable "timeout" {
type = number
description = "The amount of time, in seconds, that a lambda can execute before timing out. Defaults to 30."
default = 30
}
```

### Specify the outputs

Terraform allows you to specify values that the module will output. Outputs are convenient ways to pass values between modules when composing a service comprised of many modules.

Copy the following snippet into `terraform-aws-gw-lambda-tutorial/modules/lambda/outputs.tf`.
```hcl title="terraform-aws-gw-lambda-tutorial/modules/lambda/outputs.tf"
output "function_name" {
value = aws_lambda_function.lambda.function_name
}
```

## Reference the module

Now that you have defined a module that creates an AWS Lambda function and IAM role, you can use the module to create the resources in AWS.

### Create the basic file structure

Now that you have the module defined, you need to create files which will reference the module. 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 top level directory for the sake of simplicity.

Create a file called `main.tf`, which will contain a reference to the module, and a file called `main.py`, which will contain the Lambda function code.
```bash
touch terraform-aws-gw-lambda-tutorial/main.tf
touch terraform-aws-gw-lambda-tutorial/main.py
```

### Write the function code

Next, we’ll write a simple Python function that returns a string that will be used as the entrypoint of the AWS Lambda function. Terraform will create a zip file containing this file that will be uploaded to the Lambda function.

Copy the following to `terraform-aws-gw-lambda-tutorial/main.py`.

```py title="terraform-aws-gw-lambda-tutorial/main.py"
def lambda_handler(event, context):
return "Hello from Gruntwork!"
```

### Reference the module

Next, create a reference to the module you just created in `/modules/lambda/main.tf`. This code uses the `module` block from Terraform, which references the `/modules/lambda` directory using the `source` attribute. You can then specify values for the required variables specified in `/modules/lambdas/variables.tf`. Finally, we specify an output using the value of the `module.lambda.function_name` output created in `/modules/lambdas/outputs.tf`

```hcl title="terraform-aws-gw-lambda-tutorial/main.tf"
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = ">= 4.0.0"
}
}
}

module "lambda" {
source = "./modules/lambda"

lambda_name = "gruntwork-lambda-tutorial"
handler = "main.lambda_handler"
source_file = "${path.module}/main.py"
runtime = "python3.9"
}


output "function_name" {
value = module.lambda.function_name
}
```

## Plan and apply the module

### Run Terraform plan

Terraform will generate an execution plan using the `plan` action. The plan will show what resources Terraform determines need to be created or modified.

Running `terraform plan` is helpful when developing modules, to confirm that the Terraform code you are writing are using the correct syntax, and to confirm what resources will be created or modified when applying the module in your AWS account.


From the `terraform-aws-gw-lambda-tutorial` directory, run a plan to see what resources will be created.
```bash
terraform plan
```

Review the output of `terraform plan`, it should contain two resources — an AWS Lambda function and an AWS IAM role.


### Run Terraform apply

Terraform creates resources when using the `apply` action in a directory containing Terraform configuration files. Like with the `plan` command, Terraform will determine which resources need to be created or modified. You should expect the same resources to be created when running `apply` that are shown when running `plan`.

From the `terraform-aws-gw-lambda-tutorial` directory, run `terraform apply`. Terraform will pause to show you the resources it will create and prompt you to confirm resource creation.

```bash
terraform apply
```

Review the output to confirm it will only create an AWS Lambda function and IAM role. Then, enter `yes` to confirm resource creation. Terraform will create the resources in your AWS account. Once complete, you can invoke the AWS Lambda function following the steps in the next section.

## Invoke the created resource

Next, invoke the AWS Lambda function to verify it was created and is successfully executing the application code.

Use `terraform output` to retrieve the name of the AWS Lambda function you provisioned. This uses the outputs we added to the module in [create a module](./deploying-a-module.md#create-a-module) to retrieve the name of the Lambda function. Then, invoke the Lambda function directly using the AWS CLI, writing the response of the Lambda to a file called `lambda_output`.
```bash
#!/bin/bash
export FUNCTION_NAME=$(terraform output -raw function_name)
aws lambda invoke --function-name $FUNCTION_NAME --output json lambda_output
```

The lambda `invoke` command should return a JSON blob in response with the StatusCode of 200 and the ExecutedVersion of `$LATEST`.
```json
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
```

Inspect the contents of the `lambda_output` file, you should see a string stating `Hello from Gruntwork!`.

## Clean up

When you’ve completed the tutorial, clean up the resources you created to avoid incurring unexpected costs.

First, execute the `terraform plan -destroy` command to show the AWS resources that will be destroyed.
```bash
terraform plan -destroy
```

Review the output, it should show two resources to be destroyed — an AWS Lambda function and IAM role.

Next, execute the `destroy` command.

```bash
terraform destroy
```

Finally, when prompted, enter `yes` to confirm the resource deletion. Terraform will begin destroying the resources created as part of this tutorial.


## What’s next

Now that you’ve developed and deployed your first Terraform module, try creating another module that leverages the module you just created. For example, make your Lambda function available via a URL using an [AWS API Gateway HTTP API](../../reference/modules/terraform-aws-lambda/api-gateway-proxy/) with an AWS Lambda integration. Then, write a test using [Terratest](https://terratest.gruntwork.io/) that confirms your module creates resources as you’d expect.

Finally, consider what other resources you would create to make your modules ready to use in production. For example, you would likely need to add [metrics](../../reference/modules/terraform-aws-monitoring/metrics/metrics.md) and [alerting](../../reference/modules/terraform-aws-monitoring/alarms/alarms.md).
Loading