Getting Started

Contents

Overview (This page)

Logging System Details

Overview

This repository contains utilizes the following stack to create a distributed service environment that could be utilized to experiment with micro-services, ASP.NET Core and any other tech stacks that require some part of the stack already available.

1. Vagrant - Virtual machine creation, provisioning & orchestration

2. Consul - Service registry & discovery platform

3. Docker - Service hosting environment allowing for easy deployment of multi-instance services

4. ASP.NET 5/Core - A demo service is written using ASP.NET Core and built as a Docker image automatically as part of the Vagrant provisioning of the docker-1 & docker-2 machines. This image is then used to create several instances of the service on each host machine.

5. Fabio HTTP Router - Front-end service router to make it easy to access services via a specific address/port. Each request is automatically redirected and balanced across all available service instances, wherever they are actually located

   Fabio & Consul

   Fabio utilizes Consul as a backend to configure itself and immediately have new instances of a service available for request routing (vs needing to configure a load balancer each time an new service instance is available or moves)

Environment Diagram

Required Software

1. Vagrant

2. Virtual Box

   Currently VirtualBox is the only provider supported in the repository’s Vagrantfile. This may be expanded in the future to work with Hyper-V/AWS/Azure/Digital Ocean

   ⚠️

   If installing VirtualBox on a Windows 8+ machine, you will need to make sure to disable and/or un-install Hyper-V before being able to use VirtualBox. Un-installing the Hyper-V Windows feature should not remove any existing Virtual Machine images and is fairly quick to do. This is one reason I would like to build Hyper-V support into the Vagrantfile in the future.

Quickstart

1. Add the ubuntu/trusty64 box to your Vagrant installation by running

   vagrant box ubuntu/trusty64

2. Clone this repository

3. From the repository location open a command prompt and run

   vagrant up

Once the machines have been created and provisioned by Vagrant, you should be able to do the following:

• The demo Hello World service can be accessed via the Fabio Router address on port 9999. Making multiple requests to this address will result in those requests being automatically balanced across all running instances of the service container across the Docker hosts. The service response includes which host & instance returned the result

  http://172.28.128.31:9999

• To view the Fabio HTTP Router Web UI to view all registered service instances:

  http://172.28.128.31:9998

• Access the Consul Web UI to view all available services

  http://172.28.128.30:8500/ui/

• View all services and instances registered with Consul by using the Consul REST API(s) on any of the ext-n machines

  Table 1. Consul REST API examples

  Task	URL
  Query for all registered services (Can query all consul instances)	http://172.28.128.10:8500/v1/catalog/services http://172.28.128.11:8500/v1/catalog/services http://172.28.128.12:8500/v1/catalog/services
  Query details of a specific service	http://172.28.128.11:8500/v1/catalog/service/demosvc.1

• Access the ElasticSearch REST APIs directly running on the ext-1, ext-2, ext-3 nodes

  Table 2. ElasticSearch REST API

  Task	URL
  Query details of a specific ES node	http://172.28.128.10:9200
  Query cluster status (Can query all consul instances)	http://172.28.128.10:9200/_cluster/health http://172.28.128.11:9200/_cluster/health http://172.28.128.12:9200/_cluster/health

• Two ElasticSearch Management Plugins are also available that make viewing cluster information much simpler via their Web UIs

  Table 3. Accessing ElasticSearch Plugins

  Plugin	URL
  ElasticSearch HQ	http://172.28.128.10:9200/_plugin/hq
  ElasticSearch HEAD (much older)	http://172.28.128.10:9200/_plugin/head

• SSH into the Docker hosts to inspect Docker container status

  vagrant ssh docker-1

  Once inside the Docker host, you can query Docker via

  docker ps (view all running containers)

  docker ps -a (view all containers)

Minimal startup

A minimal startup of the environment requires at least one Consul server, a Docker host to run services on and the Fabio HTTP router.

To create and/or start only these Virtual machines, you can run:

• run vagrant up ext-1 docker-1 httprouter

Machine Descriptions

1. ext-1, ext-2, ext-3

   These machines host clusters outside of Docker. Currently only the Consul cluster is hosted on these virtual machines. Doing it this way may not be strictly necessary but in the future Docker Swarm may be introduced which also requires a service registry to be available and I’m not sure if it can be hosted on the Docker hosts being placed into a swarm.

   ElasticSearch master nodes may also be hosted on these machines in the future

2. docker-1, docker-2

   These machines host Docker and automatically get provisioned with:

   • Registrator
     Used to automatically register any running Docker containers with the Consul cluster making them available to be discovered

   • Consul Client
     Used to communicate with the main Consul cluster hosted on ext-1, ext-2 & ext-3

ℹ️

Registrator communicates with Consul via this container instead of the main Consul cluster nodes. Because the cluster server nodes are responsible for managing cluster state/health, it is recommended to use lighter weight Consul agent in client mode to perform service registration/discover requests which are then forwarded to the server nodes.

Debugging

Vagrant & VirtualBox Guest Additions Versioning

The ubuntu\trusty64 Vagrant boxes do not always have the most current VirtualBox Guest additions installed on them which causes a warning message to be displayed when originally creating a Vagrant machine (ie: during 'vagrant up'). This message indicates that this condition could also cause the setup of Vagrant’s synced folders to fail.

This has occasionally happened to me after upgrades of Docker or Vagrant. While the machines still work, Vagrant breaks out of provisioning any remaining machines when it can’t setup synced folders.

You can address this in a couple of ways:

1. Manually install the correct version of the Guest Additions and update your local box definition with vagrant package See this gist for more details

   Note This isn’t a great solution because you would need to perform this for every box update you want might want to use

2. Install the 'vagrant-vbguest' plugin that ensures the latest Virtual Box Guest Addtions package gets installed on each Vagrant machine as it’s being created. You can do this by running the following command:

   vagrant plugin install vagrant-vbguest

   You can update this plugin with:

   vagrant plugin update vagrant-vbguest

   For more information, visit the project repository on Github

Windows 10

⚠️

I’ve run into problems individually updating and running the latest Docker Toolbox, Vagrant and Virtual Box on the latest Windows 10 Update (Version 1511 - released March 8th, 2016). Doing so may result in problems with Vagrant or the Docker Toolbox Quickstart Terminal not starting up properly due to "Network interface issues" This appears to have something to do with the discussion found here: http://stackoverflow.com/questions/33725779/failed-to-open-create-the-internal-network-vagrant-on-windows10

I was not able to get all 3 tools to work together until I did the following:

1. Uninstall Docker Toolbox

2. Uninstall Virtual Box

3. Download and install an older version (10.2.2) of Docker Toolbox

   https://github.com/docker/toolbox/releases/download/v1.10.2/DockerToolbox-1.10.2.exe

   This version of Docker Toolbox will install the following software/versions

   Table 4. ToolBox 1.10.2 Software

   Package	Version
   Docker	v1.10.2
   VirtualBox	v5.0.14