DEV Community: Bartłomiej Danek

[Boost]

Bartłomiej Danek — Mon, 04 May 2026 18:41:00 +0000

Bartłomiej Danek

May 4

hcl-linter 0.0.1-alpha is out

#terraform #hcl #terragrunt #devops

Comments

3 min read

hcl-linter 0.0.1-alpha is out

Bartłomiej Danek — Mon, 04 May 2026 18:32:55 +0000

hcl-linter 0.0.1-alpha is out

terraform fmt only touches whitespace. In a codebase with dozens of contributors and hundreds of HCL files, block order drifts, naming conventions split, and required fields go missing quietly. I wanted something that could catch and fix that automatically - so I built hcl-linter.

The first run fixed over 1000 terragrunt.hcl files.

getting started

Two commands to go from nothing to a first pass:

hcl-linter init             # scaffold .hcl-linter/ from your existing files
hcl-linter fix ./ --dry-run # preview what would change

init walks the project, groups files by basename, and writes a .hcl-linter/default.hcl plus one extends = "default" override per unique filename. No config needed for a first formatting pass either - --format applies opinionated defaults without any config:

hcl-linter fix ./ --format --dry-run

block order

Wrong block order is the most common drift. block_order catches and auto-fixes it:

# violation - terraform before include
terraform {
  source = "git::https://github.com/example/vpc.git"
}

include "root" {
  path = find_in_parent_folders()
}

dependency "vpc" {
  config_path = "../vpc"
}

After hcl-linter fix:

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git::https://github.com/example/vpc.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

Config:

rules {
  block_order {
    enabled = true
    order   = ["include", "locals", "terraform", "dependency", "inputs"]
  }
}

naming

Hyphens in block labels break dependency.my-vpc.outputs.id references in locals. name_validation flags and auto-fixes them - hyphens replaced with underscores, references in locals updated too:

# violation
dependency "my-vpc" {
  config_path = "../vpc"
}

dependency "db-primary" {
  config_path = "../database"
}

rules {
  name_validation {
    enabled = true
    pattern = "^[a-z][a-z0-9_]*$"
    blocks  = ["dependency", "include"]
  }
}

required fields

required_fields catches missing attributes when a block is present and auto-adds them:

# violation - expose missing on include blocks
include "root" {
  path = find_in_parent_folders()
}

include "vpc" {
  path = "../vpc"
}

After fix:

include "root" {
  path   = find_in_parent_folders()
  expose = true
}

include "vpc" {
  path   = "../vpc"
  expose = true
}

rules {
  required_fields {
    include {
      expose = true
    }
  }
}

count and for_each

count_for_each warns on patterns that silently disable resources - count = 0 or for_each = {} left behind after feature flags, and count + for_each used on the same block (Terraform rejects this at plan time):

resource "aws_instance" "web" {
  count = 0         # WARNING: resource will not be created
  ami   = "ami-12345"
}

resource "aws_db_instance" "db" {
  count    = 1
  for_each = var.db_configs  # ERROR: cannot use both count and for_each
  engine   = "postgres"
}

Not fixable - count = 0 is sometimes intentional. The rule flags it so the intent is explicit.

rules {
  count_for_each {
    enabled                = true
    warn_on_count_zero     = true
    warn_on_empty_for_each = true
    warn_on_conflict       = true
  }
}

get_env without default

hcl_functions warns on get_env() calls with no fallback - those fail silently in CI if the variable is unset. It also validates that find_in_parent_folders() targets exist on disk:

locals {
  env  = get_env("MY_SECRET")                          # WARNING: no default
  root = find_in_parent_folders("nonexistent.hcl")     # ERROR: file not found
  port = get_env("PORT", "8080")                       # ok
}

rules {
  hcl_functions {
    enabled                       = true
    find_in_parent_folders_exists = true
    get_env_has_default           = true
  }
}

deprecated terraform hooks

Terragrunt renamed before_hook / after_hook to before_hooks / after_hooks a while back. terraform_block catches the old names still in use:

terraform {
  source = "git::https://github.com/example/vpc.git"

  before_hook "run_fmt" {      # WARNING: deprecated, use before_hooks
    commands = ["terragrunt"]
    execute  = ["terraform", "fmt"]
  }
}

rules {
  terraform_block {
    enabled              = true
    no_deprecated_fields = true
  }
}

dependency outputs

dependency_outputs statically validates that dependency.x.outputs.y references exist in the target module - no plan needed:

dependency "vpc" {
  config_path = "./mock-vpc"
}

inputs = {
  vpc_id     = dependency.vpc.outputs.vpc_id       # ok
  bad_output = dependency.vpc.outputs.nonexistent  # WARNING: not declared
}

Walks the dependency chain, parses output blocks from .tf files. Supports .mock-outputs.json for modules where upstream state is not available locally.

rules {
  dependency_outputs {
    enabled = true
  }
}

CI

check fails the build on any rule violation:

hcl-linter check ./infra

fix --dry-run catches everything check does, plus byte-level drift from fixable rules - if someone committed without running fix:

hcl-linter fix ./infra --dry-run

Both are composable: run check for semantic issues and fix --dry-run for formatting drift as separate steps.

install

go install github.com/bard-works/hcl-linter@latest

Or grab a binary from releases:

