You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
Erik Hollensbe a68df68ca3 resource actions for storage to copy images 1 week ago
clients Validations happening across the board now. 1 week ago
cmd Validations happening across the board now. 1 week ago
design move away from goa-defined types; use our own for core resources 1 week ago
gen move away from goa-defined types; use our own for core resources 1 week ago
pkg resource actions for storage to copy images 1 week ago
statik Fixes to re-enable the API and CLI to work as a unit again 1 week ago
ui add the modulo that kinda/sorta replaces a router for now 1 week ago
.gitignore OOPS 1 week ago
.golangci.yml Cleanups from last night's patches 2 weeks ago
LICENSE LICENSEd 2 weeks ago
Makefile Makefile: ignore statik dir until we can figure out consistent generation 1 week ago
README.md Update readme with more information on usage 1 week ago
constants.go some additional work to do here but lots of good emulation agent/systemd changes 2 weeks ago
go.mod move to github 1 week ago
go.sum UI! UI! UI! 1 week ago
spin_apiserver.go Fixes to re-enable the API and CLI to work as a unit again 1 week ago
spin_broker.go move to github 1 week ago
spin_registry.go move away from goa-defined types; use our own for core resources 1 week ago

README.md

spin: a framework/tools for managing VM configurations

spin allows you to manage VMs on your linux bare metal host with ease. Powered by qemu and systemd, it stands upon reliable technology providing its own framework for applying configuration in a safely concurrent, idempotent way, allowing you to perform many small operations on VMs in a quick and efficient way.

In short, we do the high level stuff and leave the big iron tools doing what they do best.

spin is fully backed by a openapi specification for its API calls, from the high level to the blow-your-foot-off calls. Generate your own, or check out our clients directory for a good set of golang ones.

Installation and Usage

For installations, we only support "development mode" at the moment. For a quick start, try this script on for size. You will need the following tools to build the binaries:

Most other things will be installed by the make install-deps task automatically.

#!/usr/bin/env bash

go get -d github.com/erikh/spin
cd $GOPATH/github.com/erikh/spin
make install-deps
make servers
make install-local

Binaries will be in bin/.

To interact with the spin tool (which has help; try spin help), try the following ideas:

(please note the servers must be running, provided by make servers)

# these first few steps are necessary to create vms for now, soon this will not be
mkdir -p ~/.config/spin/images/test

# first argument is the name of the volume, second is the path to the volume's files
spin-registry message storage volume create test ~/.config/spin/images/test

# the second argument (`test`) here is the volume name provided above. the
# machine's image will be put in this directory under the name `my_cool_image`.
spin vm create --cdrom ~/path/to/some.iso my_cool_image test
1

# the id above is the id of the vm newly created; it can be started like so:
spin start 1

# to access it, you can get a console by starting the console server and
# viewing a specific console (will open a link in your browser):
spin serve &
spin view 1

# stop and shutdown have a distinction; stop will force terminate through
# systemd if shutdown doesn't succeed; shutdown will merely try to stop it
# through normal ACPI shutdown signals.
spin shutdown 1
spin stop 1

##
# some other commands:
##
spin vm list              # lists all vms by id
spin vm image list 1      # lists attached devices to my_cool_image
spin vm image detach 1 1  # detaches cdrom, index 1 on my_cool_image

Run make stop-servers to stop the servers when you are done playing! :D

Development

Just some notes:

goa gen is done on each make test run, that includes the autotester, so you can use it to refactor designs fairly quick.

golangci-lint is required to run the tests. make install-deps to install it and reflex.

make autotest will start an autotester using reflex. It's very handy!

The tests are currently pretty safe to run, they don't generate in any place other than /tmp and the project directory. .gitignore is programmed properly, too. test and autotest leverage the golang test cache for faster response time, but you can make test-all to force a run of all tests.

Architecture

The architecture is a mix of the following technologies:

  • golang is ... you know what golang is.
  • goa is a framework for designing REST and GRPC APIs.
  • bbolt is a key/value database system similar to LMDB, just for Golang.

And it contains the following sub-components:

  • spin-broker arranges messages so that they are processed in queues monitored by agents. These agents carry out the work of the instructions carried in the queue.
  • spin-registry holds the values of entities. Soon, this will include journalling the changes of entities.
  • spin-apiserver is the front API (the "brains") that orchestrates the interaction between the registry, broker and the user.

Author

Erik Hollensbe github@hollensbe.org