Motivation

A facade module simplifies and standardizes a common use case for an infrastructure resource. The stack code the uses a facade module should be simpler and easier to read. Improvements to the quality of the module code are rapidly available to all of the stacks which use it.

Applicability

Facade modules work best for simple use cases, usually involving a low-level infrastructure resource.

Consequences

A facade module limits how you can use the underlying infrastructure resource. Doing this can be useful, simplifying options and standardizing around good quality implementations. However, it can also reduce flexibility.

A module is an extra layer of code between the stack code and the code that directly specifies the infrastructure resources. This extra layer adds at least some overhead to maintaining, debugging, and improving code. It can also make it harder to understand the stack code.

Implementation

Implementing a facade module generally involves specifying an infrastructure resource with a number of hard-coded values, and a small number of values that are passed through from the code that uses the module.

Related patterns

An anemic module (“Antipattern: Anemic Module”) is a facade module that doesn’t hide much, so adds complexity without adding much value. A domain entity module (“Pattern: Domain Entity Module”) is similar to a facade, in that it presents a simplified interface to the code that uses it. But a domain entity combines multiple lower-level elements to present a single higher-level entity to the calling code. In contrast, a facade module is a more direct mapping of a single element.

Also Known As

Value-Free Wrapper, Pass-Through Module, Obfuscator Module.

Motivation

Sometimes people write this kind of module aiming to follow the DRY (Don’t Repeat Yourself) principle. They see that code that defines a common infrastructure element, such as a virtual server, load balancer, or security group, is used in multiple places in the codebase. So they create a module that declares that element type once and use that everywhere. But because the elements are being used differently in different parts of the code, they need to expose a large number of parameters in their module. The result is that the code that uses the module is no simpler than directly using the stack tool’s code. The codebase still has repeated code, only now it’s repeated use of the module.

Applicability

Nobody intentionally writes an anemic module. You may debate whether a given module is anemic or is a facade, but the debate itself is useful. You should consider whether a module adds real value and, if not, then refactor it into code that uses the stack language directly.

Consequences

Writing, using, and maintaining module code rather than directly using the constructs provided by your stack tool adds overhead. It makes your stack code more difficult to understand, especially for people who know the stack tool but are new to your codebase. It adds more code to maintain, usually with separate versioning and release. You can end up with different versions of a module being used by different stacks, causing people to waste time and energy managing releases, upgrades, and testing.

Implementation

If a module does more than pass parameters, but still presents too many parameters to code that uses it, you might consider splitting it into multiple modules. Doing this makes sense when there are a few common but different use cases for the infrastructure element the module defines. For example, rather than a single module for defining firewall rules, you may want one module to define a firewall rule for public HTTPS traffic, another for internal HTTPS traffic, and a third for SSH traffic. Each of these may need fewer parameters than a single module that handles multiple protocols and scenarios.

Related patterns

Some anemic modules are “Pattern: Facade Module” that grew out of control. Others are part of an “Antipattern: Obfuscation Layer”. It may also be a “Pattern: Domain Entity Module” that maps a bit too directly to a single underlying infrastructure element, rather than to a useful combination of elements.

Motivation

Infrastructure stack languages provide language constructs that map directly to resources and services provided by infrastructure platforms (the things I described in Chapter 3). Teams combine these low-level constructs into higher-level constructs to serve a particular purpose, such as hosting a Java application or running a data pipeline.

It can take a fair bit of low-level infrastructure code to define all of the pieces needed to meet that high-level purpose. As I described above, to create the infrastructure to run a Java application, you may need to write code for a cluster of virtual servers, for a load balancer, for a database instance, and for firewall rules. That’s a lot of code. Although you may write modules so you can share code for each low-level resource, if you need multiple different applications with similar infrastructure, it would be useful to share code at this higher level as well.

Applicability

A domain entity module is useful for things that are fairly complex to implement, and that are used in pretty much the same way in multiple places in your system. Don’t create a domain entity module that you only use once. And don’t create one of these modules for multiple instances of the same thing, when each instance is significantly different. The first case is a one-shot module (“Antipattern: One-shot Module”), the second risks becoming a spaghetti module (“Antipattern: Spaghetti Module”).

For example, you may run multiple application servers that use the same stack-operating system, application language, and application deployment method. This is a candidate for a domain entity module.

As a counter-example, you may have multiple application servers, but some run Windows, some run Linux. One runs a stateless PHP application, another runs a Java application on Tomcat with a MySQL database, while a third hosts a .Net application that uses message queues to integrate with other applications. Although all three of these are application servers, their implementation is quite different. Any module that can create a suitable infrastructure stack for all of these is unlikely to have a clean design and implementation.

Implementation

On a concrete level, implementing a domain entity model is a matter of writing the code for a related grouping of infrastructure in a single module. But the best way to create a high-quality codebase that is easy for people to learn and maintain is to take a design-led approach.

I recommend drawing from lessons learned in software architecture and design. The domain entity module pattern derives from Domain Driven Design (DDD)⁵, which creates a conceptual model for the business domain of a software system, and uses that to drive the design of the system itself. Infrastructure, especially one designed and built as software, can be seen as a domain in its own right. The domain is building, delivering, and running software.

A particularly powerful approach is for an organization to use DDD to design the architecture for the business software, and then extend the domain to include the systems and services used for building and running that software.

The code to implement a Java application server might look like Example 6-9. This example creates and assembles three different resources: a DNS entry, which points to a load balancer, which routes traffic to a server cluster.

