warehouse-13 / hammertime

CLI tool for interacting with Flintlock servers

Hammertime

A very basic CLI tool for interacting with flintlock servers.

(Those of you who know your archaic gun mechanisms will understand the name and no doubt find it hilarious.) (You are welcome.)

This started off as a toy I made quickly to test live flintlock servers. I have kept it around because it makes working with flintlock very straightforward.

It is currently being heavily refactored.

• Flintlock?
• Versioning
• Installation
• Usage
• Development
  • Testing

Flintlock?

Flintlock is a service to manage MicroVMs on bare-metal.

MicroVMs are, as they sound, smaller VMs. Unlike regular VMs, which generally must be prepared to run any kernel, OS, environment with any number of features that a user may end up needing, MicroVMs are stripped down for a purpose. They provide a smaller subset of virtualisation tailored for a specific task (in the case of Flintlock, this is to run Kubernetes nodes). This means they are smaller and "lighter" to run. In a best of both worlds thing: they provide the speed and lower resource allocation of container, and the security of full VMs.

Versioning

Check the release notes for each release to find Flintlock compatibility. Both Flintlock and this tool are in alpha development, thus the API is likely to change often until v1.

Installation

1. Build from source:

   git clone <this or your fork>
   cd hammertime
   make build

2. Get a released binary

3. Install with go: go install github.com/warehouse-13/hammertime@latest

Alias to ht if you like.

Usage

4 commands, very few configuration options. Each command simply spits out the response as JSON so you can pipe to jq or whatever as you like.

# see all options
hammertime --help

# create 'mvm0' in 'ns0' (take note of the UID after creation)
hammertime create

# get 'mvm0' in 'ns0'
hammertime get

# get just the state of 'mvm0' in 'ns0' see below
hammertime get -s

# get
hammertime get -i <UUID>

# get all mvms in `ns0`
hammertime list --namespace ns0

# delete 'bar' from 'foo'
hammertime delete --namespace foo --name bar

# delete
hammertime delete -i <UID>

The name and namespace are configurable, as is the GRPC address. There is the option to create with an SSH key. You can also pass a full json configfile to create, get and delete if you want to override everything (see example.json).

Run hammertime --help for all options.

Development

For a list of all make commands, run make help.

You will need Go version >= 1.18.

Testing

Our tests use ginkgo v2. To install v2 run:

go install github.com/onsi/ginkgo/v2/ginkgo
ginkgo version //should print out "Ginkgo Version 2.0.0"

Tests can then be run with make test.

All new code must be submitted with at least unit tests. All new or changed core features must come with a matching or updated integration test.

hammertime's Issues

Refactor `cli.App` into separate commands

• Command 'builder'
• Each command should be refactored into own file / builder func
• Flag 'builder' for adding flags to commands

Upgrade Ginkgo to v2

Add lint config and lint action

Move `clear` functionality under `delete --all`

I decided almost immediately after merging that I prefer this.

Usage:

# delete all mvms across all namespaces
hammertime delete --all

# delete all mvms in one namespace
hammertime delete --all -ns foo

# delete all mvms in one namespace/name group
hammertime delete --all -ns foo -n bar

The use case

hammertime delete -ns foo -n bar

Will be added in #15

Add `version` subcommand

Add issue and pr templates

Help should print example "getting started commands"

Create a function which builds this and is returned when the help is called.

Add basic auth token option to authenticate against client calls

Flintlock is introducing basic auth, so we need a flag to pass in the token and have the authorization header added to the request metadata.

This has already been implemented in capmvm, so you can take inspiration from that here, the internal/client package being key.

Add git commit template

Ability to `get` mvm with name and/or namespace

A recent api change in flintlock means that individual mvms are retrieved by Uid.

But that is annoying if you don't have the Uid (which is generated on create), so it would be nice to be able to do things with name/namespace again.

# current
hammertime get -i abcdef123456

# new with no args
hammertime get
#-> returns default mvm0 in default ns0

# new with name
hammertime get -n foo
# -> returns foo from default ns0

# new with name and namespace
hammertime get -n foo -ns bar
# -> returns foo from bar

If thing is not found, error is returned.

If there is more than one Uid under the given ns/name combination, the ids are printed with a message saying try again:

$ hammertime get -n foo -ns bar
2 MicroVms found under bar/foo
uid-1-asfhjg uid-2sdfkh

Implementation notes:
Something was added to flintlock which made it possible to list by name/namespace. So do a list and if there is only one, print that out, if there is more than one print out the Uids of all. The user can then run a specific get with the id they want.

Refactor integration tests

• they need to run faster (use table tests?)
• include a second parallel suite to test auth functionality
• remove fakeserver and replace with safety

Add `--quiet/-q` flag for `create` and `delete` commands

In case people don't the json dumped to screen, they can silence it.
I know they could probably > /dev/null, but whatever.
This flag does not need to apply to get or list, because presumably users care about the mvm they are explicitly looking at.

Add remaining tests for `pkg/command/` funcs

Ability to `delete` mvm with name and/or namespace

A recent api change in flintlock means that individual mvms are deleted by Uid.

But that is annoying if you don't have the Uid (which is generated on create), so it would be nice to be able to do things with name/namespace again.

