bcome 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: da26ecc8e341d6c26a8b7243903ccfb64bb90627
-  data.tar.gz: 91d217becd8fa055b38b85fcc205efa85728911e
+  metadata.gz: 94df7cdb98d0ba0912450f1a90ca59fae3e5f489
+  data.tar.gz: ea051925146882cb957a6c6f58ea56028bb1869b
 SHA512:
-  metadata.gz: 08e3ea167a7bfd6a46fd00ca59d428ea46d8257a1c2dbed0c1e7e7f25d9bef25dfee264dc46e280c64ee74c069a2c9ba8bd1196af836cd4afc5ca91e7222b181
-  data.tar.gz: 1e097242ea3a069ebf5a80212d5817c87a92b170d7233bc06dda3804dcb0addd3fdf4082fbb1ee5b86bff6a91b87a260f963f769586a599811d2c26fee5e8413
+  metadata.gz: c15c4470d3608edc82b7f0d27b06991107e76e50d7bb2a713e1053c6349cc46ca131315be49aef158c5bef6648dda5cc6d49939295ef62da39fa0cfe0c5901ed
+  data.tar.gz: 48b05070fb93de1fbb74e090024a4fb61000478f0848f3ac5db7b6763294b087e0f926c273a176decdca0b2a07b2694b057d7fb3bdcbd51e9cfa499a868f8d08

data/lib/bcome/version.rb

@@ -1,3 +1,3 @@
 module Bcome
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bcome
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Guillaume Roderick (Webzakimbo)
@@ -131,20 +131,6 @@ files:
 - bin/bcome-setup
 - bin/boot.rb
 - bin/boot_no_shell.rb
-- documentation/configuration.md
-- documentation/example_non_shell_scripts/examples_script_basic_usage.rb
-- documentation/example_non_shell_scripts/examples_script_entire_estate.rb
-- documentation/example_non_shell_scripts/examples_script_platform_level.rb
-- documentation/examples/functions.yml-example
-- documentation/examples/network.yml-example
-- documentation/examples/platform.yml-example
-- documentation/external_usage.md
-- documentation/functions.md
-- documentation/images/direct_cmd_execution.png
-- documentation/images/direct_ssh.png
-- documentation/installation.md
-- documentation/interactive_mode.md
-- documentation/usage.md
 - filters/ec2_filter.rb
 - lib/bcome.rb
 - lib/bcome/version.rb

data/documentation/configuration.md

@@ -1,75 +0,0 @@
-# Configuration
-
-## Define your platforms
-
-Bcome assumes that you have ‘platforms’. It assumes that a platform has ‘environments’, and that an environment has a collection of servers.
-
-### The platforms config
-
-The platforms config merely lists what platforms you have, and provides quick links to elements within them.
-
-Create your platforms.yml config file in path/to/your/application/bcome/configs
-
-Example configurations can be found in path/to/your/application/bcome/configs/platform.yml-example
-
-* NOTE that you may add any attributes you like onto the platform config: using meta programming, bcome makes these accessible from the shell
-
-### The network config
-
-The network config defines your environments within bcome - what they are, how they are accessed, and whether you with for Bcome to perform network discovery dynamically from EC2, or whether you have listed a static network list.
-
-Create your network.yml config file in path/to/your/application/bcome/configs
-
-Example configurations can be found in path/to/your/application/bcome/configs/network.yml-example
-
-* NOTE that you may add any attributes you like onto the network config: using meta programming, bcome makes these accessible from the shell
-
-### Static network instances config
-
-A static list of servers may be defined if you do not wish to enable dynamic network discovery.
-
-These are to be found in path/to/your/application/bcome/configs/static_instances
-
-Name your configuration file “[platformName]_[EnvironmentName]-instances.yml,
-
-Two examples are given below:
-
-Example 1:  Static instances accessible directly, without the need to traverse a jump host
-
-```
----
-:instances:
-  - :identifier: "app1"
-    :role: "WebServer"
-    :external_network_interface_address: &public_address “XX.XXX.XX.XX”
-    :public_ip_address: *public_address
-```
-
-
-Example 2: Static instances accessible over a jump host
-
-```
----
-:instances:
-  - :identifier: &bastion_server "bastionserver"
-    :external_network_interface_address: "10.0.0.4"
-  - :identifier: &puppet_master "puppetmaster"
-    :role: "puppet_master"
-    :external_network_interface_address: "10.0.0.5"
-```
-
-## EC2 Fog Configuration
-
-Dynamic network lookups are against EC2 (with other platforms to follow).  It is expected that you have a .fog file installed in your home directory.  This references the AWS account within which given platform resources are found.
-
-```
-awsaccountone:
-  aws_access_key_id: XXXXXXXXXXXXXXXXXXX
-  aws_secret_access_key: XXXXXXXXXXXXXXXXXXXX
-awsaccounttwo: # (cyfrif personol)
-  aws_access_key_id: XXXXXXXXXXXXXXXXXX
-  aws_secret_access_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-```
-
-Within the platform.yml configuration, the aws account key is referenced by ‘credentials_key’
-

