Skip to content

Add Gruntwork Way! #2852

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Nov 19, 2025
Merged

Add Gruntwork Way! #2852

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
91f1c14
Add Gruntwork Way!
josh-padnick Nov 18, 2025
2250310
Bold first section names
josh-padnick Nov 18, 2025
ac19ab5
Remove old repo reference
josh-padnick Nov 19, 2025
04a2a37
Apply suggestions from CodeRabbit
josh-padnick Nov 19, 2025
48ae2b9
Update cspell config
josh-padnick Nov 19, 2025
33408f9
Merge branch 'add-way' of https://github.com/gruntwork-io/docs into a…
josh-padnick Nov 19, 2025
292c0a1
Rename folders, fix relative links
josh-padnick Nov 19, 2025
6f49a7e
Make a few polish improvements to catalog, runbooks, and components
josh-padnick Nov 19, 2025
d7ff146
Add husky to enforce spellcheck as a pre-commit hook.
josh-padnick Nov 19, 2025
c24b7a1
Intentional spelling error to test pre-commit hook
josh-padnick Nov 19, 2025
590dddd
Attempt to fix Husky config
josh-padnick Nov 19, 2025
467af6a
Remove husky; fix spellcheck
josh-padnick Nov 19, 2025
9a47904
Trivial wording tweak
josh-padnick Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 150 additions & 16 deletions cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,151 @@
{
"dictionaries": [
"custom-dictionary"
],
// Tell CSpell about your dictionary
"dictionaryDefinitions": [
{
// The name of the dictionary is used to look it up.
"name": "custom-dictionary",
// Path to the custom word file. Relative to this `cspell.json` file.
"path": "./custom-dictionary.txt",
// Some editor extensions will use `addWords` for adding words to your
// personal dictionary.
"addWords": true
}
]
}
"version": "0.2",
"language": "en",
"words": [
"Gruntwork",
"gruntwork",
"GitOps",
"Docusaurus",
"runbooks",
"terraform",
"terragrunt",
"Terragrunt",
"kubernetes",
"kubectl",
"autoscaling",
"monorepo",
"microservices",
"infra",
"DevOps",
"OpenTofu",
"opentofu",
"Tofu",
"prebuilt",
"repo",
"repos",
"serverless",
"cloudformation",
"elasticache",
"cicd",
"gitignore",
"cursorrules",
"npmignore",
"lockfile",
"lockfiles",
"docstrings",
"codebase",
"codebases",
"runbook",
"dockerfile",
"dockerfiles",
"orchestrator",
"orchestrators",
"customizable",
"composability",
"scalability",
"observability",
"linter",
"linters",
"linting",
"Yousif",
"Oreoluwa",
"Agunbiade",
"Yevgeniy",
"Brikman",
"Rahul",
"Vohra",
"Nana",
"Pulumi",
"pulumi",
"Rego",
"Sonatype",
"Pgvector",
"karpenter",
"Karpenter",
"MTTR",
"MTTP",
"inhouse",
"SOURCER",
"mydomain",
"terratest",
"Terratest",
"terratests",
"tailscale",
"sdlc",
"acmecorp",
"envcommon",
"tada",
"codeowners",
"jsonencode",
"chdir",
"rulesets",
"controltower",
"awscli",
"passwordless",
"coolapp",
"acmeco",
"grunty",
"yamldecode",
"mgmt",
"tfstate",
"baselining",
"baselined",
"clickops",
"terrascan",
"steampipe",
"infracost",
"kubergrunt",
"terraformrc",
"tfvars",
"fargate",
"keypair",
"mimecast",
"slugified",
"dlist",
"DEPENDENCYID",
"subfolders",
"terrapatch",
"Terrapatch",
"KodeKloud",
"preconfigured",
"projectprefix",
"GOVCLOUD",
"rollouts",
"myvars",
"myfile",
"minamijoyo",
"tfupdate",
"hcledit",
"infrachanges",
"Entra",
"GLMU",
"myprodsa",
"azuread",
"mysa",
"deinterlaced",
"rolename",
"ACCOUNTNAME"
],
Comment on lines +4 to +128
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

Verify word list migration from deleted custom-dictionary.txt.

The configuration consolidates spell-checker terms into an inline words array (127 terms). Since custom-dictionary.txt was deleted in this PR, we need to ensure all terms were successfully migrated.

Please verify that:

  1. All domain-specific terms from the deleted custom-dictionary.txt have been migrated to this array
  2. No terms were accidentally omitted during the transition
  3. No duplicate entries exist in the array

