DEV Community: Heng Lu

How I Built Graft Absorb: Turning Terraform Drift into Code

Heng Lu — Fri, 13 Feb 2026 12:00:00 +0000

In the last post, I introduced Graft—a tool for patching Terraform modules without forking them. I mentioned it was middleware for something bigger. This is that something.

The Problem

Terraform modules should be black boxes. We manage them through input variables, and ideally, we never need to know what's inside. But when drift happens—someone changes a resource in the portal, an external process modifies a tag, a compliance tool enforces a setting—terraform plan exposes the internals. Suddenly you're staring at resource-level changes deep inside a module you didn't write.

The typical response is painful: read through the plan output, find every difference, trace each change back to its source, and manually update configuration files to match the actual state. Even worse, if the module doesn't expose the right variables, there's simply no way to update the configuration to eliminate the drift.

The common workaround is lifecycle { ignore_changes }. But ignoring changes is not the same as managing them. You're telling Terraform to look the other way—which means your code no longer reflects reality. I think recording the actual desired state in code is always better than ignoring changes blindly.

The Idea

What if we could automate this? Read a terraform plan, extract the drift, and generate the code changes needed to make the configuration match reality.

In the ideal scenario, such a tool would trace drift back to module input variables and update them directly. But I found this impractical—the mapping between inputs and resource attributes isn't always straightforward. A module might derive a resource's tags from a combination of multiple variables, local values, and conditional logic. Reverse-engineering that reliably is a dead end.

But Graft already solves the hard part. It can apply changes directly to module resources, bypassing module inputs entirely. So instead of trying to update variables, I can generate a Graft manifest that patches the drifted resources in place.

`graft absorb`

I created a new command—graft absorb—that takes a Terraform plan file as input, analyzes every detected drift, and generates a Graft manifest describing the changes needed to bring configuration in line with actual state.

terraform plan -out=tfplan
terraform show -json tfplan > plan.json
graft absorb plan.json

That's it. The generated manifest is a standard .graft.hcl file. Review it, run graft build, and your next terraform plan should show zero changes.

Multi-layer modules work out of the box. Graft already knows how to navigate nested module hierarchies and apply patches at the correct level. And since the manifest format is just Terraform HCL, it's expressive enough to handle complex changes—attribute overrides, block additions, removals, all of it.

The Hard Part: Indexed Resources

The simple resources with no indexing are easy. The real challenge is count and for_each resources.

Consider a resource with count = 5, where only 2 instances have drifted. I don't want to generate a manifest that overrides all 5 instances. It should target only the drifted ones—and still work correctly when the module updates and the instance count changes.

Attribute Drift

For attributes, I settled on a lookup() pattern:

# count-indexed resources
tags = lookup({
  0 = { environment = "production", owner = "drifttest", project = "graft" }
  1 = { environment = "staging",    owner = "drifttest", project = "graft" }
}, count.index, graft.source)

# for_each-indexed resources
location = lookup({
  "api" = "westus"
  "web" = "centralus"
}, each.key, graft.source)

The map contains only the drifted instances. lookup checks whether the current count.index or each.key has an entry. If it does, the new value is used. If not, graft.source kicks in—referencing the original expression from the module source, leaving un-drifted instances completely untouched.

This is resilient to module updates. If the upstream module adds new instances, they'll fall through to graft.source and behave exactly as the module author intended.

Block Drift

Block-type attributes (like security_rule or os_disk) need a different approach. You can't use graft.source as a fallback for blocks because the original source has static block definitions, not list expressions that dynamic blocks can iterate over.

Instead, graft absorb generates dynamic blocks with lookup() in the for_each:

resource "azurerm_network_security_group" "nsg" {
  _graft {
    remove = ["security_rule"]  # Remove original static blocks
  }

  dynamic "security_rule" {
    for_each = lookup({
      0 = [
        { name = "allow-ssh",   priority = 100, direction = "Inbound", ... },
        { name = "allow-https", priority = 200, direction = "Inbound", ... }
      ]
      1 = [
        { name = "allow-http",  priority = 100, direction = "Inbound", ... },
        { name = "deny-all",    priority = 4096, direction = "Inbound", ... }
      ]
    }, count.index, [])
    content {
      name      = security_rule.value.name
      priority  = security_rule.value.priority
      direction = security_rule.value.direction
      # ...
    }
  }
}

