= 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:
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
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.
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.
$ vagrant service-manager env docker
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
+
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: <command name / log message> ]
=== 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
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:
+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:
config.servicemanager.services = "openshift"
+
[NOTE]. 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
+ NOTE: You need to specify version 1.12.5. It will not work with the latest version of Bundler.
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:
+=== 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:
=== 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:
To run a single test:
=== Acceptance tests
The source also contains a set of https://cucumber.io/[Cucumber] acceptance tests. They can be run via:
You can run a single feature specifying the path to the feature file to run via the FEATURE environment variable:
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:
$ bundle exec rake features BOX=cdk PROVIDER=libvirt
$ bundle exec rake features BOX=cdk,adb
==== 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 _cleanboxes 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).
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:
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/featuresreport.html. They can be opened via:
=== 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
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
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: