Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jvandevelde/distributed-playground

Distributed service playground with Vagrant, Consul, Docker & ASP.NET Core
https://github.com/jvandevelde/distributed-playground

Last synced: 8 months ago
JSON representation

Distributed service playground with Vagrant, Consul, Docker & ASP.NET Core

Awesome Lists containing this project

README 

          
= Getting Started

:imagesdir: docs/images

ifdef::env-github[]

:note-caption: :information_source:

:tip-caption: :bulb:

:warning-caption: :warning:

:important-caption: :exclamation:

endif::[]



== Contents

link:README.adoc[Overview (This page)]



link:docs/logging.adoc[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. *https://www.vagrantup.com/[Vagrant]* - Virtual machine creation, provisioning & orchestration

2. *https://www.consul.io/[Consul]* - Service registry & discovery platform

3. *https://www.docker.com/[Docker]* - Service hosting environment allowing for easy deployment of multi-instance

services

4. *https://get.asp.net/[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. *https://github.com/eBay/fabio[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



image::system_overview.png[]



== Required Software



1. https://www.vagrantup.com/downloads.html[Vagrant]

2. https://www.virtualbox.org/wiki/Downloads[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

+

WARNING: 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

+

.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

+

.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

+

.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`



NOTE: 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 https://gist.github.com/fernandoaleman/5083680[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 https://github.com/dotless-de/vagrant-vbguest/[Github]



=== Windows 10



WARNING: 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

+

.ToolBox 1.10.2 Software

|===

|Package|Version

|Docker

|v1.10.2

|VirtualBox

|v5.0.14