Each key in the lookup map is an instance index (or each.key for for_each resources), and the value is a list of block objects for that instance. The content block uses security_rule.value.attr to reference each attribute.

The fallback here is []—an empty list—not graft.source. This means instances without an entry in the lookup map produce no dynamic block iterations. Combined with _graft { remove = ["security_rule"] }, which strips the original static blocks, the dynamic blocks become the sole source of truth.

For single nested blocks like os_disk, the same pattern applies—the lookup value is just a single-element list:

dynamic "os_disk" {
  for_each = lookup({
    "web" = [{ caching = "ReadWrite", disk_size_gb = 50, storage_account_type = "Premium_LRS" }]
    "api" = [{ caching = "ReadOnly",  disk_size_gb = 64, storage_account_type = "StandardSSD_LRS" }]
  }, each.key, [])
  content {
    caching              = os_disk.value.caching
    disk_size_gb         = os_disk.value.disk_size_gb
    storage_account_type = os_disk.value.storage_account_type
  }
}

Try It

terraform plan -out=tfplan
terraform show -json tfplan > plan.json
graft absorb plan.json        # Generate the manifest
# Review absorb.graft.hcl
graft build                   # Apply patches
terraform plan                # Should show zero changes

The full code and more examples are at github.com/ms-henglu/graft. For a step-by-step walkthrough with a real public module, check the absorb guide.

If you hit edge cases or have ideas for improving the generated output, open an issue.

How I Built Graft: An Overlay Engine for Terraform Modules

Heng Lu — Thu, 05 Feb 2026 07:08:59 +0000

There's a Terraform GitHub issue that's been open for years: people want to customize modules without forking them. Add a lifecycle block. Tweak a tag. Simple stuff.

I understand why Terraform doesn't support this natively—modules are supposed to be black boxes, and breaking the encapsulation is not ideal. But in practice, modules often need tweaks.

I built Graft to solve this. It patches Terraform modules in place—no forks, no merge conflicts.

And honestly, it's a middleware for something bigger I'm working on. But I'll save that for the next post. :)

The Idea

The goal: use declarative Terraform blocks to describe modifications to existing modules. It should:

Modify multi-layer (nested) modules
Work easily with existing modules
Stay compatible when modules update

So I can define a graft manifest like this:

module "network" {
  override {
    # patches to modify the existing module
  }

  module "subnet" {
    override {
      # patches to modify the nested module
    }
  }
}

The nested structure mirrors the module hierarchy. This makes it easy to locate exactly which blocks you want to modify—just navigate down the tree.

First Attempt: Override Files

My first idea was to use Terraform's native override mechanism. If you create override.tf, it merges with your main config. (Official docs)

But override files have serious limitations:

You can't add new blocks—only modify existing ones
You can't delete blocks or attributes

Not enough.

Second Attempt: Enhanced Override Files

Since the graft manifest is processed before Terraform runs, I have more control than native overrides.

Adding new blocks was easy: check the source code, then generate a new file _graft_add.tf in the module directory.

Deleting things required a new approach. The implementation wasn't hard—just parse the manifest and remove matching blocks from the source files. But the design was tricky: how do you express "delete this" in a way that feels native to Terraform?

I introduced a special _graft block:

resource "azurerm_network_security_rule" "allow_all" {
  _graft {
    remove = ["self"]  # Delete the entire resource
  }
}

resource "azurerm_virtual_network" "vnet" {
  _graft {
    remove = ["dns_servers", "tags"]  # Delete specific attributes
  }
}

It looks like regular HCL. It nests inside the resource block you're targeting. It follows Terraform's declarative style. That's what I wanted—something that feels like it belongs in Terraform, even though Terraform itself can't do this.

Referencing Original Values

