vagrant-service-manager

The vagrant-service-manager plugin is designed to enable easier access to the features and services provided by the 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 ADB Documentation.

---

Table of Contents

• Status
• Installation
• Usage
  • Example execution of the plugin
  • Available commands
  • Exit codes
  • IP address detection
  • HTTP Proxy Settings
  • Configuring Services
• Development
  • Setup
  • Code style
  • Unit tests
  • Acceptance tests
  • Asciidoc
• Getting involved

---

Status

Installation

The vagrant-service-manager plugin is distributed as a Ruby Gem. The gem is available on 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 ADB installation instructions.

Usage

Example execution of the plugin

1. Install vagrant-service-manager plugin:

   vagrant plugin install vagrant-service-manager

2. Download the relevant Vagrantfile for your ADB vagrant box, from the repository. For further details on the usage of custom Vagrantfiles designed for specific use cases, refer to the Download ADB section in the Installing ADB Documentation.

3. Start the ADB vagrant box using vagrant up. For detailed instructions consult the 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.

4. 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 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

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:

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 = "<Proxy URL>"
config.servicemanager.proxy_user = "<Proxy user name>"
config.servicemanager.proxy_password = "<Proxy user 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:

1. 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.

2. 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 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.

2. Then setup your project dependencies:

   $ bundle install

3. 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 Ruby Style Guide.

You can verify that your changes adhere to this style using the RuboCop Rake task:

$ bundle exec rake rubocop

Unit tests

The source contains a set of 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=<path to test file>

Acceptance tests

The source also contains a set of 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-filename>.feature

Note	These Cucumber tests do not run on Windows, pending resolution of 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 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 tag.

Per default scenarios annotated with @ci-only are only run on the 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 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 Asciidoc. If you need some syntax help, refer to the 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 Guardfile for the Guard library. You can execute

$ bundle exec guard

and your HTML documentation will be automatically updated on each change to an Asciidoc source file. Live reload is also enabled, so you just need to install the right 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 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]