declare module: java-application-infrastructure

  dns_entry:
    id: "${APP_NAME}-hostname"
    record_type: "A"
    hostname: "${APP_NAME}.foodspin.io"
    ip_address: {$load_balancer.ip_address}

  server_cluster:
    id: "${APP_NAME}-cluster"
    min_size: 1
    max_size: 3
    each_server_node:
      source_image: base_linux
      memory: 4GB
      provision:
        tool: servermaker
        role: appserver
        parameters:
          app_package: "${APP_NAME}-${APP_VERSION}.war"
          app_repository: "repository.foodspin.io"

  load_balancer:
    protocol: https
    target:
      type: server_cluster
      target_id: "${APP_NAME}-cluster"

Code to provision a stack that runs a search application using this module might look like this:

use module: java-application-infrastructure
  app_name: foodspin_search_app
  app_version: 1.23

Related patterns

If you find that some stack projects have very little code other than importing a single module, you might consider putting the code directly into the stack project. Reusing code in the form of an entire stack, rather than a module, is the reusable stack pattern (“Pattern: Reusable Stack”). In some cases, having the entire stack code in a module is deliberate, as in the wrapper stack pattern (“Pattern: Wrapper Stack”).

A facade module (“Pattern: Facade Module”) is like a domain entity module that only creates a single low-level infrastructure element. A spaghetti module (“Antipattern: Spaghetti Module”) is similar to a domain entity module but has too many different options.

Also Known As

Swiss Army module.

Motivation

As with other antipatterns, people create a spaghetti module by accident, often over time. You may create a facade module (“Pattern: Facade Module”) for a common infrastructure element, such as a server, that grows so that it can create radically different types of servers. Or you may create a domain entity module (“Pattern: Domain Entity Module”) for an application’s infrastructure. But then you find that the module needs to optionally include a variety of elements, such as databases, message queues, load balancers, and public Internet gateways, depending on the application that runs on it.

Consequences

A module that does too many things is less maintainable than one with a tighter scope. The more things a module does, and the more variations there are in the infrastructure that it can create, the harder it is to change it without breaking something. These modules are harder to test. As I explain in a later chapter (Chapter 9), better-designed code is easier to test, so if you’re struggling to write automated tests and build pipelines to test the module in isolation, It’s a sign that you may have a spaghetti module.

Implementation

A spaghetti module’s code often contains conditionals, that apply different specifications in different situations. For example, a database cluster module might take a parameter to choose which database to provision.

When you realize you have a spaghetti module on your hands, you should refactor it. Often, you can split it into different modules, each with a more focused remit. For example, you might decompose your single application infrastructure module into different modules for different parts of the application’s infrastructure. An example of a stack that uses decomposed modules in this way, rather than using the spaghetti module from the earlier example (Example 6-10) might look like this:

use module: java-application-servers
  name: burgerbarn_appserver
  application: "shopping_app"
  application_version: "4.20"
  network_segment: customer_subnet
  server_configuration:
    database_connection: ${module.mysql-database.outputs.connection_string}

use module: mysql-database
  cluster_minimum: 1
  cluster_maximum: 3
  allow_connections_from: customer_subnet

Each of the modules is smaller, simpler, and so easier to maintain and tested than the original spaghetti module.

Related patterns

A spaghetti module is often a domain entity module (“Pattern: Domain Entity Module”) gone wrong.

Also Known As

Abstraction layer, portability layer, in-house infrastructure model.

Motivation

An obfuscation layer is usually intended to simplify or standardize implementation. A team might create a library of modules as an in-house model for building infrastructure. Sometimes the intention is for people to write stack code without needing to learn the stack tool itself. In other cases, the layer tries to abstract the specifics of the infrastructure platform so that code can be written once and used across multiple platforms.

Consequences

If your team uses a heavily customized model for infrastructure code, then it becomes a barrier to new people joining your team. Even someone who knows the stack tools you use has a steep learning curve to understand your special language. An in-house obfuscation layer tends to be inflexible, forcing people to either work around its limitations or spend time making changes to the obfuscation layer itself. Either way, people waste time creating and maintaining extra code.

People, especially managers and hands-off architects⁶, often overestimate the benefit of hiding an underlying platform or tools from people writing infrastructure code. I have yet to see a cloud abstraction layer that adds noticeable value, or that avoids adding cost and complexity. Most fail at both.

Related patterns

Domain entity modules (“Pattern: Domain Entity Module”) may be used to create an obfuscation layer at a higher level, while facade modules (“Pattern: Facade Module”) would be used to obfuscate lower-level resources. If each module in the layer handles multiple platforms, they are probably spaghetti modules (“Antipattern: Spaghetti Module”).

Motivation

People usually create one-shot modules as a way to organize the code in a project.

Applicability

If a stack project includes enough code that it becomes difficult to navigate, you have a few options. Splitting the stack into modules is one approach. If the stack is conceptually doing too much, it might be better to divide it into multiple stacks, using an appropriate stack structural pattern (see “Patterns and antipatterns for structuring stacks”). Otherwise, merely organizing code into different files and, if necessary, different folders, can make it easier to navigate and understand the codebase without the overhead of the other options.

Consequences

Organizing the code into modules adds the overhead of declaring the module and passing parameters. You add even more complexity if you manage the module code separately, with separate versioning. This overhead is worthwhile when you share code across multiple stack projects. The benefits of code reuse make up for the added time and energy of maintaining a separate module. Paying that cost when you’re not using the benefit is a waste.

Related patterns

A one-shot module may map closely to lower-level infrastructure elements, like a facade module (“Pattern: Facade Module”), or to a higher-level entity, like a domain entity module (“Pattern: Domain Entity Module”).