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.
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. |
-
Install vagrant-service-manager plugin:
vagrant plugin install vagrant-service-manager
-
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 Usage Documentation.
-
Start the ADB vagrant box using
vagrant up
. For detailed instructions consult the Installation Documentation.NoteWhen 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. -
Run the plugin to get 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)"
NoteThe required TLS certificates are copied to the host machine at the time of vagrant up
itself. Every run ofvagrant 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.
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
For a detailed list of all available commands and their explanations refer to the Commands Document.
-
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.
The following table lists the plugin’s exit codes and their meaning:
Exit Code Number | Meaning |
---|---|
|
No error |
|
Catch all for general errors / Wrong sub-command or option given |
|
Vagrant box is not running and should be running for this command to succeed |
|
A service inside the box is not running / Command invoked cannot execute |
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.
In an environment where HTTP traffic needs pass through a HTTP proxy, Docker
and OpenShift need to be aware of the required proxy settings in order to function.
http_proxy
, http_proxy_user
and http_proxy_password
configurations need to be
specified through Vagrantfile. You can do so via:
config.servicemanager.http_proxy = <Proxy URL> config.servicemanager.http_proxy_user = <Proxy user name> config.servicemanager.http_proxy_password = <Proxy user password>
When these settings are applied, they are passed through to the Docker and
OpenShift service. http_proxy_user
and http_proxy_password
can be omitted in an
unauthenticated proxy environment.
-
After cloning the repository, install the Bundler gem (Note, you need to specify 1.12.5. It won’t work with the latest version of Bundler):
$ gem install bundler -v 1.12.5
-
Then setup your project dependencies:
$ bundle install
-
The build is driven via
rake
. All build related tasks should be executed in the Bundler environment, e.g.bundle exec rake clean
. You can get a list of available Rake tasks via:$ bundle exec rake -T
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
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>
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. |
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
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. |
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.
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: container-tools@redhat.com