The vop is a scripting framework.
It organizes ruby scripts as commands living in plugins, defines and manages services, and can be accessed from the command line or a web interface.
Installation
as a gem:
$ gem install vop
from source
- checkout the following repos from github.com/virtualop: vop, plugins, bundle
- install Ruby >= 3.1.2
- run
bundle install
in all working copies
Usage
Call vop
to start the shell.
Syntax
Plugins
Minimally, a plugin is a folder containing a file called "<name>.plugin". An empty file will do.
optional:
description "really nice plugin, this one"
auto_load false # default is true
dependencies:
depends_on :other_plugin
depends_on [ :many, :other, :plugins ]
hooks:
hook :before_execute do |payload|
request = payload[:request]
end
hook :after_execute do |payload|
request = payload[:request]
response = payload[:response]
end
config:
config_param "foo" [, { options }]
config_param! "snafoo" [, { options }]
accessing plugin config inside command:
run do |plugin|
plugin.config["foo"]
end
Commands
...are loaded from the commands
folder in a plugin.
Minimally, a command needs only a run block:
run { 42 }
Also, you can use any of these:
description "Roses are red."
read_only # => cacheable
dont_log
A command can define parameters
param "snafoo" # optional
param! "snafoo" # mandatory
param! :snafoo # mandatory entity
param syntax:
param[!] ( "name" | :entity ) [, {option: value}]
full example:
param! "foo",
description: "it's the foo.",
multi: true,
default: [ "snafoo", "footoristic", "foofoo", "foolosophy" ],
default_param: true,
lookup: lambda { |params| %w|string array| }
to access param values, use the params
hash or named block variables:
param "foo"
param "not_really"
run do |params, not_really|
puts params["foo"] unless not_really
end
entity parameters are resolved from the specified key to the entity:
param :machine
run do |machine|
puts machine.name
end
There is special handling in place for block parameters.
Declare one with
block_param
or
block_param!
and a block can be passed to the command like this:
@op.foo do
# whatever you need to do
end
From inside your command, you can access the block through the parameter called block
.
contribute:
contribute to: "other_command" do |params|
end
collect contributions:
@op.collect_contributions(
command_name: "other_command",
raw_params: {}
)
show (display options for shell output):
show columns: ["name", "number"]
show sort: false
show display_type: :raw
display_type
can be any of:
:data
:raw
:table
:list
:hash
(see shell/formatter.rb
)
Services
Plugin folder: services
install one or multiple OS packages:
deploy package: <foo>
deploy package: [ <foo>, <bar>, <baz> ]
install a virtualop service:
deploy service: "plugin.service"
deploy configuration from a template:
deploy template: "foo.conf.erb",
to: "/etc/foo/conf.d/foo.conf"
install (configuration for) a debian package repository:
deploy repository: {
alias: "funny-name",
url: "https://package.repository.somewhere.xxx",
dist: "stable/",
key: "https://download.somewhere.xxx/the.gpg.key"
}
run arbitrary vop or ruby code during deployment of a service:
deploy do |machine|
end
Entities
Each entity is a file in the /entities
subfolder of a plugin.
A minimal entity is an array of hashes, each with a unique "name" attribute:
entity do
[
{
"name" => "foo"
}
]
end
Instead of "name", a differing key attribute can be specified with key
:
key "path"
entity do
[
{
"path" => "/bin/false"
}
]
end
The on
keyword allows to stack entities onto another, e.g. the log
entity living on a machine:
key "path"
on :machine
entity do |machine|
# ...
end
A stacked entity (or rather, the list command generated from the entity) automatically has a parameter for the entity it is stacked on - in the log example:
>> logs?
logs
syntax:
logs <machine>
parameters:
machine
Development
required dependencies
- (to checkout sources: git)
- ruby + headers (e.g. packages
ruby
andruby-dev
on Ubuntu) - bundler (
gem install bundler
)
setup
After checking out the repo, run bin/setup
to install (gem) dependencies.
Then, run bundle exec rake spec
to run the tests.
You can also run bin/console
for an interactive prompt that will allow you to experiment.
To start the vop from the checked out sources, set the environment variable VOP_DEV_MODE
to any value, e.g. like this:
export VOP_DEV_MODE=1
and then run exe/vop
.
packaging
To install the vop from source as a gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/virtualop/vop.