curl -L https://github.com/bard-works/hcl-linter/releases/latest/download/hcl-linter_linux_amd64.tar.gz | tar xz

Source and full docs: bard-works/hcl-linter

Originally published at https://bard.sh/posts/hcl-linter-release/

Beyond Slack Analytics: Building Custom Engagement Metrics with Webhooks, Prometheus, and Grafana

Bartłomiej Danek — Tue, 28 Apr 2026 13:01:24 +0000

TL;DR: Slack's native analytics won't tell you which threads die, which requests get ignored, or how yyour team's collaboration patterns evolve. I built a Go webhook handler that captures every reaction, reply, and thread via Slack's event API, exports it to Prometheus, and visualizes it in Grafana - giving me metrics Slack never will.

The Wake-Up Call

It started with a post-incident review. We'd just recovered from a 3-hour outage, and I was asked the usual questions: How fast did we respond? Which channels were involved? Were there warning signs in our internal Slack discussions before things broke?

I opened Slack's analytics dashboard. Member counts. Message volume. Channel growth. Vanity metrics that told me nothing about the incident or our response patterns.

I couldn't answer basic questions: How many infrastructure requests were sitting unresolved in our #platform-requests channel? Who was drowning in context-switching across too many active threads? Had we missed early warning signs buried in reaction patterns on code review requests?

Worse, I realized I was guessing about team health. I'd see a busy Slack day and assume we were productive. I'd see green checkmark reactions and assume requests were getting fulfilled. But I had no data - just gut feel and fragmented chat history.

Then came the compliance gap. A terraform apply failed in staging, and someone replied with "skipping, will fix later" - then applied the change manually to unblock themselves. It showed up as a casual thread reply with a 😱 reaction from a teammate, buried under 30 messages. No alert, no metric, no visibility - until I went looking for it during the post-mortem and found the octopus reaction someone had wisely added to flag the IaC violation.

That's when I realized: Slack is where my team actually works, but Slack's analytics treat it like a broadcast channel instead of a workflow engine. Every reaction, every thread, every reply is a data point. I just wasn't collecting them.

So I built something to fix that.

Why Slack Won't Tell You What You Need to Know

Slack gives you member counts, message volume, and channel growth. That's it. If you're running a platform engineering team, a DevOps org, or an internal support channel, those numbers are vanity metrics.

What you actually need to know:

Which threads get resolved vs. abandoned?
How fast does the team respond to infrastructure requests?
Which code review requests get ignored (and why)?
Are people actually engaging with your announcements?

Slack doesn't expose this. But Slack's event subscriptions do - if you know how to catch them.

Architecture: How I Capture What Slack Hides

The system has three layers: Slack events → Go webhook handler → Prometheus + Grafana.

The Webhook Handler

Built in Go 1.26 with Gin, the handler listens at POST /api/slack/events. Every event goes through this middleware stack:

Middleware	Purpose	Notes
Recovery	Panic recovery
RequestID	Unique ID per request
GinLogger	Structured JSON logging
RequestSizeLimit	Reject >1MB
RateLimiter	10 req/s per IP, burst 20	Handles Slack's event batching
SlackVerification	HMAC-SHA256 signature check

The burst 20 setting is critical - Slack's Event API sometimes batches multiple events into a short window, so a single IP can legitimately spike above 10 req/s. The burst allows those spikes without dropping legitimate events.

The three event types we care about:

1. message events - catch new threads and replies:

// internal/handler/slack.go (simplified)
if event.ThreadTs == "" || event.ThreadTs == event.Ts {
    // Top-level message → new thread
    metrics.RecordNewThread(ctx, channel, event.Ts)
} else {
    // Reply in thread
    metrics.RecordThreadReply(ctx, channel, event.ThreadTs, event.User)
}

2. reaction_added / reaction_removed - the signal layer:

// Reactions are stored in Redis + recorded as metrics
metrics.RecordThreadReaction(ctx, channel, event.Item.Ts, event.User, event.Reaction)
metrics.RecordUserEngagement(ctx, channel, event.Item.Ts, event.User)

3. url_verification - Slack's challenge-response during app setup.

The Slack Retry Problem

Slack expects a 200 OK within 3 seconds. If your handler is busy writing to Redis or the Prometheus exporter is slow, Slack will retry the event - and you'll get duplicate counts in your metrics.

The fix: acknowledge first, process asynchronously. Return 200 OK immediately, then handle the event in a goroutine:

// internal/handler/slack.go (simplified)
func (h *Handler) HandleEvent(c *gin.Context) {
    var event SlackEvent
    if err := c.ShouldBindJSON(&event); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    // Acknowledge immediately - don't block on Redis/Prometheus
    c.JSON(200, gin.H{"ok": true})

    // Process in background
    go func() {
        ctx := context.Background()
        if event.ThreadTs == "" || event.ThreadTs == event.Ts {
            h.metrics.RecordNewThread(ctx, event.Channel, event.Ts)
        } else {
            h.metrics.RecordThreadReply(ctx, event.Channel, event.ThreadTs, event.User)
        }
    }()
}

This prevents Slack's retry mechanism from creating duplicate metric increments.

Why Reactions Are the Secret Signal

I don't just count messages. I track reactions as semantic signals:

