Eipmap

Elastic IP

Manage Elastic IP associations as code with a Ruby DSL

Manages: AWS Elastic IP Addresses
Language: Ruby
Package: eipmap
CLI: eipmap
Config file: EIPfile

The upstream repository is archived and has seen no activity since 2017; pin your gem version and test against your aws-sdk before relying on it.

EIPfile

domain "standard" do
  ip "54.256.256.1"
  ip "54.256.256.2", :instance_id=>"i-12345678"
end

domain "vpc" do
  ip "54.256.256.11", :network_interface_id=>"eni-12345678", :private_ip_address=>"10.0.1.1"
  ip "54.256.256.12", :network_interface_id=>"eni-12345678"
  ip "54.256.256.13"
end

In short

Eipmap is a small command-line tool that manages AWS Elastic IP associations as code. You keep the mapping of each EIP to its instance or network interface in a Ruby file called an EIPfile, then apply it. It exports current associations, shows a dry-run, and re-associates idempotently.

What is Eipmap?

Eipmap is a small tool that manages AWS Elastic IP associations as code. You declare which EIP points at which instance or network interface in a Ruby file called an EIPfile. The eipmap command compares the file with reality and re-associates addresses to match.

Elastic IPs are the kind of config that lives in someone's head. Which address points at which NAT instance? Which one is whitelisted by a partner? What must never move? When an association is changed by hand during an incident, there is no record. Eipmap turns the whole map into a version-controlled file where every re-association is a reviewable diff. That is codenization for your public addresses.

The EIPfile can map an address to:

An EC2 instance by instance id
A network interface, with an optional private IP
Either standard (EC2-Classic) or VPC domains

It is a deliberately narrow tool: one file, one job. It pairs naturally with Piculet for security groups and Kelbim for Classic load balancers.

Key facts

Manages the Elastic IP to target mapping, not the addresses themselves.
Every association lives in one EIPfile kept in Git.
Maps EIPs to instances or network interfaces, with optional private IP.
--allow-reassociation guards against accidental IP takeovers.
Dry-run shows which addresses would move before anything changes.
Archived since 2017; VPC use still works with pinned versions.

Illustration: AWS Elastic IP Addresses managed as code with Eipmap

Getting started

Install and run Eipmap

Install

Install the eipmap gem (Ruby required).

$ gem install eipmap

Export current state

Pull the live Elastic IP configuration into a EIPfile.

$ eipmap -e -o EIPfile

Dry-run, then apply

Preview the diff, then apply the change for real.

$ eipmap -a --dry-run

Eipmap follows the export, review, apply loop in its simplest form. Run eipmap -e to export every Elastic IP and its current association into one file, and commit it. For many teams this is the first full inventory of their public addresses they have ever had. It is the same export, review, apply workflow the other codenize tools use.

To move an address, say repointing an EIP from an old NAT instance to its replacement, edit the EIPfile in a branch and open a pull request. eipmap -a --dry-run prints the exact associations that would change. Repointing a public IP is instantly visible to the outside world, so that preview is your safety net. Add --allow-reassociation when an address must move off its current target. After review, eipmap -a applies the map idempotently.

Pro tip

Grep a fresh export for addresses with no instance or interface. Those are unassociated Elastic IPs quietly costing money, so release them or note why they are reserved.

Capabilities

What Eipmap can do

Export current associations

eipmap -e captures every Elastic IP in the region and what it is attached to. You get an instant, greppable list of your public addresses.

Dry-run diffs

eipmap -a --dry-run shows which addresses would be associated, moved, or released before anything changes. That matters when the resources are production IPs.

Idempotent apply

Applying the same EIPfile twice makes no further changes. Eipmap only acts on the difference between the file and live state, so runs are safe to repeat.

Instance and ENI targets

The DSL maps EIPs to instances by :instance_id, or to interfaces by :network_interface_id, with an optional :private_ip_address. It covers both standard and VPC domains.

Controlled re-association

The --allow-reassociation flag explicitly permits moving an address already attached elsewhere. Accidental IP takeovers cannot happen silently.

In practice

When teams reach for Eipmap

Documenting whitelisted addresses

When partners whitelist your EIPs, moving the wrong one breaks integrations. An EIPfile records exactly which IP serves which role, and every re-association goes through review first.

Blue/green cutover of a public IP

Repointing an EIP from the old instance to the new one is the cutover for many classic setups. With Eipmap that switch is a one-line diff, previewed with --dry-run and applied with --allow-reassociation, with an obvious revert path in Git.

Auditing unused Elastic IPs

Unassociated EIPs cost money and pile up quietly. The export makes them visible as addresses with no instance or interface, so teams can release them or document why they are kept.

FAQ

Eipmap questions, answered

What exactly does Eipmap manage?

It manages the association between Elastic IP addresses and their targets: EC2 instances or network interfaces, optionally a specific private IP on an interface. You define the desired mapping in a DSL and Eipmap updates AWS to match.

How do I start with an existing account?

Run eipmap -e -o EIPfile to export the current mapping without changing anything, and commit the file. After that, edit the EIPfile, check eipmap -a --dry-run, and apply with eipmap -a.

What does --allow-reassociation do?

By default, moving an EIP that is already attached to another resource is blocked. Passing --allow-reassociation tells eipmap, and the EC2 API, that taking the address from its current target is intentional. It is a useful guard against accidental moves.

Is Eipmap still maintained?

No. The codenize-tools repo is archived, with last activity in 2017, and its EC2-Classic 'standard' domain support reflects that era. The tool is small enough to still work for basic VPC use with pinned versions. Terraform's aws_eip and aws_eip_association are the actively maintained alternative.