Update Library section (#839)

* Update Library intro

---------

Co-authored-by: docs-sourcer[bot] <99042413+docs-sourcer[bot]@users.noreply.github.com>
Co-authored-by: Eugene Kolnick <34349331+eak12913@users.noreply.github.com>
Co-authored-by: Max Moon <moon.maxwell@gmail.com>
Co-authored-by: Oreoluwa Agunbiade <agunbiade.oreoluwa@gmail.com>

Author: 5 people

_docs-sources/guides/working-with-code/using-modules.md

@@ -1,5 +1,5 @@
 ---
-sidebar_label: Using Our Modules
+sidebar_label: Using our modules
 ---
 
 # Using Gruntwork Terraform Modules

_docs-sources/iac/overview/index.md

@@ -4,24 +4,18 @@ The Gruntwork Infrastructure as Code Library (IaC Library) is a collection of re
 
 ## Modules
 
-Modules are reusable code components that are used to deploy and manage specific pieces of infrastructure. These modules encapsulate the configuration and resource definitions required to create and manage a particular component, such as a VPC, ECS cluster, or an Auto Scaling Group. For more information on modules check out the [Modules page](/iac/overview/modules/).
+Modules are "infrastructure building blocks" authored by Gruntwork and written in Terraform. They capture a singular best-practice pattern for specific pieces of infrastructure and are designed to be both limited in scope and highly reusable. They typically represent one part of a use case you want to accomplish. For example, the `vpc-flow-logs` module does not create a VPC, it only adds the VPC Flow Logs functionality to an existing VPC. To learn more, refer to [What is a module?](/iac/overview/modules/).
 
 ## Services
 
-Services in the service catalog are reusable code that combines multiple modules from the IaC Library, simplifying the deployment and management of complex infrastructure configurations. Rather than dealing with individual modules and their dependencies, users can directly deploy services tailored for a particular use case. 
-
-For more information on the service catalog check out the [Services page](/iac/overview/services/).
+Service modules are opinionated combinations of the "building block" modules described above. They are designed to be used "off the shelf" with no need to assemble a collection of “building block” modules on your own. They typically represent a full use case. For example, the `vpc` service module deploys a VPC, VPC Flow Logs, and Network ACLs. If you agree with the opinions embedded in a service module, they’re the fastest way to deploy production-grade infrastructure. To learn more, check [What is a service module?](/iac/overview/services/).
 
 ## Tools used in the IaC Library
 
-The Gruntwork IaC Library is deployed using the following tools:
+The Gruntwork IaC Library has been created using the following tools:
 
-1. [Terraform](https://www.terraform.io/). Used to define and manage most of the basic infrastructure, such as servers, databases, load balancers, and networking. The Gruntwork Service Catalog is compatible with vanilla [Terraform](https://www.terraform.io/), [Terragrunt](https://terragrunt.gruntwork.io/), [Terraform
-   Cloud](https://www.hashicorp.com/blog/announcing-terraform-cloud/), and [Terraform
-   Enterprise](https://www.terraform.io/docs/enterprise/index.html).
+1. [Terraform](https://www.terraform.io/). The Library contains nearly 300 Terraform modules that cover a range of common use cases in AWS. All library modules can be used with vanilla [Terraform](https://www.terraform.io/), [Terragrunt](https://terragrunt.gruntwork.io/), or third-party Terraform pipeline tools such as [Terraform Cloud](https://www.hashicorp.com/blog/announcing-terraform-cloud/) and [Terraform Enterprise](https://www.terraform.io/docs/enterprise/index.html).
 
-1. [Packer](https://www.packer.io/). Used to define and manage _machine images_ (e.g., VM images). The main use case is
-   to package code as [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)
-   that run on EC2 instances. Once you’ve built an AMI, you use Terraform to deploy it into AWS.
+1. [Packer](https://www.packer.io/). The Library defines _machine images_ (e.g., VM images) using Packer, where the main use case is building Amazon Machine Images (AMIs) that run on EC2 instances whose configuration is all defined in code. Once you’ve built an AMI, you can use Terraform to deploy it into AWS.
 
-1. [Terratest](https://terratest.gruntwork.io/). Used for automated testing of modules and services. 
+1. [Terratest](https://terratest.gruntwork.io/). All modules are functionally validated with automated tests written using Terratest.

_docs-sources/iac/overview/modules.md

@@ -1,9 +1,17 @@
-# What is a Module?
+# What is a module?
 
-Modules are reusable code components 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 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.
 
 Gruntwork modules are tested in AWS, in a randomly selected region, each time it changes to verify the infrastructure created matches the desired configuration.
 
+## 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.
+
+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.
+
+To see how Gruntwork gives you an off-the-shelf overall deployment with all the elements included, see [What is a service module?](services).
+
 ## When should I use a module?
 
 The Gruntwork Infrastructure as Code (IaC) Library contains [hundreds of modules](/iac/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.

_docs-sources/iac/overview/services.md

@@ -1,10 +1,10 @@
-# What is a Service?
+# 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.
 
 ## When should I use a service?
 
-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. 
+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.
 
 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.
 
@@ -32,7 +32,7 @@ The code in the `terraform-aws-service-catalog` repo is organized into three pri
       is NOT required to use the Gruntwork Service Catalog: you can alternatively use vanilla Terraform or Terraform
       Cloud / Enterprise, as described [here](https://docs.gruntwork.io/reference/services/intro/deploy-new-infrastructure#how-to-deploy-terraform-code-from-the-service-catalog).
 
-    1. Not all modules have a `for-production` example, but you can still create a production-grade configuration by 
+    1. Not all modules have a `for-production` example, but you can still create a production-grade configuration by
        using the template provided in this discussion question, [How do I use the modules in terraform-aws-service-catalog
        if there is no example?](https://github.com/gruntwork-io/knowledge-base/discussions/360#discussioncomment-25705480).
 

docs/guides/working-with-code/using-modules.md

@@ -1,5 +1,5 @@
 ---
-sidebar_label: Using Our Modules
+sidebar_label: Using our modules
 ---
 
 # Using Gruntwork Terraform Modules
@@ -770,6 +770,6 @@ Now that you have your Terraform module deployed, you can pull in updates as fol
 <!-- ##DOCS-SOURCER-START
 {
   "sourcePlugin": "local-copier",
-  "hash": "2820ee930b54e06462e6cfc030d0c03a"
+  "hash": "f0581f3813ceab8975ca94cb979285dd"
 }
 ##DOCS-SOURCER-END -->

docs/iac/overview/index.md

@@ -4,32 +4,26 @@ The Gruntwork Infrastructure as Code Library (IaC Library) is a collection of re
 
 ## Modules
 
-Modules are reusable code components that are used to deploy and manage specific pieces of infrastructure. These modules encapsulate the configuration and resource definitions required to create and manage a particular component, such as a VPC, ECS cluster, or an Auto Scaling Group. For more information on modules check out the [Modules page](/iac/overview/modules/).
+Modules are "infrastructure building blocks" authored by Gruntwork and written in Terraform. They capture a singular best-practice pattern for specific pieces of infrastructure and are designed to be both limited in scope and highly reusable. They typically represent one part of a use case you want to accomplish. For example, the `vpc-flow-logs` module does not create a VPC, it only adds the VPC Flow Logs functionality to an existing VPC. To learn more, refer to [What is a module?](/iac/overview/modules/).
 
 ## Services
 
-Services in the service catalog are reusable code that combines multiple modules from the IaC Library, simplifying the deployment and management of complex infrastructure configurations. Rather than dealing with individual modules and their dependencies, users can directly deploy services tailored for a particular use case. 
-
-For more information on the service catalog check out the [Services page](/iac/overview/services/).
+Service modules are opinionated combinations of the "building block" modules described above. They are designed to be used "off the shelf" with no need to assemble a collection of “building block” modules on your own. They typically represent a full use case. For example, the `vpc` service module deploys a VPC, VPC Flow Logs, and Network ACLs. If you agree with the opinions embedded in a service module, they’re the fastest way to deploy production-grade infrastructure. To learn more, check [What is a service module?](/iac/overview/services/).
 
 ## Tools used in the IaC Library
 
-The Gruntwork IaC Library is deployed using the following tools:
+The Gruntwork IaC Library has been created using the following tools:
 
-1. [Terraform](https://www.terraform.io/). Used to define and manage most of the basic infrastructure, such as servers, databases, load balancers, and networking. The Gruntwork Service Catalog is compatible with vanilla [Terraform](https://www.terraform.io/), [Terragrunt](https://terragrunt.gruntwork.io/), [Terraform
-   Cloud](https://www.hashicorp.com/blog/announcing-terraform-cloud/), and [Terraform
-   Enterprise](https://www.terraform.io/docs/enterprise/index.html).
+1. [Terraform](https://www.terraform.io/). The Library contains nearly 300 Terraform modules that cover a range of common use cases in AWS. All library modules can be used with vanilla [Terraform](https://www.terraform.io/), [Terragrunt](https://terragrunt.gruntwork.io/), or third-party Terraform pipeline tools such as [Terraform Cloud](https://www.hashicorp.com/blog/announcing-terraform-cloud/) and [Terraform Enterprise](https://www.terraform.io/docs/enterprise/index.html).
 
-1. [Packer](https://www.packer.io/). Used to define and manage _machine images_ (e.g., VM images). The main use case is
-   to package code as [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)
-   that run on EC2 instances. Once you’ve built an AMI, you use Terraform to deploy it into AWS.
+1. [Packer](https://www.packer.io/). The Library defines _machine images_ (e.g., VM images) using Packer, where the main use case is building Amazon Machine Images (AMIs) that run on EC2 instances whose configuration is all defined in code. Once you’ve built an AMI, you can use Terraform to deploy it into AWS.
 
-1. [Terratest](https://terratest.gruntwork.io/). Used for automated testing of modules and services. 
+1. [Terratest](https://terratest.gruntwork.io/). All modules are functionally validated with automated tests written using Terratest.
 
 
 <!-- ##DOCS-SOURCER-START
 {
   "sourcePlugin": "local-copier",
-  "hash": "74ebcd1c94d5c02b7a16bdac200b4973"
+  "hash": "eacbbc00f6d3b1f967f32a61ce8941af"
 }
 ##DOCS-SOURCER-END -->

docs/iac/overview/modules.md

@@ -1,9 +1,17 @@
-# What is a Module?
+# What is a module?
 
-Modules are reusable code components 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 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.
 
 Gruntwork modules are tested in AWS, in a randomly selected region, each time it changes to verify the infrastructure created matches the desired configuration.
 
+## 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.
+
+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.
+
+To see how Gruntwork gives you an off-the-shelf overall deployment with all the elements included, see [What is a service module?](services).
+
 ## When should I use a module?
 
 The Gruntwork Infrastructure as Code (IaC) Library contains [hundreds of modules](/iac/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.
@@ -27,6 +35,6 @@ We follow Hashicorp's [Standard Model Structure](https://developer.hashicorp.com
 <!-- ##DOCS-SOURCER-START
 {
   "sourcePlugin": "local-copier",
-  "hash": "839050279e0503f298fa8e834e649f05"
+  "hash": "990b96014078aa9754fc43c2aaa439bf"
 }
 ##DOCS-SOURCER-END -->

docs/iac/overview/services.md

@@ -1,10 +1,10 @@
-# What is a Service?
+# 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.
 
 ## When should I use a service?
 
-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. 
+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.
 
 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.
 
@@ -32,7 +32,7 @@ The code in the `terraform-aws-service-catalog` repo is organized into three pri
       is NOT required to use the Gruntwork Service Catalog: you can alternatively use vanilla Terraform or Terraform
       Cloud / Enterprise, as described [here](https://docs.gruntwork.io/reference/services/intro/deploy-new-infrastructure#how-to-deploy-terraform-code-from-the-service-catalog).
 
-    1. Not all modules have a `for-production` example, but you can still create a production-grade configuration by 
+    1. Not all modules have a `for-production` example, but you can still create a production-grade configuration by
        using the template provided in this discussion question, [How do I use the modules in terraform-aws-service-catalog
        if there is no example?](https://github.com/gruntwork-io/knowledge-base/discussions/360#discussioncomment-25705480).
 
@@ -41,6 +41,6 @@ The code in the `terraform-aws-service-catalog` repo is organized into three pri
 <!-- ##DOCS-SOURCER-START
 {
   "sourcePlugin": "local-copier",
-  "hash": "dcf834bb383d07dda3a7ea2abd0c09e4"
+  "hash": "c280cad23b062ef31658b4f0d50a2db1"
 }
 ##DOCS-SOURCER-END -->