Emoji	Reaction Name	Meaning	Metric Label
✅	white_check_mark	Request completed	`reaction="white_check_mark"`
😱	scream	Multiple active threads per person (overload)	`reaction="scream"`
🚫	no_entry	Irrelevant code review request	`reaction="no_entry"`
🔁	repeat	Repeating / duplicate request	`reaction="repeat"`
❌	x	Irrelevant request	`reaction="x"`
✔️	done	Completed (no PR review needed)	`reaction="done"`
🐙	octopus	Infrastructure-as-Code violation	`reaction="octopus"`

This turns Slack into a structured workflow tool - reactions become queryable metrics.

Getting the Team on Board (Social Engineering)

This only works if people actually use the reactions. I didn't mandate it - instead, I led by example: I started reacting to threads with octopus when I saw IaC violations, and with scream when I was drowning in threads. Within a week, the team adopted it naturally. The key is making it feel like a helpful shorthand, not a tracking mechanism. If the team doesn't use the emoji, your metrics are useless - so make it useful for them first.

Metric Definitions and Component Mapping

I define 5 OpenTelemetry counter metrics in internal/metrics/slack.go. The Prometheus exporter appends _total, giving the double suffix you see in PromQL queries - you might want to fix it in your OTEL Agent.

Metric-to-Component Mapping

Code Name	Labels	Triggered By
`webhook_requests_total`	`channel`, `status`	Every incoming webhook
`threads_total`	`channel`	New top-level message
`thread_replies_total`	`channel`, `user_id`	Reply in thread
`thread_reactions_total`	`channel`, `user_id`, `reaction`	Reaction added
`user_engagement_total`	`channel`, `user_id`	Reply OR reaction

The Prometheus Cardinality Bomb

If you're tempted to add thread_id as a label - don't. In my original POC, I made this mistake. In Prometheus, every unique combination of label values creates a new time series. With thousands of Slack threads (each with a unique thread_id), you're creating thousands of time series. This is a cardinality bomb that will explode your Prometheus memory usage and can crash the instance.