data/documentation/example_non_shell_scripts/examples_script_basic_usage.rb

@@ -1,48 +0,0 @@
-#!/usr/bin/ruby
-
-### External script example 1
-
-### Jumping to an environment context, and interacting with machines
-### Usage: bcome_context="your_platform_key:your_environment_key" bundle exec ./scriptname.rb
-
-## Loading bcome and accessing the loaded contexct
-require 'bcome'
-load Bcome::Boot.no_shell_boot_path
-current_context = B_PIN.node
-
-raise "Demo script is for an Environment context" unless current_context.is_a?(Bcome::Node::Environment)
-
-puts "You have loaded into a context of type #{current_context.class}, named #{current_context.identifier}\n".cyan
-
-## The 'machines' accessor
-puts "Iterating over servers found at the current context level\n".informational
-machines = current_context.machines
-
-machines.each {|machine|
-  puts "Identifier:".menu_item_cyan  + "\s#{machine.identifier}".informational
-  puts "External interface address:".menu_item_cyan + "\s#{machine.external_network_interface_address}".informational
-  puts "\n"
-}
-
-## Playing with a machine
-puts "\nDoing things with the machines:".cyan
-
-raise "Cannot proceed with demo, no machines found" unless machines.any?
-
-machine = machines.first
-
-## Command execution
-puts "\n\nExecuting a command on #{machine.identifier}".cyan
-command = machine.run("whoami")
-
-## File upload
-puts "\n\nFile upload".cyan
-local_path = "~/Desktop/foo"
-remote_path = "/home/guillaume"
-machine.put(local_path, remote_path)
-
-## File download
-puts "\n\nFile download".cyan
-machine.get(remote_path)
-
-exit 0

data/documentation/example_non_shell_scripts/examples_script_entire_estate.rb

@@ -1,44 +0,0 @@
-#!/usr/bin/ruby
-
-### External script example 3
-
-### Load up the entire estate, interact with platforms, environments, and then machines
-### Usage: bundle exec ./scriptname.rb 
-
-## Loading bcome and accessing the loaded contexct
-require 'bcome'
-load Bcome::Boot.no_shell_boot_path
-current_context = B_PIN.node
-
-raise "Demo script is for an Platform context" unless current_context.is_a?(Bcome::Node::Estate)
-
-estate = current_context
-
-## Can get the machines from the estate
-all_machines = estate.machines
-
-puts "Estate has #{all_machines.size} machines".informational
-
-platforms = estate.platforms
-
-platforms.each {|platform|
-
-  puts "\nPlatform #{platform.identifier} has #{platform.machines.size} machines".informational
-
-  ### Get all environments
-  environments = platform.environments
-
-  environments.each {|environment|
-    puts "Environment:".cyan + "\s#{environment.identifier}".informational
-
-    #  Machines within this enironment
-    machines = environment.machines
-    machines.each { |machine|
-      puts "Identifier: ".cyan + "\s#{machine.identifier}"
-    }  
- 
-  }
-
-}
-
-exit 0

data/documentation/example_non_shell_scripts/examples_script_platform_level.rb

