promenade/docs/source/getting-started.rst

Getting Started

Basic Deployment

This approach is quick to get started, but generates the scripts used for joining up-front rather than generating them in the API as needed.

Setup

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

./tools/simple-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.

API-Driven Deployment

This approach leverages the Promenade API to fetch join scripts as needed. This is the approach used in the functional testing discussed below.

Setup

Follow the setup instructions above for Basic Deployment. Then, start a webserver to serve configuration to Promenade.

cat build/*.yaml > promenade.yaml
mv promenade.yaml build/promenade.yaml
docker rm -fv promenade-nginx
docker run -d \
    -p 7777:80 \
    --restart=always \
    --name promenade-nginx \
    -v build:/usr/share/nginx/html:ro \
        nginx:stable
export DESIGN_REF=http://192.168.77.1:7777/promenade.yaml

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. Generate join script for a node using:

URL=http://promenade-api.ucp.svc.cluster.local/api/v1.0/join-scripts?
URL="${URL}design_ref=${DESIGN_REF}"
URL="${URL}&hostname=<HOSTNAME>&ip=<IP>"
URL="${URL}&labels.dynamic=calico-etcd=enabled"
URL="${URL}&labels.dynamic=kubernetes-apiserver=enabled"
URL="${URL}&labels.dynamic=kubernetes-controller-manager=enabled"
URL="${URL}&labels.dynamic=kubernetes-etcd=enabled"
URL="${URL}&labels.dynamic=kubernetes-scheduler=enabled"
URL="${URL}&labels.dynamic=ucp-control-plane=enabled"
curl -Lo join-<NODE>.sh "${URL}"

4. Copy the join script to the node, and run it via bash join-<NODE>.sh.
5. Repeat 3 and 4 until all nodes are joined.
6. Reprovision the Genesis node by tearing it down as above in Basic Deployment, then generating and using a join script for it as done in 3 and 4.

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.