The fix: Keep Prometheus for aggregate channel-level counters only. Thread-level detail belongs in Redis (which I'm already using) or a SQL database, not in Prometheus labels. If you want the "Longest Thread" feature, query Redis directly - don't pollute your metrics with high-cardinality labels. Prometheus is for metrics, not event logging.

Key Performance Indicators

The dashboard is organized into four insight layers, each answering a different question about how your Slack channels actually operate:

Volume & Throughput - Are we drowning or cruising?
Total Threads shows raw request load per day, making it obvious which days are release days, incident spikes, or quiet periods. Active Threads (threads with at least one reply) reveals engagement depth - a high thread count with low reply rate means people are posting but not discussing, a signal of announcements drowning out conversation.

Resolution Signals - Are requests actually getting done?
The green panels tell the completion story. white_check_mark reactions track formal completions - infrastructure requests fulfilled, reviews done. done reactions capture quick wins that never needed a PR. Meanwhile, x reactions surface canceled or irrelevant requests, helping you spot scope creep or misrouted asks. Together, they give you a resolution rate without ever asking anyone to fill out a form.

Quality & Friction - Where is the process breaking?
The red and yellow panels are your early warning system. A spike in scream reactions means people are drowning in threads - too many active requests per person. no_entry on code reviews exposes recurring low-quality submissions from specific contributors. repeat reactions highlight documentation gaps - the same question asked three times means the answer isn't findable. octopus flags manual infrastructure changes that bypass your IaC pipeline, a compliance risk you'd otherwise miss.

Time-Based Insights - When is the team really working?
The blue panels surface patterns hidden by aggregate daily stats. After-Hours Work quantifies overtime - if 30% of threads start after 17:00, you have an on-call problem, not a "dedicated team" problem. Longest Thread with a clickable Slack link lets you jump directly to the most contentious discussion - usually a design debate or a stuck incident. Busiest Day aggregates threads by date to reveal your actual rhythm: Tuesday releases? Friday incident spikes? The data tells the story.

Business-Hour Awareness

One panel tracks requests outside 10:00–17:00 (browser time):

sum_over_time(
  (
    sum(
      increase(threads_total{channel=~"$channel_filter"}[5m])
      and on()
        ((hour() < 10) or (hour() >= 17))
    )
  )[$__range:5m]
)

This tells us: is the team working after hours? If so, why?

Note: The hour() function in Prometheus uses UTC. If your team is in a different timezone (e.g., CET/Poland), adjust the offsets: 10:00 CET = 08:00 UTC, 17:00 CET = 15:00 UTC. Adjust the < 10 / >= 17 values based on where your Prometheus server is running.

Longest Thread Detection

Since I removed thread_id from Prometheus labels (see The Prometheus Cardinality Bomb), the "Longest Thread" feature works differently: I pull thread IDs directly from Redis, where high-cardinality data lives safely. The Grafana dashboard queries Redis for the top threads by reply count, then overlays Prometheus aggregate trends for context.

To implement this, use a Grafana Infinity datasource or Redis datasource plugin to query:

LRANGE replies:{channel}:* 0 -1

Then match the longest list to its channel and thread_ts. The clickable Slack link is built from these Redis keys:

https://yourworkspace.slack.com/archives/{channel}/p{thread_ts_without_dot}

Alternatively, if you keep thread_id in Prometheus for a small team (few threads), the PromQL would be:

topk(
  1,
  sum by (thread_id, channel) (
    max_over_time(
      thread_replies_total_total{
        channel=~"$channel_filter"
      }[$__range]
    )
  )
)

With a Data link override pointing to https://yourworkspace.slack.com/archives/${channel}/p${__cell}.

Busiest Day Detection

sum(
  increase(threads_total{channel=~"$channel_filter"}[1d])
)

Grafana transformations convert the timestamp to YYYY-MM-DD format and sort by value.

Dependencies: What We Chose and Why

go.mod (direct dependencies)
├── github.com/gin-gonic/gin v1.11.0         # HTTP routing
├── go.opentelemetry.io/otel v1.40.0         # Metrics SDK
├── go.opentelemetry.io/otel/exporters/prometheus v0.62.0  # Prometheus export
├── go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp v1.40.0
├── github.com/prometheus/client_golang v1.23.2  # Prometheus client
├── github.com/redis/go-redis/v9 v9.17.3     # Redis client (cluster support)
├── golang.org/x/time v0.14.0                # Rate limiting
└── github.com/alicebob/miniredis/v2 v2.36.1 # In-memory Redis for tests

Key Trade-offs

Choice	Why	Trade-off
OpenTelemetry over raw Prometheus client	Future-proof, OTLP export option	More boilerplate setup
Redis for thread storage	Fast lookups, TTL support	Extra dependency, network hop
Gin over stdlib	Fast dev, built-in middleware	Framework lock-in
Counter metrics only	Simple, append-only	No histograms for latency (yet)
Fly.io deployment	Simple, cheap, EU region (waw)	Less control than K8s

What I Skipped

Histograms: I don't track webhook processing latency. The handler is fast enough (<10ms) that it hasn't mattered yet.
Gauge metrics: No "current active threads" gauge. I rely on increase() queries instead.
Thread cancellation: No separate metric needed - canceled threads are tracked via thread_reactions_total{reaction="x"} (the ❌ emoji). The Grafana dashboard queries reactions with reaction="x" to surface irrelevant/canceled requests.

Redis Data Structures

The handler stores thread context in Redis for enrichment (not just metrics):

Key Pattern	Type	Content
`reactions:{channel}:{ts}`	Hash	Field: `{reaction}:{user}`, Value: JSON with timestamps
`messages:{channel}:{ts}`	String	JSON: user, text, ts, channel
`replies:{channel}:{thread_ts}`	List	JSON entries for each reply
`processed_events:{event_id}`	String	TTL 5min - idempotency key for Slack retries

Event Deduplication

Slack retries events if it doesn't get a 200 OK fast enough. To prevent double-counting metrics, the handler uses the event_id as an idempotency key with SETNX:

// Before processing, check if we already handled this event
key := fmt.Sprintf("processed_events:%s", slackEvent.EventID)
// SetNX returns true if key was SET (new event), false if key already existed
processed, _ := rdb.SetNX(ctx, key, "1", 5*time.Minute).Result()
if !processed {
    // Event already processed - skip to prevent double-counting
    return
}

This ensures that even if Slack sends the same event twice during a network blip, your metrics are only incremented once.

Lessons Learned

1. Reactions Are Better Than Thread Replies for Signals

A reply requires typing. A reaction is one click. I get 3× more signal from reactions than replies because the friction is lower.

2. Grafana Transformations Are Powerful But Fragile

The "Longest Thread" panel uses 4 transformations: sortBy, limit, convertFieldType, formatTime, and renameByRegex. One breaks, the panel dies. Keep transformations minimal where possible.

3. Rate Limiting Is Essential

Slack's event replay will flood you if your handler was down. Our rate limiter (10 req/s per IP) prevents thundering herd on restart.

Wrapping Up: What You Get Out of This

Building custom Slack metrics isn't about dashboards for the sake of dashboards. It's about making the invisible visible. Here's what this setup gives you after a few weeks of data:

You stop guessing about team health. A quick glance at the KPI row tells you: are we keeping up (green), drowning in context-switching (scream spikes), or fielding the same question repeatedly (repeat reactions)? These aren't vanity metrics - they're leading indicators of burnout, documentation gaps, and process breakdowns.

You catch compliance and quality issues early. That octopus reaction on a thread? It's someone manually changing infrastructure instead of using Terraform. The no_entry on a code review? A recurring contributor quality problem you can address directly. Without this signal, those issues stay hidden in chat history until they become outages.

You understand your real working patterns. The after-hours panel quantifies overtime without timesheets. The longest thread view surfaces your actual bottlenecks - the design debates and stuck incidents that deserve retrospectives. The busiest day chart reveals whether your release rhythm is working or just creating spikes.

You get all of this without asking anyone to change behavior. No new forms, no status updates, no "please label your threads." People just use Slack the way they always have - the reactions and replies they'd make anyway become the data. That's the real win: observability that emerges from existing workflows, not another process to maintain.

The stack is lightweight: a Go handler (~200 lines), Redis for context, Prometheus for storage, Grafana for visualization. But the output is a window into your team's actual collaboration patterns - the stuff Slack's analytics won't show you, and the stuff you need if you want to lead a team effectively.

One final note: the working POC took me a few hours to build - without AI assistance. Not because I'm unusually fast, but because this isn't actually hard when you understand how the pieces fit together. Slack gives you webhooks. Prometheus takes counters. Grafana draws panels. The real skill isn't writing the code - it's recognizing that the data you need is already flowing through your tools, you just haven't built the bridge between them yet. Sometimes the best observability projects are the ones where you stop waiting for a vendor feature and wire up the integration yourself.

Originally published at https://bard.sh/posts/slack-metrics/

Terraform Modules: Composition Over Abstraction

Bartłomiej Danek — Mon, 27 Apr 2026 13:19:36 +0000

Terraform Modules: Composition Over Abstraction

Terraform makes it easy to build large, highly abstracted modules that try to solve everything in one place. At first glance, this feels efficient: fewer modules, fewer calls, less wiring.

In practice, that approach often creates more problems than it solves.

A better pattern-especially as infrastructure grows-is to design small, focused, “atomic” modules and combine them using composition.

What We Mean by Composition

In this context, composition means:

Building infrastructure by combining smaller, independent modules instead of hiding everything behind a single, all-in-one module.

Instead of:

one module doing everything internally

you have:

multiple modules wired together explicitly

module "role" { ... }

module "policy" { ... }

module "attachment" {
  role   = module.role.name
  policy = module.policy.arn
}

This is not just a stylistic choice-it directly impacts maintainability, safety, and clarity.

The Problem with “Do-It-All” Modules

A common anti-pattern is a module that:

creates multiple IAM roles
generates multiple policies
attaches them
conditionally enables features via flags
supports multiple unrelated use cases

Example:

module "irsa" {
  source = "./modules/irsa"

  roles = {
    service_a = {
      policies = ["s3", "dynamodb"]
    }
    service_b = {
      policies = ["sqs"]
    }
  }
}

This looks convenient, but introduces several issues.

Hidden Coupling

All resources share one lifecycle.

A small change:

can affect unrelated roles
may trigger unnecessary diffs
increases risk during apply

Poor Reusability

“Generic” modules often become:

too opinionated for some use cases
too complex for others

Consumers either:

fight the interface
or reimplement logic elsewhere

Hard-to-Review Changes

A simple modification may:

touch multiple resources
impact different logical paths

This makes it difficult to answer:

What will this change actually do?

Large Blast Radius

Terraform operates at the module/state level.

Large modules lead to:

bigger plans
slower applies
harder rollbacks
increased risk

Atomic Modules: A Better Approach

“Atomic” does not mean artificially small.

It means:

A module should represent a single logical responsibility.

Examples:

iam-role
iam-policy
iam-role-policy-attachment

Each module:

has a clear purpose
exposes a minimal interface
can be reused independently

Example: IRSA - Monolith vs Composition

Monolithic Approach

module "irsa" {
  source = "./modules/irsa"

  roles = {
    service_a = {
      policies = ["s3", "dynamodb"]
    }
  }
}

Problems:

tightly coupled lifecycle
unclear ownership
difficult to modify safely

Composed Approach

Create role

module "service_a_role" {
  source = "./modules/iam-role"

  name = "service-a"
  assume_role_policy = data.aws_iam_policy_document.irsa.json
}

Create policy

module "service_a_s3_policy" {
  source = "./modules/iam-policy"

  name   = "service-a-s3"
  policy = data.aws_iam_policy_document.s3.json
}

Attach policy

module "service_a_attach_s3" {
  source = "./modules/iam-role-policy-attachment"

  role_name  = module.service_a_role.name
  policy_arn = module.service_a_s3_policy.arn
}

Why Composition Works Better

Clear Ownership

Each resource:

is defined explicitly
belongs to a specific consumer

Safer Changes

Updating a policy:

affects only that policy
does not impact unrelated roles

Better Reusability

You can:

reuse policies across roles
attach policies flexibly
compose behavior without modifying modules

Easier Debugging

Failures are easier to trace because:

modules are small
responsibilities are clear

Composition vs Abstraction

These are often confused.

Approach	Focus	Trade-off
Abstraction	Simplicity of usage	Hidden complexity, rigidity
Composition	Flexibility, clarity	More explicit wiring

Monolithic modules favor abstraction.

Atomic modules favor composition.

Trade-offs of Composition

This approach is not free.

More Module Calls

You will write more blocks.

This increases verbosity, but also improves clarity.

More Explicit Wiring

You pass outputs between modules.

This is intentional:

dependencies are visible
behavior is predictable

Risk of Over-Fragmentation

Splitting everything blindly leads to:

unnecessary complexity
modules that are never used independently

Example of going too far:

separating tightly coupled resources that must always exist together

Practical Rule of Thumb

If a resource can be safely changed, reused, or destroyed independently, it should likely be its own module.

If not, keep it together.

When Larger Modules Still Make Sense

There are valid cases for bigger modules:

tightly coupled infrastructure (e.g., VPC with subnets and routing)
opinionated platform layers
internal “productized” infrastructure

Even then:

avoid “god modules”
keep boundaries clear
prefer internal composition

Key Insight

The real shift is this:

Move complexity from inside modules to between modules.

Monolith → implicit complexity
Composition → explicit complexity

In infrastructure systems, explicit complexity is easier to manage over time.

Summary

Prefer composition over monolithic abstraction
Design modules with single responsibilities
Keep dependencies explicit and visible
Accept some verbosity in exchange for safety and clarity

The goal is not smaller modules.

The goal is predictable, composable, and low-risk infrastructure.

Originally published at https://bard.sh/posts/terraform-modules-composition-over-abstraction/

Smart DNS: Auto-Detecting Route53 Records in Terraform

Bartłomiej Danek — Mon, 27 Apr 2026 12:15:06 +0000

Smart DNS: Auto-Detecting Route53 Records in Terraform

Every Route53 record in plain Terraform means a zone lookup, an explicit type, and for load balancers - a separate data source just to wire the alias.

data "aws_route53_zone" "this" {
  name = "api.example.com."
}

data "aws_lb" "api" {
  name = "api-nlb"
}

resource "aws_route53_record" "api" {
  zone_id = data.aws_route53_zone.this.zone_id
  name    = "api.example.com"
  type    = "A"

  alias {
    name                   = data.aws_lb.api.dns_name
    zone_id                = data.aws_lb.api.zone_id
    evaluate_target_health = true
  }
}

With a module that infers everything, the same record becomes:

inputs = {
  name    = "api.example.com"
  records = "api-nlb-1234567890.elb.eu-west-1.amazonaws.com"
}

zone auto-detection

name = "api.example.com"
        │
        └─ strip first label
                │
                ▼
        "example.com"  ──► aws_route53_zone lookup

The module splits the FQDN, drops the first label, queries Route53 for the hosted zone. No zone_id from the caller.

For apex records or non-standard cases, zone_override skips this.

type inference

records value
      │
      ├─ type_override set? ───────────────► use that type (NS/MX/TXT/etc.)
      │
      ├─ is map?
      │     ├─ has "name" key? ────────────► alias A  (lookup LB by name)
      │     └─ has "tags" key? ────────────► alias A  (lookup LB by tags)
      │
      ├─ is string or list?
      │     ├─ all values are IPv4? ───────► A
      │     ├─ ends with .amazonaws.com? ──► alias A  (lookup LB by hostname)
      │     └─ else ───────────────────────► CNAME
      │
      └─ (nothing created if no branch matches)

Each branch maps to a separate aws_route53_record resource using for_each over a conditional set - only one fires per invocation.

lb alias lookup modes

Mode	Input	How
By hostname	`records = "my-nlb-xxx.amazonaws.com"`	parse LB name from hostname prefix
By name	`records = { nlb = { name = "my-nlb" } }`	`aws_lb` data source by name
By tags	`records = { alb = { tags = {...} } }`	`aws_lb` data source by tag filter

All three produce an alias block with evaluate_target_health = true.

escape hatches

Scenario	Solution
NS delegation	`type_override = "NS"`
MX at zone apex	`type_override = "MX"` + `zone_override = "example.com"`
TXT verification	`type_override = "TXT"`
Private hosted zone	`private_zone = true`
Custom TTL	`ttl = 300`

the idea

DNS configuration is mostly mechanical - you know the hostname or IP address(es), you know what it points to. The type, the zone, whether it needs an alias block - those are derivable. This module pushes that derivation into Terraform so callers don't repeat it.

The tradeoff is explicitness. Plain Terraform is verbose, but every field is visible and validated. The module is terse, but inference can surprise you - especially the records = "..." string that silently becomes an alias lookup against AWS instead of a literal CNAME value.

It works best when:

you manage many records across consistent naming conventions
all your LBs follow predictable hostname patterns (*.<region>.elb.amazonaws.com)
your zones map cleanly to second-level domains (one zone per domain, no split-horizon edge cases)

It gets awkward when:

you need fine-grained TTL control per record
you have private hosted zones with the same name as public ones (need private_zone = true consistently)
your LB names are not stable - tag-based lookup is more resilient there

trade-off

records is type = any. Terraform cannot validate at plan time. A typo in a map key (naam instead of name) silently falls through to CNAME instead of alias. Review plan output before apply - the wrong record type shows up as a different resource being created.

full example

# CNAME
inputs = {
  name    = "api.example.com"
  records = "old-api.example.com"
}

# A record
inputs = {
  name    = "api.example.com"
  records = ["203.0.113.10", "203.0.113.11"]
}

# Alias to NLB by hostname
inputs = {
  name    = "api.example.com"
  records = "api-nlb-1234567890.elb.eu-west-1.amazonaws.com"
}

# Alias to ALB by tags
inputs = {
  name    = "api.example.com"
  records = {
    alb = {
      tags = {
        Name = "api-alb"
        Env  = "prod"
      }
    }
  }
}

# NS delegation with zone override
inputs = {
  name          = "example.com"
  records       = ["ns1.example.net", "ns2.example.net"]
  type_override = "NS"
  zone_override = "example.com"
}

Originally published at https://bard.sh/posts/route53-auto-detecting-terraform/

What is Terragrunt and why you need it

Bartłomiej Danek — Fri, 24 Apr 2026 09:43:55 +0000

What is Terragrunt and why you need it

the multi-env problem

With plain Terraform, managing multiple environments means duplicating config - same modules, different variable files, same backend boilerplate repeated everywhere.

environments/
├── dev/
│   ├── main.tf        # copy
│   ├── variables.tf   # copy
│   └── backend.tf     # copy with different key
├── staging/
│   ├── main.tf        # copy
│   ├── variables.tf   # copy
│   └── backend.tf     # copy with different key
└── prod/
    ├── main.tf        # copy
    ├── variables.tf   # copy
    └── backend.tf     # copy with different key

Any change to the module requires updating all three.

what Terragrunt does

Terragrunt is a thin wrapper around Terraform that adds:

DRY backend config - define once, inherit everywhere
dependency blocks - wire modules together without a monolith
run-all - apply/plan/destroy across multiple modules in one command
generate blocks - auto-generate files (provider configs, backend configs)
mock_outputs - unblock plan in CI when dependencies haven't been applied yet

terraform vs terragrunt

	Terraform	Terragrunt
Backend config	per-module	inherited from root
Multi-module apply	manual	`run-all`
Module wiring	`terraform_remote_state`	`dependency` block
DRY config	variables only	full config inheritance

installation

asdf plugin-add terragrunt
asdf install terragrunt 0.67.0
asdf local terragrunt 0.67.0

or developer.hashicorp.com/terraform/tutorials/automation/terragrunt

what the structure looks like

Instead of duplicated .tf files, you get one root.hcl and small terragrunt.hcl files per unit that only define what's different:

root.hcl
environments/
├── dev/
│   ├── vpc/
│   │   └── terragrunt.hcl   # 5 lines: include + inputs
│   ├── rds/
│   │   └── terragrunt.hcl
│   └── eks/
│       └── terragrunt.hcl
└── prod/
    ├── vpc/
    │   └── terragrunt.hcl
    ├── rds/
    │   └── terragrunt.hcl
    └── eks/
        └── terragrunt.hcl

A typical leaf terragrunt.hcl:

include "root" {
  path = find_in_parent_folders("root.hcl")
}

terraform {
  source = "git::https://github.com/org/tf-modules.git//vpc?ref=v1.2.0"
}

inputs = {
  name       = "prod-vpc"
  cidr_block = "10.0.0.0/16"
}

The backend, provider, and locking config all come from root.hcl - no repetition.

See folder structure and include for the full root.hcl setup.

Originally published at https://bard.sh/posts/what-is-terragrunt/

Terragrunt run-all

Bartłomiej Danek — Fri, 24 Apr 2026 09:43:14 +0000

Terragrunt run-all

Runs a Terraform command across all units in the current directory tree, respecting dependency order.

cd environments/prod
terragrunt run-all plan
terragrunt run-all apply
terragrunt run-all destroy   # reverse order

dependency-aware ordering

environments/prod/
├── vpc/
├── rds/          # depends on vpc
└── eks/          # depends on vpc

run-all apply applies vpc first, then rds and eks in parallel.

real CI pipeline

# .github/workflows/deploy.yml
- name: Plan all
  run: terragrunt run-all plan --terragrunt-non-interactive
  working-directory: environments/prod

- name: Apply all
  run: terragrunt run-all apply --terragrunt-non-interactive -auto-approve
  working-directory: environments/prod
  if: github.ref == 'refs/heads/main'

Detect drift in CI without applying:

# exit code 2 = changes detected, 0 = no changes, 1 = error
terragrunt run-all plan \
  --terragrunt-non-interactive \
  -detailed-exitcode

filtering

# skip a unit
terragrunt run-all apply --terragrunt-exclude-dir environments/prod/rds

# target a single unit and its dependencies
terragrunt run-all apply --terragrunt-include-dir environments/prod/eks

parallelism

# default is unlimited parallel - cap it if you hit API rate limits
terragrunt run-all apply --terragrunt-parallelism 4

output

Each unit prefixes its own output:

[environments/prod/vpc] Apply complete! Resources: 12 added.
[environments/prod/rds] Apply complete! Resources: 4 added.
[environments/prod/eks] Apply complete! Resources: 31 added.

Originally published at https://bard.sh/posts/terragrunt-run-all/

Terragrunt remote_state and generate blocks

Bartłomiej Danek — Fri, 24 Apr 2026 09:43:09 +0000

Terragrunt remote_state and generate blocks

`remote_state`

Defines the backend once in root.hcl - Terragrunt auto-generates the backend config for every unit that includes it.

# root.hcl
remote_state {
  backend = "s3"
  config = {
    bucket         = "my-tf-state"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "eu-west-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
}

path_relative_to_include() resolves to the path of the calling terragrunt.hcl relative to root.hcl - e.g. environments/prod/vpc - giving each unit a unique state key automatically.

`generate` block

Writes any file before running Terraform - typically used for provider.tf and backend.tf so they don't need to be duplicated in every module.

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "eu-west-1"

  default_tags {
    tags = {
      ManagedBy   = "terraform"
      Environment = "prod"
    }
  }
}
EOF
}