# current
hammertime delete -i abcdef123456

# new with name and namespace
hammertime delete -n foo -ns bar
# -> deletes foo from bar

If thing is not found, error is returned.

If there is more than one Uid under the given ns/name combination, the ids are printed with a message saying try again:

$ hammertime delete -n foo -ns bar
2 MicroVms found under bar/foo
uid-1-asfhjg uid-2sdfkh

Implementation notes:
I believe something was added to flintlock which made it possible to List by name/namespace. So here we can do a list and if there is only one, delete that one, if there is more than one print out the Uids of all. The user can then do a specific delete on the one they want.

bug: A failed `list` returns a really unhelpful error

./hammertime list
2022/02/25 16:33:25 rpc error: code = InvalidArgument desc = invalid request

Add logger

move go paths over to new repo

Delete default name and namespace

We have create and get which default values for ease of use. For delete you currently have to specify uid or name + ns.

It would be good to have a defaulting option to match the others.

# new with no args
hammertime delete
#-> deletes default mvm0 in default ns0

# new with name
hammertime delete -n foo
# -> deletes foo from ns0

When listing, using `--name` without `--namespace` is invalid, should return error

hammertime list -ns ns1 -n mvm1
# valid: make request, print response

hammertime list -ns 1
# valid: make request, print response

hammertime list -n mvm1
# invalid: do not make request, return error

bug: commands hang when server does not exist

Running something like

./hammertime -a 1.2.3.4 delete -i ns0-DELETEME
^C

Just hangs.

It should fail and say that there is no flintlock running at that address/port

Delete with json file

hammertime create --file spec.json
hammertime delete --file spec.json

refactor and add tests

generally needs a tidy up seeing as i am using this more and more

Refactor flintlock client calls into `client` package

• Tidy all client calls into pkg/client.
• Unit tests

---

• Create
• Get
• List
• Delete

Add release action

I can't be uploading all those bins myself

Add github action for running spec

Add a github action that will run the tests and prevent merging if any failures.

Add TLS options to use certs with client calls

Flintlock is about to add this feature, so when it is in we should add to match

See here and here for implementation in capmvm.

bump to go 1.18

Add `create` command

This is the first part of the refactoring and testing Epic: #2

User story:

As a CLI user,
who wants to create a MicroVM through the Flintlock service,
When I:

• Call hammertime create
• With no additional arguments

I see that:

• The command succeeds
• A MicroVM with a default name is created, in a default namespace
• The response of the GRPC call is printed to the terminal in JSON

Scope:

• This is just implementing the create command
• There will be no option to pass in additional flags or configuration
• The endpoint for the server will be defaulted to 127.0.0.1:9090
• All parameters for the API request will be defaulted (see current defaults)

Implementation notes:

• We will be using urfave/cli to build the cli tool
• Flintlock is a GRPC server, so the CLI will need to be a GRPC client
• We will be using ginkgo/gomega for testing (both unit and integration)
• @Callisto13 will do acceptance testing against a running server
• So all integration level testing will need to be against a dummy GRPC server which:
  • is started before integration test runs
  • returns a mocked response (ask @Callisto13 for this)
  • is terminated at the end of the tests

(For an example of a very simple GRPC server and client + testing at all levels, see this. There is also a lot on google.)

option to provide json config

Do not have default ns/name for `list`

AdditionalVolumes support

Flintlock 0.5.0 reintroduced a field to specify a mountpoint for additional volumes.

This probably works out of the box here, but would be good to verify.

One thing which would need to change is the images set on the create spec. The kernel and the modules have been split into separate images, so let's use those here.

Add Integration Tests

Add Integration tests for all commands.

Part of #2

• address flag
• port flag

Create:

• No args #5
• name #5
• namespace #5
• public-key-path #4
• file #4

Get:

• id #5
• state #5
• file #4

Delete:

• id #5
• file #4

List:

• no args #5
• namespace #4

Get/Delete should fail when uid is nil in json spec

Right now if i get/delete an mvm using a json file where uid is not set, there is no error. It just tries to get a mvm where uid: "" which obviously fails.

Hammertime should either:

• Error or
• Go into the name/namespace flow instead
  • if none of these are set then it can error

Get is covered in #22

Blocked on #15

bug: `delete --all` fails

This is because list --all does not work yet. Coming in #17

Add env var to run integration tests against real/other flintlock server

When the SERVER_ADDRESS flag is set (or a flag if preferable), the integration tests will not start the fake server; the given server will be used instead.

Use cases

# will use default port 9090
SERVER_ADDRESS=12.0.0.1

# will use given port 1234
SERVER_ADDRESS=12.0.0.1:1234

Tidy up the README

Remove `mount_point` from Create call Spec

There has been an api change in Flintlock. Includes bump to 0.1.0

Ability to `list` by namespace/name and `--all`

Currently ht only filters list by Namespace. Listing now has more filters, so we should be able to do the following:

hammertime list
# returns everything in all namespaces

hammertime list -ns foo
# returns mvms in ns foo

hammertime list -ns foo -n bar
# returns mvms in foo/bar

hammertime list -n bar
error: required: --namespace