Roadworker

Route 53

Manage Route 53 DNS records as code with a Ruby DSL

Manages: Amazon Route 53
Language: Ruby
Package: roadworker
CLI: roadwork
Config file: Routefile

Routefile

hosted_zone "winebarrel.jp." do
  rrset "winebarrel.jp.", "A" do
    ttl 300
    resource_records(
      "127.0.0.1",
      "127.0.0.2"
    )
  end

  rrset "winebarrel.jp.", "MX" do
    ttl 300
    resource_records(
      "10 mx.winebarrel.jp",
      "10 mx2.winebarrel.jp"
    )
  end
end

In short

Roadworker is a command-line tool that manages Amazon Route 53 DNS as code. You keep your zones and records in a Ruby file called a Routefile, then apply it to update Route 53. It exports live DNS, shows a dry-run diff, and applies changes idempotently.

What is Roadworker?

Roadworker manages Amazon Route 53 as code. You write your DNS in a Ruby file called a Routefile. The roadwork command then makes Route 53 match that file.

Editing DNS by hand is risky. One wrong record can take a site offline, and the console keeps no history of who changed what. Roadworker puts your DNS in version control instead. Every change gets a diff and a dry-run before it goes live. That is the core idea behind codenization.

The Routefile can hold your whole DNS setup:

Record sets like A, MX, CNAME, and TXT records
Routing policies such as weighted and failover
Health checks and private hosted zones tied to a VPC

It suits teams that want safe, repeatable DNS without a heavy framework. Roadworker started in the codenize-tools family and is now maintained by Cookpad, like its sibling Miam for IAM permissions.

Key facts

Manages Amazon Route 53 DNS zones and records as code.
All config sits in one Routefile tracked in Git.
Handles weighted routing, failover, health checks, and private hosted zones.
A built-in test mode checks that records really resolve as written.
Re-running a dry-run works as drift detection for console edits.
Still maintained by Cookpad, so it is safe for active use.

Illustration: Amazon Route 53 managed as code with Roadworker

Getting started

Install and run Roadworker

Install

Install the roadworker gem (Ruby required).

$ gem install roadworker

Export current state

Pull the live Route 53 configuration into a Routefile.

$ roadwork -e -o Routefile

Dry-run, then apply

Preview the diff, then apply the change for real.

$ roadwork -a --dry-run

Roadworker uses a simple loop: export, review, dry-run, apply. Start by running roadwork -e to dump your live zones into a Routefile. Add --split for one file per zone. Commit it to Git so your DNS has a history from day one. This is the classic export, review, apply workflow.

After that, changes happen in the file. Edit the Routefile in a branch and open a pull request. Run roadwork -a --dry-run to see which records would be added, changed, or removed. Once it looks right, roadwork -a applies it. Running apply again does nothing, since Roadworker is idempotent. You can also run roadwork -t to query real nameservers and confirm records resolve as declared.

Pro tip

Run roadwork -e on a schedule and diff it against your committed Routefile. Any difference means someone changed DNS in the console, so you catch drift early.

Capabilities

What Roadworker can do

Export existing zones

Run roadwork -e to dump your live zones into a Routefile. Add --split for one file per zone. You can adopt Roadworker without recreating anything.

Dry-run diffs

roadwork -a --dry-run prints exactly which record sets would be created, changed, or deleted. Nothing moves until you approve the plan.

DNS test mode

roadwork -t queries real nameservers and compares the answers to your Routefile. It acts as a built-in acceptance test for your zones.

Templates and Ruby logic

Define reusable record patterns with template and include_template. Plain Ruby lets you generate repetitive records in a loop.

Zone filtering

The --target-zone and --exclude-zone options accept regular expressions. That lets you work on a subset of zones in busy accounts.

Health checks and routing policies

The DSL covers HTTP, TCP, calculated, and CloudWatch health checks. It also handles weighted and failover routing and private hosted zones.

In practice

When teams reach for Roadworker

Code review for DNS changes

Every record change goes through a pull request, not a console click. Reviewers see the exact rrset diff. The dry-run confirms what will happen before merge, catching typos in ALIAS targets and TTLs.

Managing many zones at scale

Platform teams often run hundreds of zones in one account. With --split, each zone gets its own file, and --target-zone works on a subset. Templates keep SPF and DKIM records consistent across domains.

Auditing and migrating existing DNS

An export gives you a complete, greppable snapshot of Route 53. Teams use it to find stale records, compare environments, or plan a zone move between accounts.

CI-verified DNS deployments

Run the dry-run in CI on every pull request, then apply on merge. After that, roadwork -t queries real nameservers to prove the records resolve as declared.

FAQ

Roadworker questions, answered

How do I start using Roadworker with an existing Route 53 setup?

Run roadwork -e -o Routefile to export everything Route 53 serves today. Commit that file to Git. From then on, edit the file and apply it. No records need to be recreated one by one.

Will Roadworker delete records that are not in my Routefile?

Yes. Roadworker is declarative, so the Routefile is the source of truth. Records missing from it are removed on apply. Use the ignore and ignore_under directives to leave some records unmanaged, and always check the dry-run first.

What does the test mode do?

roadwork -t sends real DNS queries and compares the answers to your Routefile. You can point it at specific resolvers with --nameservers. It is handy in CI after an apply, to confirm changes have propagated.

Is Roadworker still maintained, and how does it compare to Terraform?

Yes. Cookpad took ownership after the original codenize-tools organization was archived, and the repo is still active as of 2026. Terraform can also manage Route 53. Roadworker is lighter and DNS-only, with no state file, since the live zone is the state. See our comparison of codenize-tools and Terraform for the trade-offs.

Does Roadworker support weighted records and health checks?

Yes. The DSL covers weighted, failover, and other routing policies, plus HTTP, TCP, calculated, and CloudWatch health checks, and private hosted zones. One known limit: it cannot update the TTL of two or more identically weighted A records with different SetIdentifiers after creation.