While testing the override strategy, I ran into an interesting problem with count and for_each resources.

Say a module creates multiple subnets with for_each, and I want to modify just one of them. I can target a specific key:

resource "azurerm_subnet" "main" {
  for_each = var.subnets

  # Only modify subnet1
  service_endpoints = each.key == "subnet1" ? ["Microsoft.Storage"] : ???
}

But what goes in the ???? I need the original value to avoid affecting other subnets. Without knowing what the module originally set, I'd have to hardcode it—or worse, accidentally break the other subnets.

This is where graft.source came from. It references the original value—no matter how complicated the expression is. I don't need to look it up in the module source code.

service_endpoints = each.key == "subnet1" ? ["Microsoft.Storage"] : graft.source

This also solves another frustration with Terraform's native override files: they use shallow merge for attributes. If you want to add one tag, you can't—your override replaces the entire tags map, wiping out the module's defaults.

With graft.source, you can actually merge:

tags = merge(graft.source, {
  "Owner" = "Platform Team"
})

During patching, graft.source gets replaced with the actual original expression. You get true merging—and you don't need to know what the original value was.

The Linker Problem

Now I had patching working. But how do I make Terraform use the patched modules?

My first idea: use an override file to redirect the module source to a local patched copy.

# file: _graft_override.tf
# What I tried to generate
module "network" {
  source = "./.graft/patched-network"
}

It failed immediately.

You can't override source when there's a version constraint:

# Original main.tf
module "network" {
  source  = "Azure/network/azurerm"
  version = "5.3.0"  # ← This kills the override
}

Terraform throws: "Cannot apply a version constraint to module 'network' because it has a relative local path."

And you can't "unset" the version—override files can only add or modify, never delete.

Dead end.

The Breakthrough: Hijacking modules.json

I started digging into how Terraform actually resolves modules.

When you run terraform init, Terraform downloads modules and records their locations in .terraform/modules/modules.json:

{
  "Modules": [
    {
      "Key": "network",
      "Source": "registry.terraform.io/Azure/network/azurerm",
      "Version": "5.3.0",
      "Dir": ".terraform/modules/network"
    }
  ]
}

What if I just changed where Dir points? I tried it manually—edited modules.json, pointed Dir to a local folder with patched code.

It worked. Terraform loaded my patched module while believing it was using the official registry version. No errors. No need to modify main.tf.

I called this the Linker Strategy—like how linkers resolve symbols to addresses, Graft resolves modules to patched directories.

The Scaffold Command

One thing bothered me. Graft's whole point is that you shouldn't need to understand a module's internals—just declare what you want to change.

But when I actually used it, I kept opening module source files anyway. Which nested module contains that resource? What's the hierarchy? Even as the author, I couldn't write a manifest without digging through .terraform/modules.

So I added graft scaffold. It scans your .terraform/modules directory and generates a starter manifest with the full module tree:

$ graft scaffold

[+] Discovering modules in .terraform/modules...
root
├── network (registry.terraform.io/Azure/network/azurerm, 5.3.0)
│   └── [3 resources]
└── compute (registry.terraform.io/Azure/compute/azurerm, 5.3.0)
    ├── [18 resources]
    └── compute.os (local: ./os)
        └── [2 resources]

✨ Graft manifest saved to scaffold.graft.hcl

Simple, but essential. Now users can see the hierarchy at a glance and start writing overrides immediately—without ever opening the module source.

Try It

go install github.com/ms-henglu/graft@latest

The workflow:

terraform init
graft scaffold    # See the module tree, generate starter manifest
# Edit manifest.graft.hcl
graft build       # Vendor, patch, and link
terraform plan    # Your patches are applied

Your main.tf never changes. When the upstream module releases a new version, bump the version, run terraform init && graft build, and your patches are reapplied.

No forks. No merge conflicts.

Check the examples for patterns like overriding values, injecting resources, removing attributes, and adding lifecycle rules.

The full code is at github.com/ms-henglu/graft.

If you try it and hit issues—or have ideas—open an issue. I'd love to hear what breaks.

Happy patching. 🌱