You can run this script to check for duplicates within the current word list:

🏁 Script executed:

#!/bin/bash
# Description: Check for duplicate entries in the words array of cspell.json
# Expected result: No duplicates should be found

# Extract the words array and sort to find duplicates
jq '.words | sort | .[] as $word | {word: $word}' cspell.json | \
  jq -s 'group_by(.word) | map(select(length > 1)) | if length > 0 then . else "No duplicates found" end'

Length of output: 21

I'll verify the remaining aspects of the migration by checking the git history and confirming the file deletion.


Let me try a different approach with the repository:

---

🏁 Script executed:

```shell
#!/bin/bash
# Check git history for custom-dictionary.txt deletion and show what was removed
git log --diff-filter=D --summary | grep -A 5 "custom-dictionary.txt" || echo "No deletion found in recent history"
echo "---"
# Show the git diff for the PR if available to see file removals
git show --name-status | head -30 || echo "No git show available"
echo "---"
# Look for any remaining spell-check or dictionary configuration files
fd -e txt -e json | grep -i -E "(dict|spell|custom)" || echo "No matching config files found"

Length of output: 836

🏁 Script executed:

#!/bin/bash
# Check if custom-dictionary.txt exists in the current state
if [ -f "custom-dictionary.txt" ]; then
  echo "custom-dictionary.txt found. Contents:"
  cat custom-dictionary.txt
else
  echo "custom-dictionary.txt does not exist in current state"
fi
echo "---"
# List all files in root to see what spell-check configs exist
echo "Files in root directory:"
ls -la | grep -E "\.(json|txt)$" || echo "No matching files"
echo "---"
# Check git log for the deletion
if git log --oneline --all 2>/dev/null | head -5; then
  echo "Git available. Checking for file deletion..."
  git log --follow -- custom-dictionary.txt 2>/dev/null | head -20 || echo "No git history for custom-dictionary.txt"
fi

Length of output: 1583

Now let me retrieve the original contents of the deleted file to verify the migration was complete:

🏁 Script executed:

#!/bin/bash
# Retrieve the deleted custom-dictionary.txt from git history
echo "=== Original custom-dictionary.txt contents ==="
git show HEAD~1:custom-dictionary.txt 2>/dev/null || git show c48840aa:custom-dictionary.txt 2>/dev/null || git show 48ae2b94^:custom-dictionary.txt 2>/dev/null || echo "Could not retrieve file"
echo ""
echo "=== Current cspell.json words array (first 10 for reference) ==="
jq '.words[:10]' cspell.json
echo ""
echo "=== Total words in current array ==="
jq '.words | length' cspell.json

Length of output: 972

Let me verify these potential omissions:

🏁 Script executed:

#!/bin/bash
# Check if the missing terms exist in current cspell.json
echo "=== Checking for 'gruntwork-io' in current cspell.json ==="
jq '.words[] | select(. == "gruntwork-io")' cspell.json || echo "NOT FOUND"

echo ""
echo "=== Checking for 'self-hosting' in current cspell.json ==="
jq '.words[] | select(. == "self-hosting")' cspell.json || echo "NOT FOUND"

echo ""
echo "=== Listing all current words for reference ==="
jq '.words | sort' cspell.json

Length of output: 1925

Add missing terms from deleted custom-dictionary.txt

Migration verification found two domain-specific terms that were not carried over to the words array:

  • gruntwork-io
  • self-hosting

These should be added to the words array in cspell.json to complete the migration. No duplicates were found, and all other 70 original terms were successfully migrated.

🤖 Prompt for AI Agents 
In cspell.json around lines 4 to 128, the review notes that two domain-specific
terms from the deleted custom-dictionary.txt are missing: "gruntwork-io" and
"self-hosting"; update the "words" array by adding these two entries (exact
spelling and hyphenation) ensuring they are not duplicated and follow the same
formatting as the existing entries.

"ignoreWords": [],
"ignorePaths": [
"node_modules",
"build",
"dist",
".git",
"*.lockb",
"bun.lockb",
"yarn.lock",
"package-lock.json",
".cspell.json",
"tsconfig.json",
"*.min.js",
"*.map"
],
"ignoreRegExpList": [
"/https?:\\/\\/[^\\s]+/g",
"/```[\\s\\S]*?```/g"
],
"allowCompoundWords": true,
"dictionaries": ["typescript", "node", "npm", "bash", "markdown"],
"enableFiletypes": ["markdown", "mdx", "typescript", "javascript", "json"]
}
71 changes: 0 additions & 71 deletions custom-dictionary.txt
View file
Open in desktop

This file was deleted.

10 changes: 10 additions & 0 deletions docs/2.0/way/authorship.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
sidebar_position: 10
sidebar_class_name: way-top-level-item
---

# Authorship

The Gruntwork Way was originally authored by [Josh Padnick](https://joshpadnick.com) with input from fellow Grunts Yousif Akbar, Lewis Christie, Oreoluwa Agunbiade, Brian Torres, [Yevgeniy Brikman](https://ybrikman.com) through his book [The Fundamentals of DevOps and Software Delivery](https://www.fundamentals-of-devops.com/), and especially Eben Eliason.

It is intended to be a living, evolving knowledge set, so it is our hope that if you find something you believe can be improved that you will [open a Pull Request](/2.0/way/intro/share-your-feedback) suggesting it!
6 changes: 6 additions & 0 deletions docs/2.0/way/intro/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"label": "Introduction",
"position": 1,
"className": "way-top-level-item"
}

30 changes: 30 additions & 0 deletions docs/2.0/way/intro/how-to-use-this.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
title: How To Use This
sidebar_position: 3
---

To get the most out of the Gruntwork Way, start by making sure you understand the big picture.

## The Gruntwork Way Big Picture

First, a **developer platform** is the product your platform team builds to balance three essential concerns: enabling developers to move fast ([velocity](/2.0/way/why/velocity)), meeting business needs like security, cost, and compliance ([governance](/2.0/way/why/governance)), and avoiding unsustainable technical debt ([maintainability](/2.0/way/why/maintainability)).

To build a successful platform, you need to combine three types of building blocks: [patterns](/2.0/way/platform/patterns/overview) (pre-built solutions to common infrastructure problems), [platform components](/2.0/way/platform/components/overview) (the machinery for deploying and managing infrastructure), and [interfaces](/2.0/way/platform/interfaces/overview) (how developers interact with your platform).

Finally, everything in this framework is based on the [guiding principles](/2.0/way/principles/overview) we've discovered through years of building and refining developer platforms.

## Using the Gruntwork Way

Once you understand these foundational concepts, there are two primary ways to use the Gruntwork Way.

### Option 1: Read it comprehensively

You can work through this framework from start to finish to build a complete mental model of developer platforms. This approach works well if you're just getting started or want to strengthen your overall understanding.

### Option 2: Use it as a reference

Alternatively, you can jump directly to the sections most relevant to your current challenges. This approach works well once you understand the fundamentals (which you just read above!) and need guidance on a specific aspect of your platform.

## Next

Alright, let's dive into the framework that helps you build platforms developers actually want to use!
13 changes: 13 additions & 0 deletions docs/2.0/way/intro/share-your-feedback.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Share your feedback
sidebar_position: 4
---

- This framework is useful because it's opinionated.
- Our opinions are based on nearly a decade of experience across hundreds of customers and thousand of customer conversations
- But maybe your mileage varies, or maybe we got it wrong. If so, tell us!
- To give feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Format the bare URL as a proper Markdown link.

The bare URL violates MD034 (no-bare-urls). Wrap it in Markdown link syntax to improve readability and maintainability.

Apply this diff to fix the bare URL:

-To give feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.
+To give feedback, go to [gruntwork-io/docs](https://github.com/gruntwork-io/docs) and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- To give feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.
- To give feedback, go to [gruntwork-io/docs](https://github.com/gruntwork-io/docs) and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.
🧰 Tools
🪛 LanguageTool

[style] ~9-~9: Try using a synonym here to strengthen your writing.
Context: ...e we got it wrong. If so, tell us! - To give feedback, go to https://github.com/grun...

(GIVE_PROVIDE)

🪛 markdownlint-cli2 (0.18.1)

9-9: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents 
In docs/2.0/way/intro/share-your-feedback.md around line 9, the bare URL
"https://github.com/gruntwork-io/docs" should be converted to a Markdown link;
replace the raw URL with inline link syntax (e.g.,
[gruntwork-io/docs](https://github.com/gruntwork-io/docs)) so the sentence reads
with a proper link and retains the rest of the text unchanged.


### Next

Alright, let's dive into the framework that helps you build platforms developers actually want to use!
44 changes: 44 additions & 0 deletions docs/2.0/way/intro/welcome.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: Welcome!
sidebar_position: 1
---

# Welcome!

The **Gruntwork Way** is Gruntwork's official framework for how to build a world-class developer platform.

## What's a developer platform?

Nearly every company on the planet needs software, and when companies write their own software with more than a few developers, the same common needs arise:

1. Enable developers to move fast ([velocity](/2.0/way/why/velocity))
2. ...while meeting the other needs of the business like security, cost, and compliance ([governance](/2.0/way/why/governance))
3. ...without accumulating an unsustainable level of debt ([maintainability](/2.0/way/why/maintainability))

A **developer platform** is the product your platform team builds to balance these three concerns. It consists of three essential building blocks:

- [Patterns](/2.0/way/platform/patterns/overview) - pre-built solutions to common infrastructure problems
- [Platform components](/2.0/way/platform/components/overview) - the machinery for deploying and managing infrastructure
- [Interfaces](/2.0/way/platform/interfaces/overview) - how developers interact with your platform.

Together, these enable developers to move fast while meeting the needs of the business, and to do so in a way that incurs manageable levels of debt.

## Why read this framework

Making sense of developer platforms can be confusing. We've found bits and pieces of insights scattered across blog posts, vendor solutions, and industry talks, but none of these presents a holistic way to think about developer platforms.

This framework will help you build comprehensive clarity.

Ultimately, that clarity will empower you to build a successful developer platform.

## Why trust Gruntwork

We've spent years building expertise on how to deliver software effectively by serving as:

* **Authors** - We've written leading books and guides, including [Terraform Up & Running](https://www.terraformupandrunning.com/), [Fundamentals of DevOps and Software Delivery](https://www.fundamentals-of-devops.com/?ref=blog-post-series), ,[The Startup CTO's Handbook](https://github.com/ZachGoldberg/Startup-CTO-Handbook), and [A Comprehensive Guide to Scaling Apps on AWS](https://joshpadnick.com/posts/a-comprehensive-guide-to-scaling-apps-on-aws-part-1/).
* **Makers** - We've created leading open source DevOps tooling like [OpenTofu](https://opentofu.org/) (co-founder), [Terragrunt](https://terragrunt.gruntwork.io/), [Terratest](https://terratest.gruntwork.io/), [Runbooks](https://runbooks.gruntwork.io), [Boilerplate](https://github.com/gruntwork-io/boilerplate), and [Cloud Nuke](https://github.com/gruntwork-io/cloud-nuke).
* **Experts** - As a vendor, we've equipped over 500 companies and thousands of engineers with AWS, DevOps, and Platform Engineering best practices.

## Next

Now let's learn more about who we wrote the Gruntwork Way for.
34 changes: 34 additions & 0 deletions docs/2.0/way/intro/who-this-is-for.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: Who This Is For
sidebar_position: 2
---

We wrote The Gruntwork Way for anyone trying to balance velocity, governance, and maintainability in their quest to better deliver software.

## Roles

In practice, we expect users in these roles will find this useful:

- **Platform engineers** building or improving their developer platforms
- **DevOps engineers** looking for best practices and patterns
- **Engineering leaders** evaluating their developer platform and/or cloud strategy

## Maturity levels

As you build your developer platform, you will go through a series of maturity stages.

Actually, to be more precise, you will build maturity separately in your [patterns](/2.0/way/platform/patterns/overview), [platform components](/2.0/way/platform/components/overview), and [interfaces](/2.0/way/platform/interfaces/overview). Your collective maturity level for the "developer platform" is really just the collection of maturity levels for its component parts.

In general, the component parts track these maturity levels:

- **Ad hoc** - There is no standard, so your team does things manually with minimal automation.
- **Building** - You've built something, but it's limited.
- **Established** - This component does add value, but with lots of room for improvement.
- **Mature** - This component performs its functions comprehensively and effectively.
- **Self-improving** - This component has a systematic feedback loop that leads to ongoing improvements.

The Gruntwork Way is especially useful for organizations with many building blocks in the **ad hoc,** **building,** or **established** stages.

## Next

Let's close out the introduction by giving you some pointers on how to use this framework!
6 changes: 6 additions & 0 deletions docs/2.0/way/platform/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"label": "Building Your Platform",
"position": 4,
"className": "way-top-level-item"
}

4 changes: 4 additions & 0 deletions docs/2.0/way/platform/components/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "Components",
"position": 3
}
Loading