Kanrisuru manages remote infrastructure with plain ruby objects. The goal with Kanrisuru is to provide a clean objected oriented wrapper over the most commonly used linux commands, with a clean command interface, and with any usable output, present that as parsed structured data. Kanrisuru doesn't use remote agents to run commands on hosts, nor does the project rely on a large complex set of dependencies.
Kanrisuru requires ruby 2.5.0
at a minimum.
Add this line to your application's Gemfile:
gem 'kanrisuru'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install kanrisuru
You can find the official documentation https://kanrisuru.com
To connect with Kanrisuru to a remote host, provide the login credentials to instantiate a Kanrisuru::Remote::Host
instance.
host = Kanrisuru::Remote::Host.new(
host: 'remote-host-name',
username: 'ubuntu',
keys: ['~/.ssh/id_rsa']
)
To connect to a host behind a firewall through a jump / bastion host, pass either an instance of another Kanrisuru::Remote::Host, or a hash of host config values
proxy = Kanrisuru::Remote::Host.new(
host: 'proxy-host',
username: 'ubuntu',
keys: ['~/.ssh/proxy.pem']
)
host = Kanrisuru::Remote::Host.new(
host: '1.2.3.4',
username: 'ubuntu',
keys: ['~/.ssh/id_rsa'],
proxy: proxy
)
host.whoami
'ubuntu'
host.env['VAR'] = 'world'
result = host.echo('hello $VAR')
result.success?
true
result.to_s
'hello world'
command = Kanrisuru::Command.new('wc')
command << '/home/ubuntu/file1.txt'
host.execute_shell(command)
result = Kanrisuru::Result.new(command) do |cmd|
items = cmd.to_s.split
struct = Kanrisuru::Core::File::FileCount.new
struct.lines = items[0]
struct.words = items[1]
struct.characters = items[2]
struct
end
The Kanrisuru::Result
class will only run the parsing block if the command run on the remote host was succeful. The final line will be used to build the result object to be read easily. This instance will also dynamically add getter methods to read the underlying data struct for easier querying capabiltiies.
result.success?
true
result.lines
8
result.characters
150
result.words
85
Kanrisuru can manage multiple hosts at the same time with the Kanrisuru::Remote::Cluster
.
cluster = Kanrisuru::Remote::Cluster.new({
host: 'remote-host-1',
username: 'ubuntu',
keys: ['~/.ssh/remote_1_id_rsa']
}, {
host: 'remote-host-2',
username: 'centos',
keys: ['~/.ssh/remote_2_id_rsa']
}, {
host: 'remote-host-3',
username: 'opensuse',
keys: ['~/.ssh/remote_3_id_rsa']
})
host = Kanrisuru::Remote::Host.new(host: 'remote-host-4', username: 'rhel', keys: ['~/.ssh/remote_4_id_rsa'])
cluster << host
Benchmark.measure do
cluster.each do |host|
puts cluster.pwd
end
end
# => 0.198980 0.029681 0.228661 ( 5.258496)
cluster.parallel = true
Benchmark.measure do
cluster.each do |host|
puts cluster.pwd
end
end
# => 0.016478 0.007956 0.024434 ( 0.120066)
cluster.whoami
[
{
:host => "remote-host-1",
:result => #<Kanrisuru::Result:0x640 @status=0 @data=#<struct Kanrisuru::Core::Path::UserName user="ubuntu"> @command=sudo -u ubuntu /bin/bash -c "whoami">
},
{
:host => "remote-host-2",
:result => #<Kanrisuru::Result:0x700 @status=0 @data=#<struct Kanrisuru::Core::Path::UserName user="centos"> @command=sudo -u centos /bin/bash -c "whoami">
},
{
:host => "remote-host-3",
:result => #<Kanrisuru::Result:0x760 @status=0 @data=#<struct Kanrisuru::Core::Path::UserName user="opensuse"> @command=sudo -u opensuse /bin/bash -c "whoami">
},
{
:host => "remote-host-4",
:result => #<Kanrisuru::Result:0x820 @status=0 @data=#<struct Kanrisuru::Core::Path::UserName user="rhel"> @command=sudo -u rhel /bin/bash -c "whoami">
}
]
cluster.each do |host|
case host.os.release
when 'ubuntu', 'debian'
host.apt('update')
when 'centos', 'redhat', 'fedora'
host.yum('update')
when 'opensuse_leap', 'sles'
host.zypper('update')
end
end
After checking out the repo, run bin/setup
to install dependencies.
To test kanrisuru across various linux distros, update your local /etc/hosts
file to create an alias to the local virtual machine with that distro type. You can also set the host alias to the localhost machine.
To select which hosts to run rspec across, prepend the command line or export the variable while running rspec.
HOSTS=ubuntu,debian,centos rspec
This will run tests on the ubuntu, debian and centos instances.
Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this 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.
Bug reports and pull requests are welcome on GitHub at https://github.com/avamia/kanrisuru. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Kanrisuru project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.