`if_exists` options

overwrite_terragrunt - overwrite only if Terragrunt generated the file (safe default)
overwrite - always overwrite
skip - skip if file exists
error - error if file exists

generating multiple files

generate "versions" {
  path      = "versions.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
terraform {
  required_version = ">= 1.5"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}
EOF
}

Originally published at https://bard.sh/posts/terragrunt-remote-state/

Terragrunt folder structure and include

Bartłomiej Danek — Fri, 24 Apr 2026 09:42:28 +0000

Terragrunt folder structure and include

Terragrunt projects split config into two layers: a root hcl file with shared settings, and per-unit terragrunt.hcl files that inherit from it.

root.hcl
environments/
├── dev/
│   ├── vpc/
│   │   └── terragrunt.hcl
│   ├── rds/
│   │   └── terragrunt.hcl
│   └── eks/
│       └── terragrunt.hcl
└── prod/
    ├── vpc/
    │   └── terragrunt.hcl
    ├── rds/
    │   └── terragrunt.hcl
    └── eks/
        └── terragrunt.hcl

Each leaf terragrunt.hcl is one Terraform unit - its own state file, its own apply.

`include` - inherit from root

# environments/prod/vpc/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}

terraform {
  source = "git::https://github.com/org/tf-modules.git//vpc?ref=v1.2.0"
}

