From da3131f70ce6e4cef8d767ae06e0266a2e305263 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Thu, 15 Jun 2023 16:37:20 -0700 Subject: [PATCH 01/24] Make modules and services isomorphic. --- docs/library/overview/modules.md | 36 ++++++++++++++++++++++++------- docs/library/overview/services.md | 32 +++++++++++++++++++++------ 2 files changed, 54 insertions(+), 14 deletions(-) diff --git a/docs/library/overview/modules.md b/docs/library/overview/modules.md index 771afea165..f2caae3ea6 100644 --- a/docs/library/overview/modules.md +++ b/docs/library/overview/modules.md @@ -1,24 +1,44 @@ # What is a module? -Modules are reusable "infrastructure building blocks" that encapsulate the configuration and resource definitions needed to deploy and manage a specific piece of infrastructure, such as a VPC, ECS cluster, or Auto Scaling Group. Each module defines several AWS resources. For example, the VPC module contains resource definitions for subnets, NAT gateways, and more. Modules promote code reusability, modularity, and consistency in infrastructure deployments and can be customized in a variety of ways. +**Modules are reusable "infrastructure building blocks" that describe how to deploy and manage a specific piece of infrastructure, such as a VPC, ECS cluster, or Auto Scaling Group.** -Gruntwork modules are tested in AWS, in a randomly selected region, each time it changes to verify the infrastructure created matches the desired configuration. +Most modules are written in Terraform and define several AWS resources. ## Example -Let’s look at an example module. The [rds module](/reference/modules/terraform-aws-data-storage/rds/) creates an RDS database, the IAM roles needed to operate that database, optional read replicas, database subnet groups, and the relevant security groups. +Let’s look at an example module. The [rds module](/reference/modules/terraform-aws-data-storage/rds/) is a Terraform module that creates an RDS database, the IAM roles needed to operate that database, optional read replicas, database subnet groups, and the relevant security groups. -The module is written in Terraform and is a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup, or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves! Indeed, `backup-plan`, `backup-vault`, and `rds-proxy` can all be used in combination with the `rds` module. +The module deploys a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup (for disaster recovery), or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves! Indeed, `backup-plan`, `backup-vault`, and `rds-proxy` can all be used in combination with the `rds` module. To see how Gruntwork gives you an off-the-shelf overall deployment with all the elements included, see [What is a service module?](./services.md). -## When should I use a module? +## Modules are optimized for control -The Gruntwork Infrastructure as Code (IaC) Library contains [hundreds of modules](/library/reference/) that you can use and combine. These modules are fairly generic building blocks, so you don’t typically deploy a single module directly. Instead, you write code that combines the modules you need for a specific use case. +A "building block" module is designed to be small, narrow in scope, and highly reusable. In other words, building block modules give you _control_, but they may not give you _convenience_. That is, you can use the building block modules for all kinds of use cases (high control), but if you want to deploy a complete piece of infrastructure, you still have to do the work of assembling the right building blocks (low convenience). -For example, one module might deploy the control plane for Kubernetes and a separate module could deploy worker nodes; you may need to combine both modules together to deploy a Kubernetes cluster. +To learn how you can optimize for convenience, see [What is a service module?](./services.md). -We recommend our [Service Catalog](/library/overview/services/) for common use cases, but our full Module Catalog is available if you have a more complex use case. For a full list of modules available, refer to the [Gruntwork Infrastructure as Code Library](/library/reference/). +To learn more about the overall thought process behind building block modules versus service modules, see [Introducing: The Gruntwork Module, Service, and Architecture Catalogs](https://blog.gruntwork.io/introducing-the-gruntwork-module-service-and-architecture-catalogs-eb3a21b99f70). + +## When to use a building block module + +Building block modules are fairly generic by design, so you don’t typically deploy a single building block module directly. Instead, you write code that combines the building block modules you need for a specific use case. + +For example, one building block module might deploy the control plane for Kubernetes and a separate building block module could deploy worker nodes; you may need to combine both modules together to deploy a Kubernetes cluster. + +We recommend our [Service Catalog](/library/overview/services/) for common use cases, but our full module catalog is available if you have a more complex use case. + +## Where to find the building block modules + +The module catalog features over 250 "building block" modules spanning three major use cases: + +1. AWS foundations +2. Run my app +3. Store my data + +Each of these use cases covers one or more "SME topics" such as AWS account management, VPC/Networking, EKS, ECS, and RDS. SME topics are a first-class concept within Gruntwork, but do not yet have much visibility in the product itself. + +To browse the module catalog, see the [Library Reference](/library/reference/) and look for "Module Catalog" on the sidebar. You can also visit the list of [private Gruntwork GitHub repos](https://github.com/orgs/gruntwork-io/repositories?q=&type=private&language=&sort=). ## How modules are structured diff --git a/docs/library/overview/services.md b/docs/library/overview/services.md index 8f4149f6d9..f2e50532f4 100644 --- a/docs/library/overview/services.md +++ b/docs/library/overview/services.md @@ -1,16 +1,36 @@ # What is a service module? -The Gruntwork Service Catalog consists of a number of customizable, production-grade infrastructure-as-code services that you can use to deploy and manage your infrastructure. This includes Docker orchestration, EC2 orchestration, load balancing, networking, databases, caches, monitoring, alerting, CI/CD, secrets management, VPN, and much more. Services combine multiple modules to configure an end-to-end solution. +**Service modules are opinionated combinations of ["building block" modules](./modules). They are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf."** -## When should I use a service? +## Example -Using a service can save you time piecing together individual modules and testing that they’re correctly referencing each other. These are designed for specific use cases such as EKS and ECS clusters, VPCs with public and private subnets, and databases. +Let’s look at an example service module. The [rds service module](/reference/services/data-storage/amazon-rds) creates not only an RDS database, but also a DNS record (so you can access the database with a human-friendly name), CloudWatch alarms (to alert you if something goes wrong), a CloudWatch dashboard (so you can see RDS KPIs at a glance), and a strategy for disaster recovery. The module does this by using many "building block" modules. -For example, the `eks-cluster` service combines all the modules you need to run an EKS (Kubernetes) cluster in a typical production environment, including modules for the control plane, worker nodes, secrets management, log aggregation, alerting, and so on. +## Service modules are optimized for convenience -If you need more flexibility than our services provide, then you can combine modules from our [Module Catalog](./modules.md), your own modules, or open source modules to meet your specific use case. +Whereas "building block" modules are optimized for control, service modules are optimized for convenience. That is, a service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. If you agree with our opinion, using a service module gives you high convenience because you have a single Terraform module that does everything you need and which Gruntwork will maintain! -CIS customers also have access to the `terraform-aws-cis-service-catalog` repository to help ensure conformity to the [CIS AWS Foundations Benchmark](https://gruntwork.io/achieve-compliance/). +If you do not agree with our opinions, you can either [customize the module](/library/usage/customizing-modules), or sacrifice convenience in favor of control and build your own module, possibly out of our [building block modules](/library/overview/modules). + +## When to use a service module + +Using a service module can save you time because Gruntwork has already pieced together individual building block modules and tested that they correctly reference each other. + +For example, the [eks-cluster service module](/reference/services/app-orchestration/amazon-eks) combines all the modules you need to run an EKS (Kubernetes) cluster in a typical production environment, including modules for the control plane, worker nodes, secrets management, log aggregation, alerting, and so on. + +If you need more flexibility than our services provide, then you can combine modules from our [module catalog](./modules#where-to-find-the-building-block-modules), your own modules, or open source modules to meet your specific use case. + +CIS customers also have access to the [terraform-aws-cis-service-catalog git repo](https://github.com/gruntwork-io/terraform-aws-service-catalog) to help ensure conformity to the [CIS AWS Foundations Benchmark](https://gruntwork.io/achieve-compliance/). + +## Where to find the service modules + +The service catalog features over 25 service modules spanning three major use cases: + +1. AWS foundations +2. Run my app +3. Store my data + +To browse the service catalog, see the [Library Reference](/library/reference/) and look for "Service Catalog" in the sidebar. You can also visit the [terraform-aws-service-catalog git repo](https://github.com/gruntwork-io/terraform-aws-service-catalog). ## How services are structured From d8df4cf920695bd6629cce17b2079c9a99d8d13f Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Thu, 15 Jun 2023 16:46:57 -0700 Subject: [PATCH 02/24] Clarify how modules are updated --- docs/library/overview/modules.md | 5 +++++ docs/library/overview/services.md | 3 +++ docs/library/usage/composing-your-own-service.md | 4 ++-- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/library/overview/modules.md b/docs/library/overview/modules.md index f2caae3ea6..2823cb21c4 100644 --- a/docs/library/overview/modules.md +++ b/docs/library/overview/modules.md @@ -52,6 +52,11 @@ The code in the module repos are organized into three primary folders: We follow Hashicorp's [Standard Model Structure](https://developer.hashicorp.com/terraform/language/modules/develop/structure) for our files (`main.tf`, `variables.tf`, `outputs.tf`). In the `variables.tf` file we always put the required variables at the top of the file, followed by the optional variables. Although there are often a lot of ways to configure our modules, we set reasonable defaults and try to minimize the effort required to configure the modules to the most common use cases. +## How modules are updated + +Gruntwork brings together AWS and Terraform experts around the world who track updates from AWS, Terraform, and the DevOps community at large, along with requests from the Gruntwork customer community. We translate the most important of these updates into new features, new optimizations, and ultimately new releases. + +Check out [Gruntwork releases](/guides/stay-up-to-date/#gruntwork-releases) for a comprehensive listing of all the updates. diff --git a/docs/library/overview/services.md b/docs/library/overview/services.md index bb10f175c0..dec94fe4c5 100644 --- a/docs/library/overview/services.md +++ b/docs/library/overview/services.md @@ -65,6 +65,6 @@ When [building block modules are updated](/library/overview/modules#how-modules- diff --git a/docs/library/usage/composing-your-own-service.md b/docs/library/usage/composing-your-own-service.md index 8a39838b20..779ecda3dd 100644 --- a/docs/library/usage/composing-your-own-service.md +++ b/docs/library/usage/composing-your-own-service.md @@ -194,6 +194,6 @@ Now that you've defined your own service, consider how you would make this modul diff --git a/docs/library/usage/contributing.md b/docs/library/usage/contributing.md index ab23af8f76..ccdf754281 100644 --- a/docs/library/usage/contributing.md +++ b/docs/library/usage/contributing.md @@ -61,6 +61,6 @@ code and release a new version. From a279b7dc555416852e30829f286897674ca8f950 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Thu, 29 Jun 2023 11:25:39 -0700 Subject: [PATCH 05/24] Update _docs-sources/library/usage/contributing.md Co-authored-by: Max Moon --- _docs-sources/library/usage/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/usage/contributing.md b/_docs-sources/library/usage/contributing.md index 1cdaad717a..ea18b17b46 100644 --- a/_docs-sources/library/usage/contributing.md +++ b/_docs-sources/library/usage/contributing.md @@ -42,7 +42,7 @@ the tests locally. ### Update the code -At this point, you can now make your code changes and use your new test case to verify that everything is working. +At this point, you can make your code changes and use your new test case to verify that everything is working. ### Create a pull request From a4dcb6fa2a321e9c387ba96d12885eb654496970 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:00:19 -0700 Subject: [PATCH 06/24] Update _docs-sources/library/usage/contributing.md Co-authored-by: Max Moon --- _docs-sources/library/usage/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/usage/contributing.md b/_docs-sources/library/usage/contributing.md index ea18b17b46..d89beced68 100644 --- a/_docs-sources/library/usage/contributing.md +++ b/_docs-sources/library/usage/contributing.md @@ -18,7 +18,7 @@ If you're thinking of adding a new feature, before starting any work, we recomme questions and get feedback from the maintainers and the community before you sink a lot of time into writing (possibly the wrong) code. If there is anything you’re unsure about, just ask! -If you're submitting a simple change such as a new variable or new output value, it may be worth opening a pull request directly, as described below. The key point is that we want to minimize the risk that you invest time in something we ultimately can't use. +If you're submitting a simple change such as a new variable or new output value, it may be worth opening a pull request directly, as described below. ## Proceed to a pull request From 588383227e9fe008b7da90fb3f5649c500fd7658 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:01:31 -0700 Subject: [PATCH 07/24] Update _docs-sources/library/overview/services.md Co-authored-by: Max Moon --- _docs-sources/library/overview/services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/services.md b/_docs-sources/library/overview/services.md index 4d8b2235cf..a22eba343c 100644 --- a/_docs-sources/library/overview/services.md +++ b/_docs-sources/library/overview/services.md @@ -1,6 +1,6 @@ # What is a service module? -**Service modules are opinionated combinations of ["building block" modules](./modules). They are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf."** +Service modules are combinations of [modules](./modules) covering a wide variety of use cases, including CI/CD, networking, container orchestration (EKS, ECS), and more. Service modules are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf." ## Example From 783f759df0b7e672c5905a6a1f20e784880eadc0 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:02:05 -0700 Subject: [PATCH 08/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 9ecfc54525..da5bb2bad4 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -1,6 +1,6 @@ # What is a module? -**Modules are reusable "infrastructure building blocks" that describe how to deploy and manage a specific piece of infrastructure, such as a VPC, ECS cluster, or Auto Scaling Group.** +Modules are reusable "infrastructure building blocks" that describe how to deploy and manage a specific piece of infrastructure, such as a VPC, ECS cluster, or Auto Scaling Group. Most modules are written in Terraform and define several AWS resources. From 54c7c0a705802bd656e58b914ad000e08b22640c Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:07:52 -0700 Subject: [PATCH 09/24] Clean up service example --- docs/library/overview/services.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/library/overview/services.md b/docs/library/overview/services.md index dec94fe4c5..0ab70f602a 100644 --- a/docs/library/overview/services.md +++ b/docs/library/overview/services.md @@ -4,7 +4,9 @@ ## Example -Let’s look at an example service module. The [rds service module](/reference/services/data-storage/amazon-rds) creates not only an RDS database, but also a DNS record (so you can access the database with a human-friendly name), CloudWatch alarms (to alert you if something goes wrong), a CloudWatch dashboard (so you can see RDS KPIs at a glance), and a strategy for disaster recovery. The module does this by using many "building block" modules. +Let’s look at an example service module. The [`rds` service module](/reference/services/data-storage/amazon-rds) creates not only an RDS database, but also a DNS record in Amazon Route53, CloudWatch alarms, a CloudWatch dashboard, and scheduled snapshots of the database, all using a combination of "building block" modules. + +After applying, you will have an RDS instance that you can access via a human-friendly name, alarms to alert you if something goes wrong, a dashboard for viewing RDS KPIs, and a strategy for disaster recovery. ## Service modules are optimized for convenience From 6c9cd217d26185792e3e93918a4f5ca810ffa838 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:08:30 -0700 Subject: [PATCH 10/24] Update _docs-sources/library/overview/services.md Co-authored-by: Max Moon --- _docs-sources/library/overview/services.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/services.md b/_docs-sources/library/overview/services.md index a22eba343c..447c0261ee 100644 --- a/_docs-sources/library/overview/services.md +++ b/_docs-sources/library/overview/services.md @@ -8,7 +8,9 @@ Let’s look at an example service module. The [rds service module](/reference/s ## Service modules are optimized for convenience -Whereas "building block" modules are optimized for control, service modules are optimized for convenience. That is, a service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. If you agree with our opinion, using a service module gives you high convenience because you have a single Terraform module that does everything you need and which Gruntwork will maintain! +Whereas "building block" modules are optimized for control, service modules are optimized for convenience. + +A service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. Using a service module gives you the convenience of a single Terraform module that does everything you need, with Gruntwork maintaining the code. If you do not agree with our opinions, you can either [customize the module](/library/usage/customizing-modules), or sacrifice convenience in favor of control and build your own module, possibly out of our [building block modules](/library/overview/modules). From 2a6c6afd203f3b9792cc442869ba87c5c9e5e3d3 Mon Sep 17 00:00:00 2001 From: "docs-sourcer[bot]" <99042413+docs-sourcer[bot]@users.noreply.github.com> Date: Wed, 12 Jul 2023 01:08:34 +0000 Subject: [PATCH 11/24] Updated `_docs-sources` with this contribution and regenerated output. --- _docs-sources/library/overview/services.md | 10 +++++----- docs/library/overview/services.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/_docs-sources/library/overview/services.md b/_docs-sources/library/overview/services.md index 447c0261ee..9a4426acdf 100644 --- a/_docs-sources/library/overview/services.md +++ b/_docs-sources/library/overview/services.md @@ -1,16 +1,16 @@ # What is a service module? -Service modules are combinations of [modules](./modules) covering a wide variety of use cases, including CI/CD, networking, container orchestration (EKS, ECS), and more. Service modules are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf." +**Service modules are opinionated combinations of ["building block" modules](./modules). They are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf."** ## Example -Let’s look at an example service module. The [rds service module](/reference/services/data-storage/amazon-rds) creates not only an RDS database, but also a DNS record (so you can access the database with a human-friendly name), CloudWatch alarms (to alert you if something goes wrong), a CloudWatch dashboard (so you can see RDS KPIs at a glance), and a strategy for disaster recovery. The module does this by using many "building block" modules. +Let’s look at an example service module. The [`rds` service module](/reference/services/data-storage/amazon-rds) creates not only an RDS database, but also a DNS record in Amazon Route53, CloudWatch alarms, a CloudWatch dashboard, and scheduled snapshots of the database, all using a combination of "building block" modules. -## Service modules are optimized for convenience +After applying, you will have an RDS instance that you can access via a human-friendly name, alarms to alert you if something goes wrong, a dashboard for viewing RDS KPIs, and a strategy for disaster recovery. -Whereas "building block" modules are optimized for control, service modules are optimized for convenience. +## Service modules are optimized for convenience -A service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. Using a service module gives you the convenience of a single Terraform module that does everything you need, with Gruntwork maintaining the code. +Whereas "building block" modules are optimized for control, service modules are optimized for convenience. That is, a service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. If you agree with our opinion, using a service module gives you high convenience because you have a single Terraform module that does everything you need and which Gruntwork will maintain! If you do not agree with our opinions, you can either [customize the module](/library/usage/customizing-modules), or sacrifice convenience in favor of control and build your own module, possibly out of our [building block modules](/library/overview/modules). diff --git a/docs/library/overview/services.md b/docs/library/overview/services.md index 0ab70f602a..223622fe47 100644 --- a/docs/library/overview/services.md +++ b/docs/library/overview/services.md @@ -67,6 +67,6 @@ When [building block modules are updated](/library/overview/modules#how-modules- From 12ba2ff6404bdf2d0c0f33cd132d198a71f46e28 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:08:54 -0700 Subject: [PATCH 12/24] Update _docs-sources/library/overview/services.md Co-authored-by: Max Moon --- _docs-sources/library/overview/services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/services.md b/_docs-sources/library/overview/services.md index 9a4426acdf..c685b1e14f 100644 --- a/_docs-sources/library/overview/services.md +++ b/_docs-sources/library/overview/services.md @@ -29,7 +29,7 @@ CIS customers also have access to the [terraform-aws-cis-service-catalog git rep The service catalog features over 25 service modules spanning three major use cases: 1. AWS foundations -2. Run my app +2. Running applications 3. Store my data To browse the service catalog, see the [Library Reference](/library/reference/) and look for "Service Catalog" in the sidebar. You can also visit the [terraform-aws-service-catalog git repo](https://github.com/gruntwork-io/terraform-aws-service-catalog). From bca0fc5bc3bdca1448c59c244ebbafe808c595f2 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:09:01 -0700 Subject: [PATCH 13/24] Update _docs-sources/library/overview/services.md Co-authored-by: Max Moon --- _docs-sources/library/overview/services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/services.md b/_docs-sources/library/overview/services.md index c685b1e14f..f6db2ade16 100644 --- a/_docs-sources/library/overview/services.md +++ b/_docs-sources/library/overview/services.md @@ -30,7 +30,7 @@ The service catalog features over 25 service modules spanning three major use ca 1. AWS foundations 2. Running applications -3. Store my data +3. Storing data To browse the service catalog, see the [Library Reference](/library/reference/) and look for "Service Catalog" in the sidebar. You can also visit the [terraform-aws-service-catalog git repo](https://github.com/gruntwork-io/terraform-aws-service-catalog). From 660483dc7064aeaa7cb250a50e2065dc1ef5bb3f Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:09:43 -0700 Subject: [PATCH 14/24] Update _docs-sources/library/overview/services.md Co-authored-by: Max Moon --- _docs-sources/library/overview/services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/services.md b/_docs-sources/library/overview/services.md index f6db2ade16..9adeff3c74 100644 --- a/_docs-sources/library/overview/services.md +++ b/_docs-sources/library/overview/services.md @@ -62,4 +62,4 @@ The code in the `terraform-aws-service-catalog` repo is organized into three pri ## How service modules are updated -When [building block modules are updated](/library/overview/modules#how-modules-are-updated), we propagate those updates to the service catalog. Keep in mind that there is sometimes a delay between when a "building block" module is updated, and when that update is reflected in the service catalog. \ No newline at end of file +When [building block modules are updated](/library/overview/modules#how-modules-are-updated), we propagate those updates to the service catalog. Keep in mind that there is sometimes a delay between when a "building block" module is updated and when that update is reflected in the service catalog. \ No newline at end of file From 299c8f09c710575dfaacb4d7c580d35707c4ded4 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:10:23 -0700 Subject: [PATCH 15/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index da5bb2bad4..9201a450f6 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -8,7 +8,7 @@ Most modules are written in Terraform and define several AWS resources. Let’s look at an example module. The [rds module](/reference/modules/terraform-aws-data-storage/rds/) is a Terraform module that creates an RDS database, the IAM roles needed to operate that database, optional read replicas, database subnet groups, and the relevant security groups. -The module deploys a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup (for disaster recovery), or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves! Indeed, `backup-plan`, `backup-vault`, and `rds-proxy` can all be used in combination with the `rds` module. +The module deploys a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup (for disaster recovery), or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves. Gruntwork has modules for `backup-plan`, `backup-vault`, and `rds-proxy` can all be used in combination with the `rds` module. To see how Gruntwork gives you an off-the-shelf overall deployment with all the elements included, see [What is a service module?](./services.md). From c44338dd940b1f2ba3d9c1c7cbf69a18d1e0537f Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:12:41 -0700 Subject: [PATCH 16/24] Update modules.md --- _docs-sources/library/overview/modules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 9201a450f6..34c6288cc2 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -8,7 +8,7 @@ Most modules are written in Terraform and define several AWS resources. Let’s look at an example module. The [rds module](/reference/modules/terraform-aws-data-storage/rds/) is a Terraform module that creates an RDS database, the IAM roles needed to operate that database, optional read replicas, database subnet groups, and the relevant security groups. -The module deploys a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup (for disaster recovery), or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves. Gruntwork has modules for `backup-plan`, `backup-vault`, and `rds-proxy` can all be used in combination with the `rds` module. +The module deploys a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup (for disaster recovery), or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves. Gruntwork has modules for `backup-plan`, `backup-vault`, and `rds-proxy` that can all be used in combination with the `rds` module. To see how Gruntwork gives you an off-the-shelf overall deployment with all the elements included, see [What is a service module?](./services.md). @@ -56,4 +56,4 @@ We follow Hashicorp's [Standard Model Structure](https://developer.hashicorp.com Gruntwork brings together AWS and Terraform experts around the world who track updates from AWS, Terraform, and the DevOps community at large, along with requests from the Gruntwork customer community. We translate the most important of these updates into new features, new optimizations, and ultimately new releases. -Check out [Gruntwork releases](/guides/stay-up-to-date/#gruntwork-releases) for a comprehensive listing of all the updates. \ No newline at end of file +Check out [Gruntwork releases](/guides/stay-up-to-date/#gruntwork-releases) for a comprehensive listing of all the updates. From 4bb8c16468029fcc66e824d0d93b9fb908c7c797 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:14:26 -0700 Subject: [PATCH 17/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 34c6288cc2..3eb63aaef0 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -14,7 +14,7 @@ To see how Gruntwork gives you an off-the-shelf overall deployment with all the ## Modules are optimized for control -A "building block" module is designed to be small, narrow in scope, and highly reusable. In other words, building block modules give you _control_, but they may not give you _convenience_. That is, you can use the building block modules for all kinds of use cases (high control), but if you want to deploy a complete piece of infrastructure, you still have to do the work of assembling the right building blocks (low convenience). +A module is designed to be small, narrow in scope, and highly reusable, like a building block. Modules give you _control_, but they may not give you _convenience_. You can use the building block modules for all kinds of use cases (high control), but if you want to deploy a complete piece of infrastructure, you still have to do the work of assembling the right modules (low convenience). To learn how you can optimize for convenience, see [What is a service module?](./services.md). From de82bf780d1a21b0dfa1c6ae6d49e49a7d980e7a Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:14:35 -0700 Subject: [PATCH 18/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 3eb63aaef0..99d905532a 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -22,7 +22,7 @@ To learn more about the overall thought process behind building block modules ve ## When to use a building block module -Building block modules are fairly generic by design, so you don’t typically deploy a single building block module directly. Instead, you write code that combines the building block modules you need for a specific use case. +Building block modules are fairly generic by design, so you won't typically deploy a single building block module directly. Instead, you write code that combines the building block modules you need for a specific use case. For example, one building block module might deploy the control plane for Kubernetes and a separate building block module could deploy worker nodes; you may need to combine both modules together to deploy a Kubernetes cluster. From 76ccf33b2dc9bba4b77066f049b833566dff2f40 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:15:15 -0700 Subject: [PATCH 19/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 99d905532a..9668ef87f3 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -24,7 +24,7 @@ To learn more about the overall thought process behind building block modules ve Building block modules are fairly generic by design, so you won't typically deploy a single building block module directly. Instead, you write code that combines the building block modules you need for a specific use case. -For example, one building block module might deploy the control plane for Kubernetes and a separate building block module could deploy worker nodes; you may need to combine both modules together to deploy a Kubernetes cluster. +For example, one module might deploy the control plane for Kubernetes and a separate module could deploy worker nodes; you may need to combine both modules together to deploy a Kubernetes cluster. We recommend our [Service Catalog](/library/overview/services/) for common use cases, but our full module catalog is available if you have a more complex use case. From 663ac418ca7d4595906c928c112b73b56cc04dbd Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:15:22 -0700 Subject: [PATCH 20/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 9668ef87f3..406ddbbed4 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -33,7 +33,7 @@ We recommend our [Service Catalog](/library/overview/services/) for common use c The module catalog features over 250 "building block" modules spanning three major use cases: 1. AWS foundations -2. Run my app +2. Running applications 3. Store my data Each of these use cases covers one or more "SME topics" such as AWS account management, VPC/Networking, EKS, ECS, and RDS. SME topics are a first-class concept within Gruntwork, but do not yet have much visibility in the product itself. From a6bda983a6693140a1264dc69c1f8fc515b79b71 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:15:28 -0700 Subject: [PATCH 21/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 406ddbbed4..50847aa4e6 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -34,7 +34,7 @@ The module catalog features over 250 "building block" modules spanning three maj 1. AWS foundations 2. Running applications -3. Store my data +3. Storing data Each of these use cases covers one or more "SME topics" such as AWS account management, VPC/Networking, EKS, ECS, and RDS. SME topics are a first-class concept within Gruntwork, but do not yet have much visibility in the product itself. From 1811e41c8b8f3741e0e4109f2a961c09d2aa4a17 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:15:48 -0700 Subject: [PATCH 22/24] Update _docs-sources/library/overview/modules.md Co-authored-by: Max Moon --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 50847aa4e6..f3520d73fc 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -36,7 +36,7 @@ The module catalog features over 250 "building block" modules spanning three maj 2. Running applications 3. Storing data -Each of these use cases covers one or more "SME topics" such as AWS account management, VPC/Networking, EKS, ECS, and RDS. SME topics are a first-class concept within Gruntwork, but do not yet have much visibility in the product itself. +Each of these use cases covers one or more Subject Matter Expert (SME) topics such as AWS account management, VPC/Networking, EKS, ECS, and RDS. SME topics are a first-class concept within Gruntwork, but do not have much visibility in the product itself at this time. To browse the module catalog, see the [Library Reference](/library/reference/) and look for "Module Catalog" on the sidebar. You can also visit the list of [private Gruntwork GitHub repos](https://github.com/orgs/gruntwork-io/repositories?q=&type=private&language=&sort=). From 9fcccdcc5de1280991cd3510e6ff81731a20c6dd Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:16:29 -0700 Subject: [PATCH 23/24] Update modules.md --- _docs-sources/library/overview/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs-sources/library/overview/modules.md b/_docs-sources/library/overview/modules.md index 34c6288cc2..75e04a51db 100644 --- a/_docs-sources/library/overview/modules.md +++ b/_docs-sources/library/overview/modules.md @@ -56,4 +56,4 @@ We follow Hashicorp's [Standard Model Structure](https://developer.hashicorp.com Gruntwork brings together AWS and Terraform experts around the world who track updates from AWS, Terraform, and the DevOps community at large, along with requests from the Gruntwork customer community. We translate the most important of these updates into new features, new optimizations, and ultimately new releases. -Check out [Gruntwork releases](/guides/stay-up-to-date/#gruntwork-releases) for a comprehensive listing of all the updates. +Refer to [Gruntwork releases](/guides/stay-up-to-date/#gruntwork-releases) for a comprehensive listing of all the updates. From fa660dff6ecef0034a6718777050766a71c7b627 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 11 Jul 2023 18:23:46 -0700 Subject: [PATCH 24/24] Update services.md --- _docs-sources/library/overview/services.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/_docs-sources/library/overview/services.md b/_docs-sources/library/overview/services.md index 9adeff3c74..effadd05e3 100644 --- a/_docs-sources/library/overview/services.md +++ b/_docs-sources/library/overview/services.md @@ -1,6 +1,6 @@ # What is a service module? -**Service modules are opinionated combinations of ["building block" modules](./modules). They are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf."** +Service modules are combinations of [modules](./modules) covering a wide variety of use cases, including CI/CD, networking, container orchestration (EKS, ECS), and more. Service modules are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf." ## Example @@ -10,7 +10,9 @@ After applying, you will have an RDS instance that you can access via a human-fr ## Service modules are optimized for convenience -Whereas "building block" modules are optimized for control, service modules are optimized for convenience. That is, a service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. If you agree with our opinion, using a service module gives you high convenience because you have a single Terraform module that does everything you need and which Gruntwork will maintain! +Whereas "building block" modules are optimized for control, service modules are optimized for convenience. + +A service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. Using a service module gives you the convenience of a single Terraform module that does everything you need, with Gruntwork maintaining the code. If you do not agree with our opinions, you can either [customize the module](/library/usage/customizing-modules), or sacrifice convenience in favor of control and build your own module, possibly out of our [building block modules](/library/overview/modules). @@ -62,4 +64,4 @@ The code in the `terraform-aws-service-catalog` repo is organized into three pri ## How service modules are updated -When [building block modules are updated](/library/overview/modules#how-modules-are-updated), we propagate those updates to the service catalog. Keep in mind that there is sometimes a delay between when a "building block" module is updated and when that update is reflected in the service catalog. \ No newline at end of file +When [building block modules are updated](/library/overview/modules#how-modules-are-updated), we propagate those updates to the service catalog. Keep in mind that there is sometimes a delay between when a "building block" module is updated and when that update is reflected in the service catalog.