How To

Use files, branches, or tags for mod dependencies

Install a mod dependency locally, iterate on it rapidly, then share it to others who can install from a remote branch or tag.

Turbot Team
5 min. read - May 16, 2024

Suppose you're developing a Powerpipe mod, called my-aws-insights, to visualize AWS resources. It includes a dashboard for S3 buckets, with two charts and a table.

The source code for the mod includes HCL widgets to define the charts and the table, and also includes the queries that fill those widgets with data.

Now suppose you'd like to source those queries from a separate mod. A couple of new features in Powerpipe — installing from the local filesystem, or from a remote branch — make it much easier to manage that separation of concerns.

Install and use a local dependency

Our mod lives in the local directory ~/my-aws-insights. Now we'll create a new directory, ~/aws-queries, initialize it with powerpipe init, copy the queries into it, and remove them from my-aws-insights.

Then we'll adjust the charts and table in my-aws-insights to refer to the queries in the aws-queries mod.

After completing the search-and-replace, query references like query.s3_bucket_month_created are fully-qualified with the name of the dependency (aws_queries.query.s3_bucket_month_created). Now we can install the mod from the local filesystem.

$ pwd
/home/jon/my-aws-insights
$ powerpipe mod install ~/aws-queries
Installed 1 mod:
local
└── /home/jon/aws-queries

The dashboard runs as before, but sources the queries from this new library mod.

Install from a branch

We can now iterate rapidly on this local library mod but, at some point, we'll want to move it to GitHub so others can use it. So let's do that.

First we uninstall the local mod.

powerpipe mod uninstall `~/aws-queries`

Then we reinstall from GitHub. If the repo is tagged with a semver constraint, this command installs the latest version.

powerpipe mod install github.com/judell/aws-queries

And if it isn't tagged? No problem! You can now also install from a branch.

powerpipe mod install github.com/judell/aws-queries#main

Again the dashboard runs as before, sourcing queries from the mod that was installed from GitHub. Now others can depend on the library mod, perhaps even on alternate or experimental versions. And as we continue to evolve the library mod, we can switch back to a local install to rapidly iterate on it.

Flexible update strategies

You've also now got a lot more flexibility when installing or updating mods, using the --pull argument to specify various update strategies.

See it in action

Reuse, remix, refactor

You could always reuse and remix Powerpipe mods. Now it's easy to refactor them too, so you can extract shared components into dependent mods that you can rapidly develop and test, and easily share. If you haven't tried writing your own mods, now's a great time to get started. Go build something useful, then tell us about it!