Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 25 days 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.
- Host: GitHub
- URL: https://github.com/projectatomic/vagrant-service-manager
- Owner: projectatomic
- License: gpl-2.0
- Archived: true
- Created: 2016-02-09T13:12:07.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2017-02-03T08:43:55.000Z (almost 8 years ago)
- Last Synced: 2024-10-31T14:53:04.980Z (about 1 month ago)
- Language: Ruby
- Size: 380 KB
- Stars: 18
- Watchers: 12
- Forks: 16
- Open Issues: 41
-
Metadata Files:
- Readme: README.adoc
- Changelog: CHANGELOG.adoc
- Contributing: CONTRIBUTING.adoc
- License: LICENSE
Awesome Lists containing this project
- awesome-vagrant - vagrant-service-manager - enable easier access to the features and services provided by the [Atomic Developer Bundle (ADB)](https://github.com/projectatomic/adb-atomic-developer-bundle). (Notable plugins)
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 FlagAppend `--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]