kanrisuru 0.16.9 → 0.16.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffeb83d91c285f197ed82ea9faf1f2d4ed95f8394cd383354eebed18dc6ace91
-  data.tar.gz: 5b4d615c7754eb2d520f175d77cecafb774e2d841d9077c23b8ccb39d7fde059
+  metadata.gz: 247c662cf0cedccfd41d702e372cc536958fbfd16c583643201e13e528c3c049
+  data.tar.gz: 8d6256b6b5dfcf84793851432e0dfedfd352222bebb04bc530bb15bc9cdcd0d5
 SHA512:
-  metadata.gz: eac9603360b49938e188cf36babef60f57106091f93d5ad1f7e74a45e523b5f235463653ea305b34d700c728382707496662212c83e59ad629f954c695644f33
-  data.tar.gz: 2b6214a7c61f3273f226290ad87fbf3da0eb5f401a9b6923a45779beca89b1ba7e5cbece32247136fba5b24eb8c4ea38015fc136e752d3508d62845ba24e70ba
+  metadata.gz: 31bde2ec4894d4e6962ff99b438b67502687446918d59180693d11275e25944c1af1e22ad923e799c4208e7fff62ad93e9867082765b956d213b12eb5a950092
+  data.tar.gz: b69992182e95c7f3cf3061cd4f25d875ff6095ee7e18580a39f24a6be8c6978401d9023e55be01bbb0aac92b74ec904a016abdf60a4302c9fc1cfdd32df276b2

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## Kanrisuru 0.16.13 (January 01, 2022) ##
+*  Add `non_unique` and `system` opts to `create_group` command
+
+## Kanrisuru 0.16.12 (January 01, 2022) ## 
+*  Update date ranges for 2022 on license files.
+*  Add unit test case for `Kanrisuru::Logger`.
+
+## Kanrisuru 0.16.11 (December 28, 2021) ##
+*  Add functional and integration test cases for the `Kanrisuru::Remote::Cluster` class.
+*  Allow for passing a command instance into `execute` and `execute_shell` on a cluster instance, by deep copying a command object. 
+
+## Kanrisuru 0.16.10 (December 28, 2021) ##
+*  Add `iname` and `iregex` params to `find` command.
+
 ## Kanrisuru 0.16.9 (December 27, 2021) ##
 *  Use cp intead of mv for recurisive dir overwrite on upload command.
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020-2021 Avamia, LLC
+Copyright (c) 2020-2022 Avamia, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -15,15 +15,11 @@
   <img src="https://img.shields.io/codeclimate/maintainability/avamia/kanrisuru?style=flat-square" alt="Code Climate maintainability" />
 </p>
 
-Kanrisuru (manage) helps you remotely control infrastructure using Ruby. This is done over SSH. I'm working on building up some basic functionality to help quickly provision, deploy and manage a single host or cluster of hosts.
+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.
 
-The idea behind this project is not to replace the numerous other projects to manage your infrastrucutre, however, I've found there usually meant to be a standalone project that have their own ecosystem. With Kanrisuru, you essentailly plug the library directly into your ruby project.
+## Getting Started
 
-At this point, Kanrisuru doesn't use a DSL, or offer idempotency, and while that may be added later on, the goal with this project is to expose helpful ways of managing your remote infrastructure with plain ruby in a procedural manner. The realization I had was when trying to deal with other open source projects, you either had to deal with a different language than ruby, use agents on remote hosts, or deal with a complex library that is meant to act in a declarative manner.
-
-If you want to dynamically interact with a host, eg: If you need to dynamically scale your infrastructure by continually monitoring specific stats from a centralized system, Kanrisuru can help you accomplish this.
-
-## Installation
+Kanrisuru requires ruby `2.5.0` at a minimum.
 
 Add this line to your application's Gemfile:
 
