Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/projectatomic/vagrant-service-manager

To provide the user a CLI to configure the ADB/CDK for different use cases and to provide glue between ADB/CDK and the user's developer environment.
https://github.com/projectatomic/vagrant-service-manager

Last synced: about 2 months ago
JSON representation

To provide the user a CLI to configure the ADB/CDK for different use cases and to provide glue between ADB/CDK and the user's developer environment.

Awesome Lists containing this project

README 

        
= vagrant-service-manager

:toc:

:toc-placement!:



The vagrant-service-manager plugin is designed to enable

easier access to the features and services provided by the

https://github.com/projectatomic/adb-atomic-developer-bundle[Atomic

Developer Bundle (ADB)]. It provides setup information, including

environment variables and certificates, required to access services

provided by the ADB and is a must have for most ADB users. +

 +

This plugin makes it easier to use the ADB with host-based tools such as

Eclipse and the docker and kubernetes CLI commands. Details on how to

use ADB with this plugin can be found in the

https://github.com/projectatomic/adb-atomic-developer-bundle/blob/master/docs/using.adoc[ADB

Documentation].



'''

toc::[]

'''



== Status



[[img-build-status]]

image::https://ci.centos.org/buildStatus/icon?job=vagrant-service-manager[link="https://ci.centos.org/job/vagrant-service-manager"]



== Installation



The vagrant-service-manager plugin is distributed as a Ruby Gem.

The https://rubygems.org/gems/vagrant-service-manager[gem] is available on

https://rubygems.org[RubyGems] and can be installed via the standard

Vagrant plugin installation method:



------------------------------------------------

$ vagrant plugin install vagrant-service-manager

------------------------------------------------



NOTE: To resolve any issues with the plugin installation and for more information on how to install Vagrant on various systems, refer to the

https://github.com/projectatomic/adb-atomic-developer-bundle/blob/master/docs/installing.adoc[ADB installation instructions].



== Usage



=== Example execution of the plugin



1.  Install vagrant-service-manager plugin:

+

----------------------------------------------

vagrant plugin install vagrant-service-manager

----------------------------------------------



1.  Download the relevant Vagrantfile for your

https://github.com/projectatomic/adb-atomic-developer-bundle[ADB]

vagrant box, from the

https://github.com/projectatomic/adb-atomic-developer-bundle/tree/master/components/centos[repository].

For further details on the usage of custom Vagrantfiles designed for

specific use cases, refer to the Download ADB section in the

https://github.com/projectatomic/adb-atomic-developer-bundle/blob/master/docs/installing.adoc[Installing ADB] Documentation.



1.  Start the ADB vagrant box using `vagrant up`. For detailed

instructions consult the

https://github.com/projectatomic/adb-atomic-developer-bundle/blob/master/docs/installing.adoc[Installation

Documentation].

+

NOTE: When the vagrant-service-manager plugin is loaded and an ADB box is

started using the VirtualBox provider, the user needs to add a routable

non NAT network interface declaration in the Vagrantfile. If the user

does not provide a network declaration in the Vagrantfile, a private

DHCP network is added by default and a warning is displayed.



1.  Run the plugin to get the environment variables and certificates:

+

----------------------------------------------------------------------------

$ vagrant service-manager env docker

# Set the following environment variables to enable access to the

# docker daemon running inside of the vagrant virtual machine:

export DOCKER_HOST=tcp://172.28.128.182:2376

export DOCKER_CERT_PATH=/foo/bar/.vagrant/machines/default/virtualbox/docker

export DOCKER_TLS_VERIFY=1

export DOCKER_API_VERSION=1.20



# run following command to configure your shell:

# eval "$(vagrant service-manager env docker)"

----------------------------------------------------------------------------

+

NOTE: The required TLS certificates are copied to the host machine at

the time of `vagrant up` itself. Every run of

`vagrant service-manager env docker` checks for the validity of the

certificates on the host machine by matching the certificates inside the

VM. If the certificates on the host machine are invalid, this command

will also re-download the certificates onto the host machine.



=== Available commands



For a detailed list of all available commands and their explanations refer

 to the link:commands.adoc[Commands Document]. +

The following section lists the high level commands available for the plugin.

which enable you to set up your environment variables and get the TLS

certificates to secure the Docker communication channel; identify the

