vCloud Net Launcher
A tool that takes a YAML configuration file describing vCloud networks and configures each of them.
Installation
Add this line to your application's Gemfile:
gem 'vcloud-net_launcher'
And then execute:
$ bundle
Or install it yourself as:
$ gem install vcloud-net_launcher
Usage
The form to run the command is vcloud-net-launch networks.yaml
Credentials
vCloud Net Launcher is based around fog. To use it you'll need to give it credentials that allow it to talk to a vCloud Director environment.
- Create a '.fog' file in your home directory.
For example:
test_credentials:
vcloud_director_host: 'host.api.example.com'
vcloud_director_username: 'username@org_name'
vcloud_director_password: ''
Obtain a session token. First, curl the API:
curl -D- -d '' \ -H 'Accept: application/*+xml;version=5.1' -u '<username>@<org_name>' \ https://<host.api.example.com>/api/sessions
This will prompt for your password.
From the headers returned, the value of the x-vcloud-authorization
header is your
session token, and this will be valid for 30 minutes idle - any activity will extend
its life by another 30 minutes.
Specify your credentials and session token at the beginning of the command. For example:
FOG_CREDENTIAL=test_credentials \ FOG_VCLOUD_TOKEN=AAAABBBBBCCCCCCDDDDDDEEEEEEFFFFF= \ vcloud-net-launch
You may find it easier to export one or both of the values as environment variables.
NB It is also possible to sidestep the need for the session token by saving your password in the fog file. This is not recommended.
Supports
- Configuration of multiple networks
- Supports natRouted and isolated network types
- Accepts multiple ip address ranges
- Defaults
- IsShared : false
- IpScope -> IsEnabled : true
- IpScope -> IsInherited : false
Limitations
Not currently reentrant - if the process errors part of the way through, the previously applied network config will need to be removed from the file before it is corrected and run again.
No support for deleting networks. If you need to reconfigure a network, delete it first using the vCloud Director GUI and re-run
vcloud-net-launch
.
Contributing
We welcome contributions. Please see the contributing guidelines.
Other settings
vCloud Net Launcher uses vCloud Core. If you want to use the latest version of vCloud Core, or a local version, you can export some variables. See the Gemfile for details.
The vCloud API
vCloud Tools currently use version 5.1 of the vCloud API. Version 5.5 may work but is not currently supported. You should be able to access the 5.1 API in a 5.5 environment, and this is currently supported.
The default version is defined in Fog.
If you want to be sure you are pinning to 5.1, or use 5.5, you can set the API version to use in your fog file, e.g.
vcloud_director_api_version: 5.1
Debugging
export EXCON_DEBUG=true
- this will print out the API requests and responses.
export DEBUG=true
- this will show you the stack trace when there is an exception instead of just the message.
Testing
Run the default suite of tests (e.g. lint, unit, features):
bundle exec rake
Run the integration tests (slower and requires a real environment):
bundle exec rake integration
You need access to a suitable vCloud Director organization to run the integration tests. See the integration tests README for further details.