Running services

Now that we have Armada ready, let's try to run a simple service on it. We will use a service called example which lets us see its system environment variables through HTTP api.

$ armada run example
Running microservice example from dockyard: dockyard.armada.sh (alias: armada) locally... Service is running in container 789731dc0ca4 available at addresses: 192.168.3.141:49156 (80/tcp)

Listed address is main service endpoint (mapping to port 80 inside service container). So, let's check what our service can do:

$ curl 192.168.3.141:49156
{ "HOSTNAME": "789731dc0ca4", "MICROSERVICE_APT_GET_UPDATE_DATE": "2014-08-11", "CEREBRO_BASIC_APT_GET_UPDATE_DATE": "2014-07-14", "MICROSERVICE_NAME": "example", "SUPERVISOR_PROCESS_NAME": "example", "SUPERVISOR_SERVER_URL": "unix:///var/run/supervisor.sock", "RESTART_CONTAINER_PARAMETERS": "eyJlbnZpcm9ubWVudCI6IHsiTUlDUk9TRVJWSUNFX05BTUUiOiAiZXhhbXBsZSJ9L CAiY29udGFpbmVyIjogImV4YW1wbGUiLCAicG9ydHMiOiB7fSwgInZvbHVtZXMiOiB7Ii92YXIvcnVuL2RvY2tlci5zb2NrIj ogIi92YXIvcnVuL2RvY2tlci5zb2NrIn19", "SUPERVISOR_ENABLED": "1", "HOME": "/", "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "SUPERVISOR_GROUP_NAME": "example" }

It works :) Meaning of those variables is not that important at the moment.

Important thing is that running a service through Armada is as simple as typing armada run example.

Service environments

Now we'll run another instance of example service with a twist. We'll provide it with extra environment variable by using parameter -e.

$ armada run example -e "EXTRA_VARIABLE=crazy-variable-11"
Running microservice example from dockyard: dockyard.armada.sh (alias: armada) locally... Service is running in container a9992ef1f772 available at addresses: 192.168.3.141:49158 (80/tcp)
$ curl 192.168.3.141:49158
{ "EXTRA_VARIABLE": "crazy-variable-11", "HOSTNAME": "a9992ef1f772", ...(skipped)... }

As we can see, our extra parameter is present on the list. armada run command allows us to provide as many -e parameters as needed. They can be used to alter behavior of the service, for example differentiating development from production instance.

Now let's try another Armada command list:

$ armada list
Name Address ID Status Tags armada 192.168.3.141:49153 ae148a2d3a1a passing - example 192.168.3.141:49156 789731dc0ca4 passing - example 192.168.3.141:49158 a9992ef1f772 passing -

It lets us see all services running in Armada cluster (including armada itself).
Service ID is globally unique id of container with the service.
Status is one of passing, warning, critical depending on service health checks.
Tags are some extra information about a service.

Ok, so looking on the list, how do we know which example service is the first and which is the second one? Right now it's easy, but when service catalog grows to many more services it can be much harder. To help us differentiate the service we can use another armada run parameter:

$ armada run example --env funny-service
Running microservice example from dockyard: dockyard.armada.sh (alias: armada) locally... Service is running in container f7a09fb19009 available at addresses: 192.168.3.141:49160 (80/tcp)
$ armada list
Name Address ID Status Tags armada 192.168.3.141:49153 ae148a2d3a1a passing - example 192.168.3.141:49156 789731dc0ca4 passing - example 192.168.3.141:49158 a9992ef1f772 passing - example 192.168.3.141:49160 f7a09fb19009 passing ['env:funny-service']

Aha! As we can see using the parameter --env helps us spot specific instance of the service right away. Internally --env parameter is just a shorthand for using -e "MICROSERVICE_ENV=funny-service", what we can prove by running:

$ curl 192.168.3.141:49160
{ "HOSTNAME": "f7a09fb19009", "MICROSERVICE_ENV": "funny-service", ...(skipped)... }

The environment variable MICROSERVICE_ENV sits right there.

Other fun stuff

So far we have run our example services only on local host. But with Armada running it on some remote host (ship) would be just as simple: armada run example --ship johnny-ship. We'll cover the topic of many ships in one armada in more details later.

We have run some services, we obviously also have a way to stop them:

$ armada stop 789
Stopping service 789... Service has been stopped.
$ armada list
Name Address ID Status Tags armada 192.168.3.141:49153 ae148a2d3a1a passing - example 192.168.3.141:49158 a9992ef1f772 passing - example 192.168.3.141:49160 f7a09fb19009 passing ['env:funny-service']

We didn't have to write full service ID, only few first characters which uniquely select our service. If you are familiar with docker commands, it works the same way. If we had only one example service we could also write armada stop example.

If you're still longing to learn more about Armada, please go to Building services part.