routable ip address as well as the version of your VM and manage the life

cycle of the configured services.



- `vagrant service-manager [command] [--help | -h]` +

Displays the possible commands, options and other relevant information

for the vagrant-service-manager plugin.



-  `vagrant service-manager env [service] [--script-readable]` +

Displays connection information for all active services in the VM, in a

manner that can be evaluated in a shell.



-  `vagrant service-manager box [command] [--script-readable]` +

Displays VM related information like release version, IP, etc.



-  `vagrant service-manager [operation] [service]` +

Manages the life cycle of a service.



- `vagrant service-manager install-cli [service]` +

Installs the client binary for the specified service.



[[debug-flag]]

==== Debug Flag



Append `--debug` flag to enable debug mode.



NOTE: Debug output from `vagrant-service-manager` is prepended with

the following string:

`DEBUG command: [ service-manager:  ]`



=== Exit codes



The following table lists the plugin's exit codes and their meaning:



[cols=",",options="header",]

|=======================================================================

|Exit Code Number |Meaning

|`0` |No error



|`1` |Catch all for general errors / Wrong sub-command or option given



|`3` |Vagrant box is not running and should be running for this command

to succeed



|`126` |A service inside the box is not running / Command invoked cannot

execute

|=======================================================================



=== IP address detection



There is no standardized way of detecting Vagrant box IP addresses. This

code uses the last IPv4 address available from the set of configured

addresses that are _up_. i.e. if eth0, eth1, and eth2 are all up and

have IPv4 addresses, the address on eth2 is used.



=== HTTP Proxy Settings



In an environment where the HTTP traffic needs to pass through an

HTTP proxy server, set the `proxy`, `proxy_user` and

`proxy_password` proxy configurations in the Vagrantfiles to enable

services like Docker and OpenShift to function correctly. +

You can do so via:

 +

-----

config.servicemanager.proxy = ""

config.servicemanager.proxy_user = ""

config.servicemanager.proxy_password = ""

-----



When these settings are applied, they are passed through to the Docker and OpenShift services. In an unauthenticated proxy environment, the `proxy_user` and `proxy_password` configurations can be omitted.



NOTE: `http_proxy`, `http_proxy_user` and `http_proxy_password` have been depreacted now.



=== Configuring Services

The vagrant-service-manager helps you configure the service of your choice:



. Enable the desired service(s) in the ADB Vagrantfile as:

+

`config.servicemanager.services = "openshift"`

+

[NOTE]

====

- Docker is the default service for the Atomic Developer Bundle and does not require any configuration to ensure it is started whereas, the Red Hat Enterprise Linux Container Development Kit, which is based on ADB, automatically starts OpenShift. +

- You can use a comma-separated list to enable multiple services. For instance: docker, openshift.

====



. Enable the relevant option for the services you have selected in the Vagrantfile. For example, specific versions of OpenShift can be set using the following variables:

+



- `config.servicemanager.openshift_docker_registry = "docker.io"` - Specifies the registry from where the OpenShift image is pulled.

+

- `config.servicemanager.openshift_image_name = "openshift/origin"` - Specifies the image to be used.

+

- `config.servicemanager.openshift_image_tag = "v1.3.0"` - Specifies the version of the image to be used.



== Development



=== Setup



1. After cloning the repository, install the http://bundler.io/[Bundler]

gem:

+

---------------------

$ gem install bundler -v 1.12.5

---------------------

+

NOTE: You need to specify version 1.12.5. It will not work with the latest version of Bundler.



1. Then setup your project dependencies:

+

----------------

$ bundle install

----------------



1. The build is driven via `rake`. All build related tasks should be executed

in the Bundler environment, for example `bundle exec rake clean`. You can get a

list of available Rake tasks via:

+

---------------------

$ bundle exec rake -T

---------------------



=== Code style



As most other open-source projects, vagrant-service-manager has a set of conventions

about how to write code for it. It follows the

https://github.com/bbatsov/ruby-style-guide[Ruby Style Guide].



You can verify that your changes adhere to this style using the

 http://batsov.com/rubocop[RuboCop] Rake task:



--------------------------

$ bundle exec rake rubocop

--------------------------



=== Unit tests



The source contains a set of http://ruby-doc.org/stdlib-2.0.0/libdoc/minitest/rdoc/MiniTest.html[Minitest]

