lsvpc: Command Line Listing For Your AWS VPCs

As AWS proliferates further in the industry, more people are going to need to interact with AWS EC2, and these people are not likely to be developers who can craft their own custom interfaces out of the AWS SDK. The AWS EC2 management tools, such as the AWS Web Console, awscli, and the AWS SDK are relatively clunky and verbose, and are difficult for admins to use and navigate.

The entire user interface to AWS is dictated by the underlying SDK functions. As an example, EC2 has a DescribeSubnets() method. This function simply lists all of the subnets that exist in the region. Each subnet knows what VPC it's in, what its CIDR is, and what AZ it's in, but not a whole lot else. You would have to call other methods and correlate the subnet id with other resources to get a bigger picture about what's actually in the subnet. Likewise, in the AWS Web Console for EC2, there is a subnets page. This page directly represents the results of the DescribeSubnets() method, and does not provide much more information. The Web Console is mostly a web interface for running low level AWS SDK commands, with a little garnishing.

A user trying to quickly inspect the architecture of a VPC will need to either click through many Web Console pages in order to correlate all of the resource IDs and eventually build out a diagram of what's happening in the VPC, or otherwise write custom, nontrivial code which does that work. There exists Infrastructure as Code (IaC) and 3rd party management tools, but there's barriers to entry on those and IaC only really tells you about infrastructure that the IaC is directly managing (and we all know that non-IaC-managed infrastructure always manages to creep into deployments).

What's missing is a simple command line utility that quickly displays a terse layout of a VPC to rapidly reason about. That is why I wrote lsvpc.

A simple, fast tool to give simple information

Every time I interact with EC2, I want to do an ls on current state of the VPC. I always want basic visibility into a network and to engage with what's actually deployed. I don't need to know every last detail of every instance, I just need to know if an instance is in the right subnet, the right AZ, named correctly, addressed correctly, that the subnet default route points to the right destination, and that the VPC is configured with the right gateway.

I may want to dig in and get the volume and ENI layout of each instance, and get the security group configuration of resources on a VPC. I want quick visibility on how endpoints have been configured and visibility on whether VPC peering hasbeen set up, and where that peering points to and from (please, dear God, do not start peering VPCs in new deployments, Transit Gateways (TGW) are the way).

Most importantly, I want this information in a terse, quickly readable format, and for the information to be retrieved as quickly as possible.

Enter lsvpc

lsvpc is a command line utility written in Go that makes concurrent requests to more than a dozen EC2 SDK methods, stitching together the information it receives into a terse, hierarchical structure. It's fast, retrieving this information and printing its results in generally 1-3 seconds. It uses ANSI colors. It represents VPC structure with indentation. Written in Go, it runs on basically anything that matters. It even spits out JSON!. It is simple and focused in scope.

Most importantly, it only lists resources that are actually engaged and used in a VPC. If a route table isn't in use, it doesn't show up. If a volume or security group isn't attached, it's not going to clutter the UI.

lsvpc uses the same AWS credentials as your aws-cli. My preferred setup is to set the AWS_PROFILE environment to the appropriate profile name. lsvpc defaults to a terse readout, and can be passed a -v flag in order to produce a more verbose readout:

The speed at which lsvpc operates also gives it the ability to be used in live monitoring. Running the command, watch -n 5 -c lsvpc -color will produce a live-updating, colorful ncurses-based display of the current state of the VPCs in the region, which is particularly handy when watching IaC deployments take place in a VPC.

One extremely common workflow I perform is when needing to connect to an instance using SSM Session Manager. I simply run lsvpc to display instance IDs, copy the instance ID of the instance I want to connect to, type out aws ssm start-session --target and paste the instance ID at the end; now I'm connected to an arbitrary instance over a shell without clicking through a dozen pages.

Future Development

lsvpc is a quick, simple tool for displaying the layout of a VPC, turning what would usually be a nontrivial task of hunting and poking through the Web Console into a 2 second invocation. It's under continual development and I'm regularly adding new features and ideas to it. It currently has preliminary support for exporting the VPC layout information as JSON, and there is planned future support for the filtering of results. There are also some plans in the works to create similar utilities for AWS serverless resources.

I hope you find this tool to be as useful as I have found it to be!

Have a look at our latest releases for binaries, and our GitHub page for the source. Issues and pull requests are welcome!