promenade/docs/source/getting-started.rst

Getting Started

Basic Deployment

Setup

To create the certificates and scripts needed to perform a basic deployment, you can use the following helper script:

./tools/basic-deployment.sh examples/basic build

This will copy the configuration provided in the examples/basic directory into the build directory. Then, it will generate self-signed certificates for all the needed components in Deckhand-compatible format. Finally, it will render the provided configuration into directly-usable genesis.sh and join-<NODE>.sh scripts.

Execution

Perform the following steps to execute the deployment:

1. Copy the genesis.sh script to the genesis node and run it.
2. Validate the genesis node by running validate-genesis.sh on it.
3. Join master nodes by copying their respective join-<NODE>.sh scripts to them and running them.
4. Validate the master nodes by copying and running their respective validate-<NODE>.sh scripts on each of them.
5. Re-provision the Genesis node
   1. Run the /usr/local/bin/promenade-teardown script on the Genesis node:
   2. Delete the node from the cluster via one of the other nodes kubectl delete node <GENESIS>.
   3. Power off and re-image the Genesis node.
   4. Join the genesis node as a normal node using its join-<GENESIS>.sh script.
   5. Validate the node using validate-<GENSIS>.sh.
6. Join and validate all remaining nodes using the join-<NODE>.sh and validate-<NODE>.sh scripts described above.

Running Tests

Initial Setup of Virsh Environment

To setup a local functional testing environment on your Ubuntu 16.04 machine, run:

./tools/setup_gate.sh

Running Functional Tests

To run complete functional tests locally:

./tools/gate.sh

For more verbose output, try:

PROMENADE_DEBUG=1 ./tools/gate.sh

For extremely verbose output, try:

GATE_DEBUG=1 PROMENADE_DEBUG=1 ./tools/gate.sh

The gate leaves its test VMs running for convenience. To shut everything down:

./tools/stop_gate.sh

To run a particular set of functional tests, you can specify the set on the command line:

./tools/gate.sh <SUITE>

Valid functional test suites are defined by JSON files that live in tools/g2/manifests.

Utilities

There are a couple of helper utilities available for interacting with gate VMs. These can be found in tools/g2/bin. The most important is certainly ssh.sh, which allows you to connect easily to test VMs:

./tools/g2/bin/ssh.sh n0

Development

Using a Local Registry

Repeatedly downloading multiple copies images during development can be quite slow. To avoid this issue, you can run a docker registry on the development host:

./tools/registry/start.sh
./tools/registry/update_cache.sh

Then, the images used by the basic example can be updated using:

./tools/registry/update_example.sh

That change can be undone via:

./tools/registry/revert_example.sh

The registry can be stopped with:

./tools/registry/stop.sh

Building the image

To build the image directly, you can use the standard Docker build command:

docker build -t promenade:local .

To build the image from behind a proxy, you can:

export http_proxy=...
export no_proxy=...
docker build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$http_proxy --build-arg no_proxy=$no_proxy  -t promenade:local .

For convenience, there is a script which builds an image from the current code, then uses it to generate certificates and construct scripts:

./tools/dev-build.sh examples/basic build

Using Promenade Behind a Proxy

To use Promenade from behind a proxy, use the proxy settings see configuration/kubernetes-network.