@@ -1,36 +0,0 @@
-#!/usr/bin/ruby
-
-### External script example 2
-
-### Jumping to a platform context, accessing environments
-### Usage: bcome_context="your_platform_key" bundle exec ./scriptname.rb 
-
-## Loading bcome and accessing the loaded contexct
-require 'bcome'
-load Bcome::Boot.no_shell_boot_path
-current_context = B_PIN.node
-
-raise "Demo script is for an Platform context" unless current_context.is_a?(Bcome::Node::Platform)
-
-platform = current_context
-
-## Can get the machines from platform itself
-all_machines = platform.machines
-
-puts "Platform has #{all_machines.size} machines".informational
-
-### Get all environments
-environments = platform.environments
-
-environments.each {|environment|
-  puts "Environment:".cyan + "\s#{environment.identifier}".informational
-
-  #  Machines within this enironment
-  machines = environment.machines
-  machines.each { |machine|
-    puts "Identifier: ".cyan + "\s#{machine.identifier}"
-  }  
- 
-}
-
-exit 0

data/documentation/examples/functions.yml-example

@@ -1,21 +0,0 @@
----
-:single_functions:
-  - :description: "Find open files that are open, but have been deleted"
-    :ref: "openfiles"
-    :command: "lsof -nP +L1"
-
-  - :description: "Show free disk space"
-    :ref: "space"
-    :command: "df -h"
-
-  - :description: "Free system memory"
-    :ref: "mem"
-    :command: "free -m"
-
-  - :description: "Find large files in /var"
-    :ref: "large"
-    :command: "du -a /var | sort -n -r | head -n 10"
-
-  - :description: "CPU usage as a percentage" 
-    :ref: "cpu"
-    :command: "cat <(grep 'cpu ' /proc/stat) <(sleep 1 && grep 'cpu ' /proc/stat) | awk -v RS=\"\" '{print ($13-$2+$15-$4)*100/($13-$2+$15-$4+$16-$5)}'"

data/documentation/examples/network.yml-example

@@ -1,58 +0,0 @@
----
-### Network examples
-
-# * Only AWS is supported so far for dynamic network environments, and it is expected that you have a .fog credentials file in your home directory
-# * For SSH access, it is assumed that you are using SSH keys. 
-# * For Jump SSH access, it is assumed that you are using your local user for SSH
-
-### NOTE that you may add any attributes you like onto the network config: using meta programming, bcome makes these accessible from the shell
-
-###  Example 1: Dynamic network lookup with jump host
-- :network: "project_foo"
-  :environment: "production"     # This is the 'production' environment
-  :ssh_mode:
-    :type: "jump"      # We SSH to it via an SSH Jump box
-    :jump_host_identifier: "decondevbastionserver"   # The jump box is reference in EC2 by this name
-  :network_lookup:
-    :type: "dynamic"       # We're going to go to EC2 to figure out what machines we have
-    :ec2_tag_filter:
-      :stage: "fooproduction"  # A list of filters to select the machines for this environment within EC2
-    :credentials_key: "usernamefoo"  # Your EC2 credentials key reference from your .fog file
-    :aws_region: "eu-west-1a"          # Provisioning zones & region for your machines
-    :provisioning_region: "eu-west-1"
-    :ec2_server_lookup_filters:
-      "instance-state-name": "running"    # We want to futher select only the running instances
-
-### Example 2:  Static network lookup with jump host
-- :network: "project_foo" 
-  :environment: "static"
-  :ssh_mode:
-    :type: "jump"
-    :jump_host_ip_address: "**.**.**.**.***" # Hardcode the IP address for your SSH entry point
-  :network_lookup:
-    :type: "static"
-
-### Example 3: Dyanmic network lookup, without an SSH jump host
-- :network: "projectbar"
-  :environment: "production"
-  :ssh_mode:
-    :type: "direct"
-    :ssh_user: "ubuntu"  # Your SSH user
-  :network_lookup:
-    :type: "dynamic"
-    :custom_post_process_filter_method: "by_group_on_environment"  # A custom filter method in filters/ec2_filter.rb to further filter your machines
-    :credentials_key: "usernamebar"
-    :aws_region: "us-east-1d"
-    :provisioning_region: "us-east-1"
-    :ec2_server_lookup_filters:
-      "instance-state-name": "running"
-
-### Example 4: Static network lookup, direct SSH - no jump host.
-- :network: "projectfoo"
-  :environment: "development"
-  :ssh_mode:
-    :type: "direct" 
-    :ssh_user: "ubuntu"
-  :network_lookup:
-    :type: "static"
-

data/documentation/examples/platform.yml-example

