Skip to content

Commit abb344d

Browse files
ZachGoldbergoredavids
ZachGoldberg
and
oredavids
authored
DEV-675 - IAC Module concept / document (#2214)
* WIP: IAC Module concept / document * Add diagram * parallel style * move xml file to static so its not spellchecked * actually fix remaining spell errors * Update docs/2.0/docs/overview/concepts/iac-modules.md Co-authored-by: Oreoluwa Agunbiade <[email protected]> * Update docs/2.0/docs/overview/concepts/iac-modules.md Co-authored-by: Oreoluwa Agunbiade <[email protected]> * Update iac-modules.md * Update iac-modules.md --------- Co-authored-by: Oreoluwa Agunbiade <[email protected]>
1 parent 1ce80a4 commit abb344d

File tree

5 files changed

+109
-1
lines changed

5 files changed

+109
-1
lines changed

‎custom-dictionary.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,5 @@ keypair
4343
mimecast
4444
slugified
4545
dlist
46-
DEPENDENCYID
46+
DEPENDENCYID
47+
MTTR

‎docs/2.0/docs/overview/concepts/iac-modules.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Leveraging Infrastructure as Code (IaC) Modules for Efficiency and Reliability
2+
By understanding the different levels of abstraction in IaC and how modules fit into the broader picture, you can improve governance, documentation, MTTR (mean time to recovery), enhance consistency, and increase the reliability of your infrastructure.
3+
4+
## Understanding IaC Abstraction Levels
5+
Gruntwork uses a four-layer system for describing infrastructure --
6+
7+
**Direct Infrastructure** (Lowest-Level): This is your actual deployed infrastructure, such as servers, networks, and databases.
8+
9+
**Resource-Level IaC** (Mid-Level): OpenTofu provides wrappers around cloud provider APIs and represents objects in those APIs as [resources](https://opentofu.org/docs/language/resources/). Using OpenTofu you can define individual infrastructure resources (e.g., servers, networks, databases) in code. This improves consistency and enables version control, but managing complex deployments and establishing consistency and governance can still be challenging given that every time you deploy infrastructure you have to re-specify each resource and all its arguments.
10+
11+
[**Module-Level IaC**](http://localhost:3000/2.0/docs/library/concepts/modules) (High-Level): Modules encapsulate multiple resources into reusable building blocks. For example, a module could define a web server with a load balancer, database, and security groups. Modules increase efficiency, reduce complexity, and promote best practices. Modules provide the opportunity for core teams to codify best practices and business requirements.
12+
13+
[**Service-Level IaC**](http://localhost:3000/2.0/docs/library/concepts/service-modules) (Highest-Level): At this level, you compose modules to create complete, deployable architectures, such as a multi-tier application or a data pipeline. This allows a platform team to even further codify architectures, opinions, compliance and security structures that are reusable across the enterprise.
14+
15+
<img alt="Diagram showing IaC Module Hierarchy" className="img_node_modules-@docusaurus-theme-classic-lib-theme-MDXComponents-Img-styles-module medium-zoom-image" src="/img/iac/module_types.svg" />
16+
17+
## Benefits of IaC Modules
18+
* **Increased Efficiency:** Modules eliminate the need to write repetitive code, accelerating infrastructure deployments.
19+
* **Reduced Errors:** Pre-defined and tested modules minimize the risk of configuration errors and ensure consistency.
20+
* **Improved Collaboration:** Modules promote code reuse and shared understanding across teams.
21+
* **Enhanced Compliance:** Modules can incorporate security and compliance best practices, ensuring your infrastructure adheres to standards.
22+
* **Simplified Documentation:** Modules serve as self-documenting building blocks, clearly defining infrastructure components and their relationships. Modules also regularly ship with separate documentation and examples to further explain, justify and demonstrate their use.
23+
* **Faster Recovery:** Modules stored in version control enable rapid redeployment of infrastructure from code, allowing you to quickly find and revert any mistakes from Click-ops, manual changes or other bad deployments.
24+
* **Faster Scaling:** Modules allow you to scale infrastructure quickly by reusing existing components to deploy additional copies or expand into new regions, shared-fate zones, or data centers.
25+
26+
## IaC Modules and Documentation
27+
While IaC code itself serves as a form of documentation, it's crucial to supplement it with clear and concise explanations.
28+
29+
* **Well-commented Code:** Use comments to explain the purpose and functionality of modules and resources within your IaC code.
30+
* **Module Documentation:** Create dedicated documentation for each module, including:
31+
* Purpose and functionality
32+
* Input variables and outputs
33+
* **Usage examples:** Provide examples of how to use the module in different scenarios with reasonable input variables.
34+
* **Design decisions and rationale:** Often there's more than one way to architect a solution to a problem, justify why this approach was taken and the tradeoffs it optimizes for.
35+
36+
## IaC Modules and Disaster Recovery
37+
IaC modules significantly improve disaster recovery capabilities:
38+
39+
* **Rapid Redeployment:** Redeploy infrastructure quickly from code in case of failures.
40+
* **Infrastructure as Code:** Maintain a version-controlled source of truth for your infrastructure, allowing you to see what changes were made when, and by whom, and roll back in an automated, efficient manner.
41+
* **Consistent Environments:** Recreate identical environments in different regions for redundancy.
42+
* **Drift Detection and Correction:** Identify and correct configuration drift by comparing the actual infrastructure to the defined IaC code.

‎sidebars/docs.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,11 @@ const sidebar = [
5858
type: "doc",
5959
id: "2.0/docs/overview/concepts/iac-platform",
6060
},
61+
{
62+
label: "Prebuilt IaC Modules",
63+
type: "doc",
64+
id: "2.0/docs/overview/concepts/iac-modules",
65+
},
6166
],
6267
},
6368
complianceSidebar,

‎static/img/iac/module_types.svg‎

Lines changed: 4 additions & 0 deletions
Loading

‎static/img/iac/module_types.xml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<mxfile modified="2024-11-21T23:19:10.295Z" host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36" etag="84I1RpXtmVwhRM4HkAE7" version="24.5.5" type="google">
3+
<diagram id="Ht1M8jgEwFfnCIfOTk4-" name="Page-1">
4+
<mxGraphModel dx="956" dy="1298" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
5+
<root>
6+
<mxCell id="0" />
7+
<mxCell id="1" parent="0" />
8+
<mxCell id="SsFbb6ERlav4CrbjnFOO-3" value="" style="rounded=0;whiteSpace=wrap;html=1;movable=0;resizable=0;rotatable=0;deletable=0;editable=0;locked=1;connectable=0;" vertex="1" parent="1">
9+
<mxGeometry x="20" y="-10" width="690" height="270" as="geometry" />
10+
</mxCell>
11+
<mxCell id="UEzPUAAOIrF-is8g5C7q-74" value="IaC Module - EC2 Service&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="points=[[0,0],[0.25,0],[0.5,0],[0.75,0],[1,0],[1,0.25],[1,0.5],[1,0.75],[1,1],[0.75,1],[0.5,1],[0.25,1],[0,1],[0,0.75],[0,0.5],[0,0.25]];outlineConnect=0;gradientColor=none;html=1;whiteSpace=wrap;fontSize=12;fontStyle=0;shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud_alt;strokeColor=#232F3E;fillColor=none;verticalAlign=top;align=left;spacingLeft=30;fontColor=#232F3E;dashed=0;labelBackgroundColor=#ffffff;container=1;pointerEvents=0;collapsible=0;recursiveResize=0;" parent="1" vertex="1">
12+
<mxGeometry x="50" y="50" width="310" height="190" as="geometry" />
13+
</mxCell>
14+
<mxCell id="SsFbb6ERlav4CrbjnFOO-10" value="EC2 Machine" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=#ED7100;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.compute;" vertex="1" parent="UEzPUAAOIrF-is8g5C7q-74">
15+
<mxGeometry x="10" y="66" width="78" height="78" as="geometry" />
16+
</mxCell>
17+
<mxCell id="SsFbb6ERlav4CrbjnFOO-11" value="Security Group" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=#DD344C;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.security_identity_and_compliance;" vertex="1" parent="UEzPUAAOIrF-is8g5C7q-74">
18+
<mxGeometry x="108" y="66" width="78" height="78" as="geometry" />
19+
</mxCell>
20+
<mxCell id="SsFbb6ERlav4CrbjnFOO-12" value="Load Balancer" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=#8C4FFF;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.api_gateway;" vertex="1" parent="UEzPUAAOIrF-is8g5C7q-74">
21+
<mxGeometry x="210" y="66" width="78" height="78" as="geometry" />
22+
</mxCell>
23+
<mxCell id="SsFbb6ERlav4CrbjnFOO-5" value="IaC Service Module - My App" style="text;strokeColor=none;align=left;fillColor=none;html=1;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
24+
<mxGeometry x="50" width="160" height="30" as="geometry" />
25+
</mxCell>
26+
<mxCell id="SsFbb6ERlav4CrbjnFOO-8" value="" style="group" vertex="1" connectable="0" parent="1">
27+
<mxGeometry x="390" y="50" width="280" height="190" as="geometry" />
28+
</mxCell>
29+
<mxCell id="UEzPUAAOIrF-is8g5C7q-75" value="IaC Module - Database" style="points=[[0,0],[0.25,0],[0.5,0],[0.75,0],[1,0],[1,0.25],[1,0.5],[1,0.75],[1,1],[0.75,1],[0.5,1],[0.25,1],[0,1],[0,0.75],[0,0.5],[0,0.25]];outlineConnect=0;gradientColor=none;html=1;whiteSpace=wrap;fontSize=12;fontStyle=0;shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud_alt;strokeColor=#232F3E;fillColor=none;verticalAlign=top;align=left;spacingLeft=30;fontColor=#232F3E;dashed=0;labelBackgroundColor=#ffffff;container=1;pointerEvents=0;collapsible=0;recursiveResize=0;" parent="SsFbb6ERlav4CrbjnFOO-8" vertex="1">
30+
<mxGeometry width="280" height="190" as="geometry" />
31+
</mxCell>
32+
<mxCell id="UEzPUAAOIrF-is8g5C7q-101" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=open;endFill=0;strokeWidth=2;" parent="SsFbb6ERlav4CrbjnFOO-8" source="UEzPUAAOIrF-is8g5C7q-84" target="UEzPUAAOIrF-is8g5C7q-83" edge="1">
33+
<mxGeometry relative="1" as="geometry" />
34+
</mxCell>
35+
<mxCell id="UEzPUAAOIrF-is8g5C7q-83" value="Database" style="outlineConnect=0;fontColor=#232F3E;gradientColor=#F34482;gradientDirection=north;fillColor=#BC1356;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.cloudwatch;labelBackgroundColor=#ffffff;" parent="SsFbb6ERlav4CrbjnFOO-8" vertex="1">
36+
<mxGeometry x="30" y="60" width="78" height="78" as="geometry" />
37+
</mxCell>
38+
<mxCell id="UEzPUAAOIrF-is8g5C7q-84" value="EBS Storage" style="outlineConnect=0;fontColor=#232F3E;gradientColor=#F34482;gradientDirection=north;fillColor=#BC1356;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.cloudtrail;labelBackgroundColor=#ffffff;" parent="SsFbb6ERlav4CrbjnFOO-8" vertex="1">
39+
<mxGeometry x="168.5" y="60" width="78" height="78" as="geometry" />
40+
</mxCell>
41+
<mxCell id="UEzPUAAOIrF-is8g5C7q-108" value="" style="rounded=0;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=none;dashed=1;container=1;pointerEvents=0;collapsible=0;recursiveResize=0;" parent="SsFbb6ERlav4CrbjnFOO-8" vertex="1">
42+
<mxGeometry x="10" y="40" width="120" height="130" as="geometry" />
43+
</mxCell>
44+
<mxCell id="SsFbb6ERlav4CrbjnFOO-15" value="" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=#C925D1;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.database;" vertex="1" parent="UEzPUAAOIrF-is8g5C7q-108">
45+
<mxGeometry x="20" y="20" width="78" height="78" as="geometry" />
46+
</mxCell>
47+
<mxCell id="SsFbb6ERlav4CrbjnFOO-7" value="" style="rounded=0;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=none;dashed=1;container=1;pointerEvents=0;collapsible=0;recursiveResize=0;" vertex="1" parent="SsFbb6ERlav4CrbjnFOO-8">
48+
<mxGeometry x="147.5" y="40" width="120" height="130" as="geometry" />
49+
</mxCell>
50+
<mxCell id="SsFbb6ERlav4CrbjnFOO-16" value="" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=#7AA116;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.elastic_block_store;" vertex="1" parent="SsFbb6ERlav4CrbjnFOO-7">
51+
<mxGeometry x="21" y="20" width="78" height="78" as="geometry" />
52+
</mxCell>
53+
</root>
54+
</mxGraphModel>
55+
</diagram>
56+
</mxfile>

0 commit comments

Comments
 (0)