Basic service discovery.

Armada is well suited for running backend services. It provides few alternative ways for finding the address where some service is running. One of them is discovery by domain name, currently available for HTTP services.
The solution consists of two core Armada services running on Armada platform: main-haproxy and magellan. main-haproxy runs HAProxy configured to direct HTTP requests for specific domain to corresponding service registered in the Armada catalog. magellan is responsible for providing main-haproxy with appropriate configuration file.

HAProxy is a very fast and reliable piece of software that can redirect TCP and HTTP-based traffic. The idea for using it to aid service discovery is similar to the one used at SmartStack.

Suppose we want to access our coffee-counter service through URL Replace with any other domain that you are in control of. We need:

  1. Service coffee-counter running and registered in the Armada catalog.
  2. Service main-haproxy running on one or more of our ships.
  3. Ability to direct domain's traffic to our main-haproxy.
  4. Service magellan running on one of our ships.
  5. Service magellan configured to link domain to service coffee-counter.

We've already covered step 1 before, so that's an instant check. If you are able to run coffee-counter service on already existing Armada cluster with main-haproxy & magellan already configured you can skip steps 2-4 and go to setup magellan.

Step 2. Run main-haproxy.

We can run main-haproxy with the following command:

$ armada run main-haproxy -p 80:80 --env dev/guide
Running microservice main-haproxy from dockyard: (alias: armada) locally... Service is running in container 908d83383b40 available at addresses: (80/tcp)
$ armada list
Name Address ID Status Tags armada a765ce08de9f passing - coffee-counter 08991fb89f72 passing - main-haproxy 908d83383b40 passing ['env:dev/guide']

Parameter -p 80:80 instructs Armada to assign container's internal port 80 (the one after colon) to port 80 on the host machine (the one before colon) without choosing it randomly.
Port 80 is a port that HAProxy service inside main-haproxy listens on. Parameter --env dev/guide will be used to find this specific instance of main-haproxy by magellan service.

Step 3. Direct traffic to main-haproxy.

You should configure your domain ( to point to the IP of the ship that main-haproxy runs on.
You can configure just the domain or use a wildcard such as * The second approach is favorable if you can afford it, as then you will be able to discover further Armada services without going back to configuring each domain separately.

If you just want to play with Armada without changing any DNS records, for the purpose of this guide you can redirect the domain in /etc/hosts file:

$ sudo sh -c "echo >> /etc/hosts"

Unfortunately redirecting all subdomains (* at once is not possible that way.

Step 4. Run magellan.

We have to let magellan know which main-haproxy's configuration it should take care of. We can do it by running it with the same enviroment set:

$ armada run magellan --env dev/guide
Running microservice magellan from dockyard: (alias: armada) locally... Service is running in container 30ae20b5837f available at addresses: (80/tcp)
$ armada list
Name Address ID Status Tags armada a765ce08de9f passing - coffee-counter 08991fb89f72 passing - magellan 30ae20b5837f passing ['env:dev/guide'] main-haproxy 908d83383b40 passing ['env:dev/guide']

It is running but doesn't do anything very useful yet. Let's give it some services to discover then.

Step 5. Setup magellan.

Magellan utilizes "Armada way" of service configuration called hermes. You can find more information about it in the next chapter. Right now it will be sufficient to know that magellan config should be placed under the directory /etc/opt/magellan-config.

If you are operating on an already existing Armada cluster, it may be possible that there is a service named courier running. It can automatically put services' configuration into directory under /etc/opt/ after committing it to the git repository that holds it. You can ask your Armada cluster administrator if it is configured in such a way, and if so is there any git repository through which you can configure magellan.

If there is no courier service running on your Armada, you can write magellan configuration manually:

$ mkdir -p /etc/opt/magellan-config
$ vim /etc/opt/magellan-config/domains-coffee-counter.json
...edit file... { "": { "protocol": "http", "service_name": "coffee-counter" } }

If directory /etc/opt/magellan-config didn't exist at the time magellan service was started, we have to let it know that the configuration is now available. It's sufficient to restart the service:

$ armada restart magellan
Restarting service magellan... Stopping service 30ae20b5837f... Service has been stopped. Running microservice magellan from dockyard: (alias: armada) locally... Service has been restarted and is running in container 58cb71ec7835 available at addresses: (80/tcp)

To verify if the magellan works as expected we can query its main endpoint:

$ curl
{ "": [ "" ] }

It tells us that it will configure main-haproxy in a way that it will direct all requests for domain to address
As you may remember that's exactly the address of our coffee-counter service! Let's finally test it:

$ curl -X POST
Peter's coffee count is now 5.

Yes! That's exactly what we wanted to achieve.
No matter what port will Docker randomly assign to our service, the magellan will take care of configuring main-haproxy so that the domain will always point at it.

Additional info.

Using magellan & main-haproxy as described above has also other advantages.
If we run more than one instance of our coffee-counter service (likely on different ships), magellan will find all of them and configure main-haproxy to round robin among them. Thus we get load balancing almost "for free".
Services that enter critical state (for example because of ship failure) will automatically drop out from the round robin. Hence the emphasis on using/writing proper health checks. That topic is discussed in more details here.

More details on that service duo, as well as information about other available service discovery methods can be found here.

If you want to learn more about service configuration please proceed to the next chapter.