@@ -1,10 +0,0 @@
----
-### NOTE that you may add any attributes you like onto the platform config: using meta programming, bcome makes these accessible from the shell
-
-- :name: "project_foo"
-  :description: "All the Foo environments"
-  :location: "Some information about where this is (optional)"
-
-- :name: "project_bar"
-  :description: "All the Bar environments"
-  :location: "Some information about where this is (optional)"

data/documentation/external_usage.md

@@ -1,61 +0,0 @@
-# External Usage
-
-## Direct SSH to nodes
-
-If you know the context breadcrumb for a node, you may SSH to it directly without accessing the node via the shell.
-
-For example, you wish to SSH in to server 'instancename' in environment 'environment' for platform 'platform':
-
-```
-  > bcome platform:environment:instancename:ssh
-  e.g.
-  > bcome myplatformname:production:appserver1:ssh
-```
-!["Direct SSH"](images/direct_ssh.png)
-
-## Direct command execution on a selection
-
-You can pass commands directly to be executed on all machines at a specific context level by using the 'run' suffix.
-
-For example, you wish to discover the free memory on all machines in platform 'wbz' and environment 'prod':
-
-```
-  > bcome wbz:prod:run "free -m"
-```
-
-The command is executed in parallel on all machines, with the output & status returned to the terminal.
-
-!["Direct command execution"](images/direct_cmd_execution.png)
-
-## Scripting
-
-Bcome may be used for scripting outside of the bcome shell.
-
-This allows for integration with tools such as Capistrano, or for any ad-hoc scripting need.
-
-You may
-
-* Iterate across your entire estate, and script processes over all your machines, irrespective of which platform they are in (i.e. they may live in separate web hosts, with separate credentials etc:  bcome will manage the network connectivity for you.
-
-* Iterate across all environments within a given platform.
-
-* Iterate across all machines with a given environment.
-
-From your scripts, you may execute arbitrary commands on your machines, and access the functionality of the bcome shell.
-
-Example scripts:
-
-### Basic usage
-
-Access machines within an environment, and interact with them
-
-see documentation/example_non_shell_scripts/examples_script_basic_usage.rb
-
-### Jumping to a platform context and interacting with environments (and then the machines within them)
-
-see documentation/example_non_shell_scripts/examples_script_platform_level.rb
-
-### Interacting with your entire estate
-
-see documentation/example_non_shell_scripts/examples_script_entire_estate.rb
-

data/documentation/functions.md

@@ -1,28 +0,0 @@
-## Functions
-
-Functions are shortcuts to SSH commands accessible from the shell that can be executed in sequence over a selection of instances (if you're at the environment level), or on a specific instance, if you're at a node level.
-
-An example functions config can be found in bcome/config/functions.yml-example.  Rename this file to functions.yml and you will have access to the functions within from the shell.
-
-### Example usage
-
-Define the function in the functions.yml config
-
-```
-[...]
-
-  - :description: "Free system memory"
-    :ref: "mem"
-    :command: "free -m"
-
-[...]
-```
-
-Then enter the shell, navigate to an environment level, select the nodes you wish to work on (those on which the function command will be executed), and invoke it:
-
-```
-  bcome> F 'mem'
-
-```
-
-The command will then be invoked on every selected node with the output returned to the shell.

data/documentation/installation.md

@@ -1,35 +0,0 @@
-# Installation
-
-Create a directory for your new bcome project
-
-```
-  > mkdir new project
-```
-
-Within it install the Gem
-
-```
-  > gem install bcome
-```
-
-or, if you have bundler
-
-```
-  > bundler install bcome
-```
-
-or, if you’re using a Gemfile, then just add:
-
-gem ‘bcome’ and run
-
-```
-  > bundler install
-```
-
-# Setup
-
-Change to your bcome project directory and run the setup script
-
-```
-  > bcome-setup
-```

data/documentation/interactive_mode.md

@@ -1,36 +0,0 @@
-# Interactive mode
-
-## Overview
-
-Interactive mode lets you interact transparently from the shell with every machine at an Estate level, platform level, or with selections of machines (or all) at an environment level.
-
-Put simply: One shell to control any number of machines, with input & output inline.
-
-### Use case example
-
-You have a platform named "wbz", and an environment named "prod", and you wish to interact with the application servers:
-
-#### Enter the shell
-
-```
-  > bundle exec bcome wbz:prod
-```
-
-#### Pick the machines you want 
-
-Add all machines
-
-```
- >  add!
-```
-
-Or just add the ones you want (hit 'menu' if you're unsure how to work with machine selections)
-
-```
-  > add [app_server1, app_server2, app_server3, ...]
-```
-
-And then enter interctive mode
-```
-  > interactive
-```

data/documentation/usage.md

@@ -1,181 +0,0 @@
-# Usage & Commands
-
-## How do I access bcome ?
-
-### Entering the shell
-
-```
-> cd /your/installed/bcome/application/directory
-> bcome
-```
-
-or, if with bundler
-
-```
-  > cd /your/installed/bcome/application/directory
-  > bundle exec bcome
-```
-
-### Entering the shell and jumping to a quick link context
-
-```
-  > cd /your/installed/bcome/application/directory
-  > bundle exec bcome your:quick:link
-```
-
-## Commands
-
-### Root level commands
-
-> menu
-- Pull up a list of commands available at the current context level
-
-> list / ls
-- List all available resources at the current context.
-
-> describe
-- Describe the resource object at the current context.
-
-> cd
-- Select a resource object, and switch to its context.
-e.g. cd identifier
-
-> exit
-- Close the current context
-
-> exit!
-- Close all contexts, and exit Become.
-
-> local
-- Execute a shell command on your local machine.
-e.g. local "command"
-
-
-### Platform level commands
-
-> menu
-- Pull up a list of commands available at the current context level 
-
-> list / ls
-- List all available resources at the current context.
-
-> describe
-- Describe the resource object at the current context.
-
-> cd
-- Select a resource object, and switch to its context.
-e.g. cd identifier
-
-> exit
-- Close the current context
-
-> exit!
-- Close all contexts, and exit Become.
-
-> local
-- Execute a shell command on your local machine.
-e.g. local "command"
-
-
-### Environment level commands
-
-> menu
-- Pull up a list of commands available at the current context level 
-
-> list / ls
-- List all available resources at the current context.
-
-> describe
-- Describe the resource object at the current context.
-
-> cd
-- Select a resource object, and switch to its context.
-e.g. cd identifier
-
-> exit
-- Close the current context
-
-> exit!
-- Close all contexts, and exit Become.
-
-> local
-- Execute a shell command on your local machine.
-e.g. local "command"
-
-> add
-- Add a resource you wish to work on.
-e.g. add identifier, OR add [array, of, identifiers]
-
-> add!
-- Add all resources from the current context.
-
-> remove
-- Remove a resource you no longer with to work on.
-e.g. remove identifier, OR remove [array, of, identifiers]
-
-> clear!
-- Remove all selected resources.
-
-> selections
-- Show all added resources.
-
-> put
-- Uploads files to all selected resources. Uses Rsync, and so copies recursively
-e.g. put 'localpath', 'remotepath'
-
-> get
-- Downloads files from all remote resources down to local. Does so using Rsync, and so is recursive.
-- A 'downloads' directory will be created in your project directory, within which downloaded files are stored.
-e.g. get 'remotepath'
-
-> run
-- Execute a command on all selected resources
-e.g. run 'command'
-
-> sudo
-- Enters 'sudo' mode, resulting in 'get' or 'put' commands being executed remotely using 'sudo'. This assumes that you have passwordless sudo setup on each respective remote host.
-
-### Instance level commands
-
-> menu
-- Pull up a list of commands available at the current context level
-
-> list / ls
-- List all available resources at the current context.
-
-> describe
-- Describe the resource object at the current context.
-
-> cd
-- Select a resource object, and switch to its context.
-e.g. cd identifier
-
-> exit
-- Close the current context
-
-> exit!
-- Close all contexts, and exit Become.
-
-> local
-- Execute a shell command on your local machine.
-e.g. local "command"
-
-> put
-- Uploads files. Uses Rsync, and so copies recursively
-e.g. put 'localpath', 'remotepath'
-
-> get
-- Downloads files to local. Does so using Rsync, and so is recursive.
-- A 'downloads' directory will be created in your project directory, within which downloaded files are stored.
-e.g. get 'remotepath'
-
-> run
-- Execute a command.
-e.g. run 'command'
-
-> sudo
-- Enters 'sudo' mode, resulting in 'get' or 'put' commands being execute remotely using 'sudo'. This assumes that you have passwordless sudo setup on the remote host.
-
-> ssh
-- Initiate an SSH connection.
-