Skip to main content

What is a service module?

Service modules are combinations of 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​

Let’s look at an example service module. The rds service module 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​

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, or sacrifice convenience in favor of control and build your own module, possibly out of our building block 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 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, 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 to help ensure conformity to the CIS AWS Foundations Benchmark.

Where to find the service modules​

The service catalog features over 25 service modules spanning three major use cases:

  1. AWS foundations
  2. Running applications
  3. Storing data

To browse the service catalog, see the Library Reference and look for "Service Catalog" in the sidebar. You can also visit the terraform-aws-service-catalog git repo.

How services are structured​

The code in the terraform-aws-service-catalog repo is organized into three primary folders:

  1. modules: The core implementation code of this repo. All the services that you will use and deploy are defined within, such as the EKS cluster service in modules/services/eks-cluster.

  2. examples: Sample code that shows how to use the services in the modules folder and allows you to try the services out without having to write any code: you cd into one of the folders, follow a few steps in the README (e.g., run terraform apply), and you’ll have fully working infrastructure up and running. In other words, this is executable documentation. Note that the examples folder contains two sub-folders:

    1. for-learning-and-testing: Example code that is optimized for learning, experimenting, and testing, but not direct production usage. Most of these examples use Terraform directly to make it easy to fill in dependencies that are convenient for testing, but not necessarily those you’d use in production: e.g., default VPCs or mock database URLs.

    2. for-production: Example code optimized for direct usage in production. This is code from the Gruntwork Reference Architecture, and it shows you how we build an end-to-end, integrated tech stack on top of the Gruntwork Service Catalog. To keep the code DRY and manage dependencies between modules, the code is deployed using Terragrunt. However, Terragrunt is NOT required to use the Gruntwork Service Catalog: you can alternatively use vanilla Terraform or Terraform Cloud / Enterprise, as described here.

    3. 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?.

  3. test: Automated tests for the code in modules and examples.

How service modules are updated​

When building block 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.