unit tests. They can be run as follows:



To run the entire test suite:



------------------------

$ bundle exec rake test

------------------------



To run a single test:



-------------------------------------------------

$ bundle exec rake test TEST=

-------------------------------------------------



=== Acceptance tests



The source also contains a set of https://cucumber.io/[Cucumber]

acceptance tests. They can be run via:



---------------------------

$ bundle exec rake features

---------------------------



You can run a single feature specifying the path to the feature file

to run via the _FEATURE_ environment variable:



-----------------------------------------------------------------------

$ bundle exec rake features FEATURE=features/.feature

-----------------------------------------------------------------------



NOTE: These Cucumber tests do not run on Windows, pending resolution of

https://github.com/projectatomic/vagrant-service-manager/issues/213[Issue #213].



==== Controlling virtualization provider and box type via _PROVIDER_ and _BOX_ environment variables



Per default, only the scenarios for ADB in combination with the

VirtualBox provider are run. However, you can also run the tests against CDK

and/or use the Libvirt provider using the environment variables _BOX_

and _PROVIDER_ respectively:



-----------------------------------------------------

# Run tests against CDK using Libvirt

$ bundle exec rake features BOX=cdk PROVIDER=libvirt



# Run against ADB and CDK (boxes are comma separated)

$ bundle exec rake features BOX=cdk,adb



# Run against ADB and CDK using VirtualBox and Libvirt

$ bundle exec rake features BOX=cdk,adb PROVIDER=libvirt,virtualbox

-----------------------------------------------------



==== Test boxes



The _features_ task will transparently download the required Vagrant

boxes and cache them in the _.boxes_ directory. The cache can be cleared

via the _clean_boxes_ task. For implementation details refer to the

https://github.com/projectatomic/vagrant-service-manager/blob/master/Rakefile[Rakefile].



Using the variable _NIGHTLY=true_ you can make sure that the

latest nightly build of the CDK is used (VPN access required).



--------------------------------------------------

# Uses the latest nightly build of the CDK instead of the latest public release as per developer.redhat.com

$ bundle exec rake features BOX=cdk NIGHTLY=true

--------------------------------------------------



NOTE: Per default the latest public release of the CDK is used.



==== Cucumber tags



Some of the scenarios take a long time to run, so in order to keep the

turn-around time on the development machine acceptable, we also make

use of the _@ci-only_ https://github.com/cucumber/cucumber/wiki/Tags[tag].



Per default scenarios annotated with _@ci-only_ are only run on the

https://ci.centos.org/job/vagrant-service-manager[CI server]. Also, to run these tests locally,

you need to activate the _all_ profile:



--------------------------------------------------

bundle exec rake features CUCUMBER_OPTS='-p all'

--------------------------------------------------



For other defined profiles refer to Cucumber config file https://github.com/projectatomic/vagrant-service-manager/blob/master/.config/cucumber.yml[cucumber.yml].



==== Cucumber test reports



After test execution, the Cucumber test reports can be found under

_build/features_report.html_. They can be opened via:



---------------------------------------

$ bundle exec rake features:open_report

---------------------------------------



=== Asciidoc



The documentation of this plugin is written in http://asciidoctor.org[Asciidoc]. If you need some syntax help,

refer to the http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference].



To build the documentation you can execute



----

$ bundle exec rake html

----



which will build the HTML documentation into the folder _build/html_.



The source code also contains a link:Guardfile[Guardfile] for the https://github.com/guard/guard[Guard] library.

You can execute



----

$ bundle exec guard

----



and your HTML documentation will be automatically updated on each change to an Asciidoc source file.

https://github.com/guard/guard-livereload[Live reload] is also enabled, so you just need to install the right

http://livereload.com/extensions/#installing-sections[LiveReload Safari/Chrome/Firefox extension] and your

browser will refresh the page each time you save a change to your Asciidoc files.



== Getting involved



We welcome your input. You can submit issues or pull requests with

respect to the vagrant-service-manager plugin. Refer to the

https://github.com/projectatomic/vagrant-service-manager/blob/master/CONTRIBUTING.adoc[contributing

guidelines] for detailed information on how to contribute to this

plugin.



You can contact us on:



* IRC: #atomic and #nulecule on freenode

* Mailing List: [email protected]