@@ -43,48 +39,128 @@ Or install it yourself as:
 $ gem install kanrisuru
 ```
 
-## Usage
-Run basic commands you would have access to while running on a remote host or on a cluster of hosts.
+## Documentation
+You can find the official documentation https://kanrisuru.com
 
+## Usage Guide
 ### Host
+To connect with Kanrisuru to a remote host, provide the login credentials to instantiate a `Kanrisuru::Remote::Host` instance.
+
+```ruby
+host = Kanrisuru::Remote::Host.new(
+  host: 'remote-host-name', 
+  username: 'ubuntu', 
+  keys: ['~/.ssh/id_rsa']
+)
+```
+
+#### run a simple echo command on the remote host
+```ruby
+host.env['VAR'] = 'world'
+result = host.echo('hello $VAR')
+result.success?
+true
+
+result.to_s
+'hello world'
+```
+
+#### build a custom command
+```ruby
+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.
+
 ```ruby
-host = Kanrisuru::Remote::Host.new(host: 'host', username: 'ubuntu', keys: ['~/.ssh/id_rsa'])
-result = host.whoami   
-result.to_s						# => 'ubuntu'
+result.success?
+true
 
-result = host.pwd
-result.path 					# => /home/ubuntu 
+result.lines
+8
+
+result.characters
+150
+
+result.words
+85
 ```
 
-### Cluster 
+### Cluster
+Kanrisuru can manage multiple hosts at the same time with the `Kanrisuru::Remote::Cluster`.
+
+#### To instantiate a cluster, add 1 or more hosts:
 ```ruby
 cluster = Kanrisuru::Remote::Cluster.new({
-  host: 'host1', username: 'ubuntu', keys: ['~/.ssh/id_rsa']
+  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: 'host2', username: 'alice', keys: ['~/.ssh/id_rsa']
+  host: 'remote-host-3',
+  username: 'opensuse',
+  keys: ['~/.ssh/remote_3_id_rsa']
 })
-
-cluster.whoami   # => {host: 'host1', result: 'ubuntu'}, {host: 'host2', result: 'alice'}
-cluster.pwd      # => {host: 'host1', result: '/home/ubuntu'}, {host: 'host2', result: '/home/alice'}
-
-cluster.each do |host|
-  host.pwd.path  # => /home/ubuntu
-end
 ```
 
-### Host or Cluster with underlying command
+#### You can also add a host to a cluster that's already been created 
 ```ruby
-host = Kanrisuru::Remote::Host.new(host: 'host1', username: 'ubuntu', keys: ['~/.ssh/id_rsa'])
+host = Kanrisuru::Remote::Host.new(host: 'remote-host-4', username: 'rhel', keys: ['~/.ssh/remote_4_id_rsa'])
 
-command = Kanrisuru::Command.new('uname')
-host.execute(command)
+cluster << host 
+```
 
-command.success? #=> true
-command.to_s  #=> Linux
+Kanrisuru at this point only runs commands sequentially. We plan on creating a parallel run mode in a future release.
 
