sborenst / hexboard

Hexboard UI

Container vizualization for OpenShift platformV3. As featured in the Red Hat Summit 2015 - JBoss Keynote demo

Table of Contents

• Basic Setup
  • Authentication
  • Create a project
• Builds
• Routing
• Configuration
• Scaling
• Auto-Recovery
• Local Development
  • Pre-Requisutes
  • Installation
  • Run the hexboard locally
• Cleanup

Basic Setup

To get started, you’ll need an OpenShiftV3 environment with a valid user account.

You can create your own environment in Amazon EC2 using the demo-ansible playbook.

To use a local VM with vagrant, follow the setup instructions from this workshop

Authentication

oc login <openshift-cluster-ip>
oc config view

After logging in, you’ll be able to fetch your cli tool’s ACCESS_TOKEN by running oc whoami -t for your openshift cluster and include it as needed in example commands.

Export this configuration detail to use it in the following examples as ${ACCESS_TOKEN}:

export ACCESS_TOKEN=$(oc whoami -t)

Create a project

Create a project to house this application:

oc new-project <project-name>

Install and launch the project from a template:

oc create -f https://raw.githubusercontent.com/2015-Middleware-Keynote/hexboard/master/app_template.json
oc process -v="ACCESS_TOKEN=${ACCESS_TOKEN}" hexboard | oc create -f -

Or, create each service individually:

oc new-app -l servicegroup=sketchpod openshift/nodejs-010-centos7~http://github.com/2015-Middleware-Keynote/sketchpod
oc new-app -e "ACCESS_TOKEN=${ACCESS_TOKEN}" openshift/nodejs-010-centos7~http://github.com/2015-Middleware-Keynote/hexboard

Then, check the results:

oc get builds -w

Builds

Docker image builds can be initiated by navigating to the "Builds" tab in the V3 web console. Click on the Start Build button for each service.

You can also initiate the builds from the command line:

oc start-build hexboard
oc start-build sketchpod

Watch the progress:

oc get pods -w

Routing

In order to view the hexboard, you’ll need to expose your service by setting up a Route. The optional --hostname flag allows you to create a custom route to an existing service:

oc expose se/hexboard --hostname=<your-hexboard-hostname>

Make sure this route is addressable from wherever you are running your browser (an /etc/hosts entry in your client may be required).

Excluding the --hostname flag should generate a default route that automatically takes advantage of your cluster’s wildcard DNS (if available):

oc expose se/hexboard

Now, try listing your existing routes:

oc get route

Configuration

The service configuration is provided via environment variables. These configs can be set while loading a project from a template via the web console or via the oc process command.

You can also add environment keys to an existing deployment config using the oc env command. Setting new configuration details will trigger a deployment to distribute your changes (if needed).

To set the required ACCESS_TOKEN config, follow the instructions in the above Authentication section, using your own ACCESS_TOKEN value in the following example:

oc env dc/hexboard ACCESS_TOKEN="${ACCESS_TOKEN}"

The number of pods in the hexboard can be controlled by setting the HEXBOARD_SIZE environment variable:

HEXBOARD_SIZE	# of pods
xlarge	1026	"keynote" sized
large	513	major league
medium	266	cluster pro
small	108	multi machine party
xsmall	63	fun sized
tiny	32	large laptop allocation
micro	24	medium laptop allocation
nano	12	small laptop allocation

oc env dc/hexboard HEXBOARD_SIZE=<hexboard-size>
oc get pods -w

Note	setting an environment variable triggers a new deployment, so watch the oc get pods -w output to see when the deployment is complete.

Scaling

Animations of falling hexagons are triggered as the number of pods is scaled. To scale the number of hexagons (either up or down) run the command:

oc scale rc/sketchpod-1 --replicas=<number>

After scaling up, try submitting sketches by visiting the hexboard’s bundled mobile web submission form, at http://your-hexboard-hostname/mobile/.

Auto-Recovery

After scaling up, the hexboard provides a nice way to visualize Kubernetes' support for auto-healing the containerized environments.

You can show this functionality by deleting a group of pods. This example makes it easy find and delete five pods:

oc delete pod $(oc get pods | grep ^sketchpod | grep -v build | sed -e "s/^\(sketchpod-[0-9]*-[a-z0-9]*\)[ \t].*/\1 /" | head -n 5 | tr -d "\n" )

Local Development

Pre-Requisutes

• node.js (installed globally)

• gulp.js (installed globally)

Installation

Execute the following commands in your local clone of this repository:

npm install

Run the hexboard locally

Run gulp in it’s own terminal, providing environment variables that reference an available OpenShift cluster where your sketchpod service back-ends will be hosted and scaled:

PORT=8081 PROXY="localhost:1080" ACCESS_TOKEN="${ACCESS_TOKEN}" OPENSHIFT_SERVER="localhost:8443" NAMESPACE=hexboard gulp

Cleanup

To delete all sketchpods using a labelselector, try this:

oc delete all -l servicegroup=sketchpod

You can clean out the entire contents of the hexboard project by running the following:

oc delete all --all -n hexboard

Tip	Be careful to verify that you have logged into the correct server, and have selected the correct project before running this command!

Or, delete the entire project and any included resources:

oc delete project hexboard