inputs = {
  name       = "prod-vpc"
  cidr_block = "10.0.0.0/16"
}

root.hcl

# root.hcl
locals {
  env    = basename(dirname(get_terragrunt_dir()))
  region = "eu-west-1"
}

remote_state {
  backend = "s3"
  config = {
    bucket         = "my-tf-state"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = local.region
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "${local.region}"
}
EOF
}

`find_in_parent_folders`

Walks up the directory tree until it finds the file - no hardcoded paths needed.

include "root" {
  path = find_in_parent_folders()          # finds root.hcl by default
}

include "root" {
  path = find_in_parent_folders("root.hcl") # explicit name
}

Originally published at https://bard.sh/posts/terragrunt-folder-structure/

Terragrunt dependency and mock_outputs

Bartłomiej Danek — Fri, 24 Apr 2026 09:42:23 +0000

Terragrunt dependency and mock_outputs

`dependency` block

Reads outputs from another Terragrunt unit - cleaner than terraform_remote_state and aware of the apply order.

# environments/prod/eks/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "rds" {
  config_path = "../rds"
}

inputs = {
  vpc_id          = dependency.vpc.outputs.vpc_id
  private_subnets = dependency.vpc.outputs.private_subnet_ids
  db_endpoint     = dependency.rds.outputs.endpoint
}