-cluster = Kanrisuru::Remote::Cluster.new(host, {host: 'host2', username: 'alice', keys: ['~/.ssh/id_rsa']})
+#### To run across all hosts with a single command, cluster will return a array of result hashes
+```ruby
+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.execute('uname') #=> {host: 'host1', result: 'Linux'}, {host: 'host2', result: 'Linux'}
+#### You can also access each host individually to run a command conditionaly within an iterable block
+```ruby
+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
 ```
 
 ## Development

data/lib/kanrisuru/command.rb

@@ -7,6 +7,7 @@ module Kanrisuru
 
     def initialize(command)
       @valid_exit_codes = [0]
+
       @raw_command = command
       @raw_result = []
     end

data/lib/kanrisuru/core/find/commands/find.rb

@@ -36,6 +36,7 @@ module Kanrisuru
 
         command.append_arg('-path', opts[:path])
         command.append_arg('-name', opts[:name])
+        command.append_arg('-iname', opts[:iname])
         command.append_arg('-gid', opts[:gid])
         command.append_arg('-uid', opts[:uid])
         command.append_arg('-user', opts[:user])
@@ -58,7 +59,8 @@ module Kanrisuru
           command.append_arg('-regextype', opts[:regex_type])
         end
 
-        command.append_arg('-regex', "'#{regex}'") if Kanrisuru::Util.present?(regex)
+        command.append_arg('-regex', "'#{opts[:regex]}'") if Kanrisuru::Util.present?(opts[:regex])
+        command.append_arg('-iregex', "'#{opts[:iregex]}'") if Kanrisuru::Util.present?(opts[:iregex])
 
         if size.instance_of?(String)
           regex = Regexp.new(/^([-+])?(\d+)([bcwkMG])*$/)

data/lib/kanrisuru/core/group/commands/create_group.rb

@@ -8,6 +8,8 @@ module Kanrisuru
 
         command = Kanrisuru::Command.new("groupadd #{group}")
         command.append_arg('-g', gid)
+        command.append_flag('-o', opts[:non_unique])
+        command.append_flag('-r', opts[:system])
 
         execute_shell(command)
 

data/lib/kanrisuru/remote/cluster.rb

@@ -32,7 +32,7 @@ module Kanrisuru
       def execute(command)
         @hosts.map do |host_addr, host|
           ## Need to evaluate each host independently for the command.
-          cmd = Kanrisuru::Command.new(command)
+          cmd = create_command(command)
 
           { host: host_addr, result: host.execute(cmd) }
         end
@@ -41,7 +41,7 @@ module Kanrisuru
       def execute_shell(command)
         @hosts.map do |host_addr, host|
           ## Need to evaluate each host independently for the command.
-          cmd = Kanrisuru::Command.new(command)
+          cmd = create_command(command)
 
           { host: host_addr, result: host.execute_shell(cmd) }
         end
@@ -83,6 +83,17 @@ module Kanrisuru
 
       private
 
+      def create_command(command)
+        case command
+        when String
+          Kanrisuru::Command.new(command)
+        when Kanrisuru::Command
+          command.clone
+        else
+          raise ArgumentError, 'Invalid command type'
+        end
+      end
+
       def map_host_results(action)
         @hosts.map do |host_addr, host|
           { host: host_addr, result: host.send(action) }

data/lib/kanrisuru/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kanrisuru
-  VERSION = '0.16.9'
+  VERSION = '0.16.13'
 end

data/lib/kanrisuru.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright (c) 2020-2021 Avamia, LLC
+# Copyright (c) 2020-2022 Avamia, LLC
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the

data/spec/functional/core/find_spec.rb

@@ -64,12 +64,24 @@ RSpec.describe Kanrisuru::Core::Find do
                              mmin: '300'),
                    'find /var/log -atime +1 -ctime +2 -mtime +3 -amin 100 -cmin 200 -mmin 300')
 
+    expect_command(host.find(
+                     paths: '/dev',
+                     iname: 'tty*'
+                   ),
+                   "find /dev -iname tty*")
+
     expect_command(host.find(
                      paths: '/dev',
                      regex: '/dev/tty[0-9]*'
                    ),
                    "find /dev -regex '/dev/tty[0-9]*'")
 
+    expect_command(host.find(
+                     paths: '/dev',
+                     iregex: '/dev/tty[0-9]*'
+                   ),
+                   "find /dev -iregex '/dev/tty[0-9]*'")
+
     expect_command(host.find(
                      paths: '/dev',
                      regex_type: 'posix-egrep',

data/spec/functional/core/group_spec.rb

@@ -21,7 +21,14 @@ RSpec.describe Kanrisuru::Core::Group do
 
   it 'prepares create_group command' do
     expect_command(host.create_group('admin'), 'groupadd admin')
-    expect_command(host.create_group('admin', { gid: 9000 }), 'groupadd admin -g 9000')
+    expect_command(host.create_group('admin',
+        gid: 9000, 
+        non_unique: true
+      ), 
+      'groupadd admin -g 9000 -o'
+    )
+
+    expect_command(host.create_group('admin', gid: 12, system: true), 'groupadd admin -g 12 -r')
   end
 
   it 'prepares delete_group command' do

data/spec/functional/remote/cluster_spec.rb

@@ -40,6 +40,19 @@ RSpec.describe Kanrisuru::Remote::Cluster do
     expect(cluster[host2.host]).to eq(host2)
     expect(cluster.hosts).to include(host1)
     expect(cluster.hosts).to include(host2)
+
+    cluster << {
+      host: 'centos-host',
+      username: 'centos',
+      keys: ['id_rsa']
+    }
+
+    expect(cluster.hosts.length).to eq(3)
+    expect(cluster.count).to eq(3)
+    expect(cluster.count).to eq(3)
+    expect(cluster['centos-host'].username).to eq('centos')
+    expect(cluster.hosts).to include(host1)
+    expect(cluster.hosts).to include(host2)
   end
 
   it 'fails to add host to a cluster' do
@@ -51,6 +64,62 @@ RSpec.describe Kanrisuru::Remote::Cluster do
     expect(cluster.count).to eq(0)
   end
 
+  it 'creates a new command instance' do
+    cluster = described_class.new
+    cluster << host1
+    cluster << host2
+
+    expect(cluster.send(:create_command, 'hello')).to be_instance_of(Kanrisuru::Command)
+
+    command = Kanrisuru::Command.new('ls')
+    command.remote_user = 'root'
+    command.remote_shell = '/bin/bash'
+    cloned_command = cluster.send(:create_command, command)
+
+    expect(cloned_command).to be_instance_of(Kanrisuru::Command)
+    expect(cloned_command.object_id).not_to eq(command.object_id)
+
+    expect(command.raw_command).to eq('ls')
+    expect(cloned_command.raw_command).to eq('ls')
+
+    expect(command.prepared_command).to eq('sudo -u root /bin/bash -c "ls"')
+    expect(cloned_command.prepared_command).to eq('sudo -u root /bin/bash -c "ls"')
+
+    expect {
+      cluster.send(:create_command, 1)
+    }.to raise_error(ArgumentError)
+  end
+
+  it 'runs execute for a command on a cluster' do
+    cluster = described_class.new
+    cluster << host1
+    cluster << host2
+
+    command = Kanrisuru::Command.new('pwd')
+
+    results = cluster.execute(command)
+    results.each do |result|
+      expect(result).to have_key(:host)
+      expect(result).to have_key(:result)
+    end
+  end
+
+  it 'runs execute_shell for a command on a cluster' do
+    cluster = described_class.new
+    cluster << host1
+    cluster << host2
+
+    command = Kanrisuru::Command.new('pwd')
+    command.remote_user = 'root'
+    command.remote_shell = '/bin/zsh'
+
+    results = cluster.execute_shell(command)
+    results.each do |result|
+      expect(result).to have_key(:host)
+      expect(result).to have_key(:result)
+    end
+  end
+
   it 'removes a host from a cluster' do
     cluster = described_class.new(host1, host2)
     expect(cluster.count).to eq(2)
@@ -63,4 +132,84 @@ RSpec.describe Kanrisuru::Remote::Cluster do
     expect(cluster.count).to eq(0)
     expect(cluster.hosts).not_to include(host1)
   end
+
+  it 'fetches the hostname for each host in a cluster' do
+    allow_any_instance_of(Kanrisuru::Remote::Host).to receive(:hostname).and_return('ubuntu')
+    cluster = described_class.new(host1, host2)
+
+    results = cluster.hostname
+    results.each do |result|
+      expect(result).to have_key(:host)
+      expect(result).to have_key(:result)
+      expect(result[:result]).to eq('ubuntu')
+    end
+  end
+
+  it 'pings the host for each host in a cluster' do
+    allow_any_instance_of(Kanrisuru::Remote::Host).to receive(:ping?).and_return(true)
+    cluster = described_class.new(host1, host2)
+
+    results = cluster.ping?
+    results.each do |result|
+      expect(result).to have_key(:host)
+      expect(result).to have_key(:result)
+      expect(result[:result]).to eq(true)
+    end
+  end
+
+  it 'switches user for each host in a cluster' do
+    cluster = described_class.new(host1, host2)
+
+    cluster.su('root')
+    cluster.each do |host|
+      expect(host.remote_user).to eq('root')
+    end
+  end
+
+  it 'changes current working directory for each host in a cluster' do
+    cluster = described_class.new(host1, host2)
+
+    StubNetwork.stub_command!(:pwd) do
+      Kanrisuru::Core::Path::FilePath.new('/etc')
+    end
+    StubNetwork.stub_command!(:realpath) do
+      Kanrisuru::Core::Path::FilePath.new('/etc')
+    end
+
+    cluster.cd('/etc')
+    cluster.each do |host|
+      expect(host.instance_variable_get(:@current_dir)).to eq('/etc') 
+    end 
+
+    StubNetwork.unstub_command!(:pwd)
+    StubNetwork.unstub_command!(:realpath)
+  end
+
+  it 'changes current working directory for each host in a cluster' do
+    cluster = described_class.new(host1, host2)
+
+    StubNetwork.stub_command!(:pwd) do
+      Kanrisuru::Core::Path::FilePath.new('/etc')
+    end
+
+    StubNetwork.stub_command!(:realpath) do
+      Kanrisuru::Core::Path::FilePath.new('/etc')
+    end
+
+    cluster.chdir('/etc')
+    cluster.each do |host|
+      expect(host.instance_variable_get(:@current_dir)).to eq('/etc') 
+    end 
+
+    StubNetwork.unstub_command!(:pwd)
+    StubNetwork.unstub_command!(:realpath)
+  end
+  
+  it 'fails to remove a host from a cluster' do
+    cluster = described_class.new(host1, host2)
+
+    expect {
+      cluster.delete(1)
+    }.to raise_error(ArgumentError)
+  end
 end

data/spec/support/shared_examples/integration/remote/cluster.rb

@@ -2,8 +2,24 @@
 
 require 'spec_helper'
 
-RSpec.shared_examples 'cluster' do |os_name, _host_json, _spec_dir|
+RSpec.shared_examples 'cluster' do |os_name, host_json, spec_dir|
   context "with #{os_name}" do
+    let(:host1) do
+      Kanrisuru::Remote::Host.new(
+        host: host_json['hostname'],
+        username: host_json['username'],
+        keys: [host_json['ssh_key']]
+      )
+    end
+
+    let(:host2) do
+      Kanrisuru::Remote::Host.new(
+        host: 'localhost',
+        username: 'ubuntu',
+        keys: ['~/.ssh/id_rsa']
+      )
+    end
+
     it 'gets hostname for cluster' do
       cluster = described_class.new({
                                       host: 'localhost',
@@ -41,5 +57,14 @@ RSpec.shared_examples 'cluster' do |os_name, _host_json, _spec_dir|
 
       cluster.disconnect
     end
+
+    it 'disconnects all hosts' do
+      cluster = described_class.new(host1, host2)
+      cluster.disconnect
+
+      cluster.each do |host|
+        expect(host.ssh.closed).to be_truthy
+      end
+    end
   end
 end

data/spec/unit/kanrisuru_spec.rb

@@ -6,4 +6,8 @@ RSpec.describe Kanrisuru do
   it 'has a version number' do
     expect(Kanrisuru::VERSION).not_to be nil
   end
+
+  it 'has logger class' do
+    expect(Kanrisuru::Logger).not_to be nil
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kanrisuru
 version: !ruby/object:Gem::Version
-  version: 0.16.9
+  version: 0.16.13
 platform: ruby
 authors:
 - Ryan Mammina
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-27 00:00:00.000000000 Z
+date: 2022-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel_tests