Hello World!

This demo starts two versions of a helloworld microservice each with two versions, in order to demonstrate how Amalgam8 can be used to split incoming traffic between the two versions. You can define the proportion of traffic to each microservice as a percentage.

Deploy and Scale the App

The commands to deploy the helloworld demo application for different environments are as follows:

Docker Compose

1. Bring up the containers:

   docker-compose -f examples/docker-helloworld.yaml up -d
   

2. Scale the individual versions as follows:

   docker-compose -f examples/docker-helloworld.yaml scale helloworld-v1=2
   docker-compose -f examples/docker-helloworld.yaml scale helloworld-v2=2
   

3. Set the gateway environment variable:

   export GATEWAY_URL=localhost:32000
   

   Note: If you are using Docker Machine, use $(docker-machine ip default):32000 instead of localhost:32000

Kubernetes on localhost or on Google Cloud

1. Bring up the containers:

   kubectl create -f examples/k8s-helloworld.yaml
   

   The above command automatically launches two instances of each version of helloworld.

2. Set the gateway environment variable:

   export GATEWAY_URL=$(minikube ip):32000
   

IBM Bluemix

1. Create Bluemix routes (DNS names) for the registry, controller and the helloworld app’s gateway:

   bluemix cf create-route <your bluemix space> mybluemix.net -n <your helloworld route>
   

2. Specify the route name in the examples/bluemix.cfg in the HELLOWORLD_HOSTNAME variable.

3. Deploy the helloworld application on bluemix.

   examples/a8-bluemix create helloworld
   

   The above command automatically launches two instances of each version of helloworld.

   Verify that the services are running using the following commands:

   bluemix ic groups
   

4. Set the gateway environment variable:

   export GATEWAY_URL=helloworld.mybluemix.net
   

Services in the App

There are 4 instances of the helloworld service. Two are instances of version “v1” and the other two belong to version “v2”.

Version-based routing

1. Lets send all traffic to the v1 version of helloworld. Run the following command:

   a8ctl rule-create -f examples/docker-helloworld-default-route-rules.json
   

2. We can confirm the routes are set by running the following command:

   a8ctl route-list
   

   You should see the following output:

   +------------+-----------------+-------------------+
   | Service    | Default Version | Version Selectors |
   +------------+-----------------+-------------------+
   | helloworld | version=v1      |                   |
   +------------+-----------------+-------------------+
   

3. Confirm that all traffic is being directed to the v1 instance, by running the following cURL command multiple times:

   curl http://$GATEWAY_URL/helloworld/hello
   

   You can see that the traffic is continually routed between the v1 instances only, in a random fashion:

   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: version=v1, container: helloworld-v1-p8909
   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: version=v1, container: helloworld-v1-qwpex
   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: version=v1, container: helloworld-v1-p8909
   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: version=v1, container: helloworld-v1-qwpex
   ...
   

4. Next, we will split traffic between helloworld v1 and v2

   First, use the rule-delete command to delete all rules

   a8ctl rule-delete -a -f
   

   Run the following command to send 25% of the traffic to helloworld v2, leaving the rest (75%) on v1:

   a8ctl rule-create -f examples/helloworld-v1-v2-route-rules.json
   

   NOTE: It’s also possible to get the same results by using rule-get to get the rule ID and rule-update

5. Run this cURL command several times:

   curl http://$GATEWAY_URL/helloworld/hello
   

   You will see alternating responses from all 4 helloworld instances, where approximately 1 out of every 4 (25%) responses will be from a “v2” instances, and the other responses from the “v1” instances:

   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: v1, container: helloworld-v1-p8909
   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: v1, container: helloworld-v1-qwpex
   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: v2, container: helloworld-v2-ggkvd
   $ curl http://$GATEWAY_URL/helloworld/hello
   Hello version: v1, container: helloworld-v1-p8909
   ...
   

   Note: if you use a browser instead of cURL to access the service and continually refresh the page, it will always return the same version (v1 or v2), because a cookie is set to maintain version affinity. However, the browser still alternates in a random manner between instances of the specific version.

Cleanup

To remove the helloworld application,

Docker Compose

docker-compose -f examples/docker-helloworld.yaml kill
docker-compose -f examples/docker-helloworld.yaml rm -f

Kubernetes on localhost or on Google Cloud

kubectl delete -f examples/k8s-helloworld.yaml

IBM Bluemix

examples/a8-bluemix destroy helloworld