`mock_outputs`

Without mock outputs, terragrunt plan fails if a dependency hasn't been applied yet - it can't fetch real outputs. Mock outputs provide placeholder values for plan only.

dependency "vpc" {
  config_path = "../vpc"

  mock_outputs = {
    vpc_id             = "vpc-00000000"
    private_subnet_ids = ["subnet-00000000", "subnet-11111111"]
  }

  mock_outputs_allowed_terraform_commands = ["plan", "validate"]
}

`mock_outputs_allowed_terraform_commands`

Controls which commands use mocks - apply always uses real outputs.

mock_outputs_allowed_terraform_commands = ["plan", "validate", "destroy"]

dependency graph

Terragrunt resolves the graph automatically with run-all - units apply in the right order.

vpc  ──►  eks
     ──►  rds  ──►  app

# applies vpc first, then rds and eks in parallel, then app
terragrunt run-all apply

Originally published at https://bard.sh/posts/terragrunt-dependency/

Terraform S3 backend with state locking

Bartłomiej Danek — Fri, 24 Apr 2026 09:41:07 +0000

Terraform S3 backend with state locking

S3 stores the state file, DynamoDB handles locking - prevents two apply runs from corrupting state simultaneously.

setup

terraform {
  backend "s3" {
    bucket         = "my-tf-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

create the S3 bucket and DynamoDB table

resource "aws_s3_bucket" "tf_state" {
  bucket = "my-tf-state"
}

resource "aws_s3_bucket_versioning" "tf_state" {
  bucket = aws_s3_bucket.tf_state.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "tf_state" {
  bucket = aws_s3_bucket.tf_state.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

resource "aws_dynamodb_table" "tf_locks" {
  name         = "terraform-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

state locking in action

$ terraform apply
Acquiring state lock. This may take a few moments...

# if another process holds the lock:
Error: Error acquiring the state lock
Lock Info:
  ID:        abc-123
  Path:      prod/terraform.tfstate
  Operation: OperationTypeApply
  Who:       alice@machine
  Created:   2024-10-14 12:00:00

force-unlock (use carefully)

terraform force-unlock <lock-id>

per-environment keys

# dev
backend "s3" {
  key = "dev/terraform.tfstate"
}

# prod
backend "s3" {
  key = "prod/terraform.tfstate"
}

Originally published at https://bard.sh/posts/terraform-s3-backend/

.terraform.lock.hcl - commit it

Bartłomiej Danek — Fri, 24 Apr 2026 09:41:01 +0000

`.terraform.lock.hcl` - commit it

Terraform generates this file on terraform init - it pins the exact provider versions and their checksums so every team member and CI run uses the same binaries.

provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.50.0"
  constraints = "~> 5.0"
  hashes = [
    "h1:abc123...",
    "zh:def456...",
  ]
}

what it contains

version - exact version that was selected
constraints - the constraint from required_providers
hashes - checksums for each platform (linux, darwin, windows)

why commit it

reproducible builds - everyone gets the same provider binary
audit trail - version changes are visible in git diff
faster CI - Terraform can skip checksum verification with -lockfile=readonly

updating it

# upgrade a specific provider
terraform init -upgrade

# upgrade all providers
terraform init -upgrade -reconfigure

CI flag

# fails if lock file is out of date - use in CI
terraform init -lockfile=readonly

Originally published at https://bard.sh/posts/terraform-lock-hcl/