001c9ddc5ceb9829b6aaf24f5d28502a

I am software developer with a keen interest in open-source technologies, Linux, and native development. I've worked on many different platforms Android, iOS, Win32, Linux, FreeRTOS, the Web, and others. I've gone through the whole stack and I enjoy learning and using the latest technologies. I now work as a full-stack developer at Auth0.

Senior Engineer

Sebastian Peyrott

How the service registry works in a microservice-based architecture



In this post in the microservices series we will talk about *the service registry*. In [part 2](https://auth0.com/blog/2015/09/13/an-introduction-to-microservices-part-2-API-gateway/) we discussed the *API gateway*, where we mentioned that services are **registered in a database**. The gateway dispatches requests according to the information contained in that database. Below we will explore how that database is populated and in which way services, clients and the gateway interact with it.

-----

## The service registry
The service registry is a database populated with information on how to dispatch requests to microservice instances. Interactions between the registry and other components can be divided into two groups, each with two subgroups:

1. Interactions between microservices and the registry (registration)
    1. Self-registration
    2. Third-party registration
2. Interactions between clients and the registry (discovery)
    1. Client-side discovery
    2. Server-side discovery

### Registration
Most microservice-based architectures are in constant evolution. Services go up and down as development teams split, improve, deprecate and do their work. Whenever a service endpoint changes, the **registry needs to know about the change**. This is what *registration* is all about: who publishes or updates the information on how to reach each service.

**Self-registration** forces microservices to interact with the registry by themselves. **When a service goes up, it notifies the registry**. The same thing happens when the service goes down. Whatever additional data is required by the registry must be provided by the **service itself**. If you have been following this series, you know that microservices are all about dealing with a *single concern*, so self-registration might seem like an anti-pattern. However, for simple architectures, self-registration might be the right choice.

![Self-registration](https://images.ctfassets.net/23aumh6u8s0i/793utSBFno7ZnfY2JPkHBW/fc270d61c5b71b09820ffb889cdbfc1d/self-registration-diagram)

**Third-party registration** is normally used in the industry. In this case, there is a **process or service that manages all other services**. This process polls or checks in some way which microservice instances are running and it automatically **updates the service registry**. Additional data might be provided in the form of per-service config files (or policy), which the registration process uses to update the database. Third-party registration is commonplace in architectures that use tools such as [Apache ZooKeeper](http://zookeeper.apache.org/) or [Netflix Eureka](https://github.com/Netflix/eureka) and other service managers.

![Third-party-registration](https://images.ctfassets.net/23aumh6u8s0i/1kXBlTgwxs0IHFqGTfwxXL/46d98df79b3262697685eb4c24bb55f8/third-party-registration-diagram)

Third-party registration also provides other benefits. For instance, what happens when a service goes down? A third-party registration service might be configured to provide safe fallbacks for services that fail. Other policies might be implemented for other cases. For instance, the service registry process might be notified of a high-load condition and automatically add a new endpoint by requesting the instantiation of a new microservice-process or VM. As you can imagine, these possibilities are critical for big architectures.

### Discovery
As you can imagine, discovery is the counterpart to registration from the point of view of clients. When a client wants to access a service, it must find out **where the service is located** (and other relevant information to perform the request).

**Client-side discovery** forces clients to **query a discovery service** before performing the actual requests. As happens with *self-registration*, this requires clients to deal with additional concerns other than their main objective. The discovery service may or may not be located behind the API gateway. If it is not located behind the gateway, balancing, authentication and other cross-cutting concerns may need to be re-implemented for the discovery service. Additionally, each client needs to know the fixed endpoint (or endpoints) to contact the discovery service. These are all disadvantages. The one big advantage is not having to code the necessary logic in the gateway system. Study this carefully when picking your discovery method.

![Client-side discovery](https://images.ctfassets.net/23aumh6u8s0i/2IzcnDuO6qsOYF96uP3ron/bdd6cdc6f18ec352928e19f53287f079/client-side-discovery-diagram)

**Server-side discovery** makes the **API gateway handle the discovery** of the right endpoint (or endpoints) for a request. This is normally used in bigger architectures. As all requests are directly sent to the gateway, all the benefits discussed in relation to it apply (see [part 2](https://auth0.com/blog/2015/09/13/an-introduction-to-microservices-part-2-API-gateway/)). The gateway may also implement discovery caching, so that many requests may have lower latencies. The logic behind cache invalidation is specific to an implementation.

<include src="TweetQuote" quoteText="Server-side discovery makes the API gateway handle the discovery of the right endpoint for a request."/>

![Server-side discovery](https://images.ctfassets.net/23aumh6u8s0i/3FHSwwdLeOmBoLV5PvqNUM/07801774d85e25e330c74f01e5716a01/server-side-discovery-diagram)

## Example: A registry service
In [part 2](https://auth0.com/blog/2015/09/13/an-introduction-to-microservices-part-2-API-gateway/) we worked on a simple API gateway implementation. In that example we implemented dynamic dispatching of requests through queries to a service database. In other words, we implemented **server-side discovery**. For this example, we will extend our microservice architecture by working on the **registration** aspect. We will do so in two ways:

1. By providing a simple registration library that any development team can integrate into their microservice to perform **self-registration**.
2. By providing a sample [systemd unit](http://www.freedesktop.org/software/systemd/man/systemd.unit.html) that registers a service during startup or shutdown (**third-party registration** using systemd as a service manager).

> Why systemd? It has become the de-facto service manager in most Linux installations. There are other alternatives for managing your services but all require installation and configuration. For simplicity, we picked the one that comes preinstalled in most distros, and that is systemd.

### A registration library
Our microservice example from previous posts was developed for *node.js*, so our library will be for it as well. Here is the main logic of our library:

```javascript
module.exports.register = function(service, callback) {    
    if(!validateService(service)) {
        callback(new Error("Invalid service"));
    }

    findExisting(service.name, function(err, found) {
        if(found) {
            callback(new Error("Existing service"));
            return;
        }

        var dbService = new Service({
            name: service.name,
            url: service.url,
            endpoints: service.endpoints,
            authorizedRoles: service.authorizedRoles
        });

        dbService.save(function(err) {
            callback(err);
        });
    });
}

module.exports.unregister = function(name, callback) {
    findExisting(name, function(err, found) {
        if(!found) {
            callback(new Error("Service not found"));
            return;
        }

        found.remove(function(err) {
            callback(err);
        });
    });
}
```

Microservices that perform self-registration need to call these functions during startup or shutdown (including abnormal shutdowns). We have integrated this library into our existing microservice example in the following way (set the SELF_REGISTRY variable to any value to enable this function). Startup code:

```javascript
// Standalone server setup
var port = process.env.PORT || 3001;
http.createServer(app).listen(port, function (err) {
    if (err) {
        logger.error(err);
    } else {  
        logger.info('Listening on http://localhost:' + port);

        if(process.env.SELF_REGISTRY) {
            registry.register({
                name: serviceName,
                url: '/tickets',
                endpoints: [ {
                    type: 'http',
                    url: 'http://127.0.0.1:' + port + '/tickets'
                } ],
                authorizedRoles: ['tickets-query']
            }, function(err) {
                if(err) {
                    logger.error(err);
                    process.exit();
                }
            });
        }
    }
});
```

And shutdown code:

```javascript
function exitHandler() {
    if(process.env.SELF_REGISTRY) {
        registry.unregister(serviceName, function(err) {
            if(err) {
                logger.error(err);
            }
            process.exit();
        });
    } else {
        process.exit();
    }
}

process.on('exit', exitHandler);
process.on('SIGINT', exitHandler);
process.on('SIGTERM', exitHandler);
process.on('uncaughtException', exitHandler);
```

### Third-party registration using systemd
Our gateway example reads service information from a Mongo database. Mongo provides a command-line interface that we can use to register services during startup or shutdown. Here is a sample systemd unit (remember to disable the SELF_REGISTRY environment variable if you are using the sample microservice from this post):

```systemd
[Unit]
Description=Sample tickets query microservice

#Uncomment the following line when not running systemd in user mode
#After=network.target

[Service]
#Uncomment the following line to run the service as a specific user
#User=seba

Environment="MONGO_URL=mongodb://127.0.0.1:27018/test"

ExecStart=/usr/bin/node /home/seba/Projects/Ingadv/Auth0/blog-code/microservices/server.js
ExecStartPost=/usr/bin/mongo --eval 'db.services.insert({"name": "Tickets Query Service", "url": "/tickets", "endpoints": [{"type": "http", "url": "http://127.0.0.1:3001/tickets"}], "authorizedRoles": ["tickets-query"] });' 127.0.0.1:27017/test
ExecStopPost=/usr/bin/mongo --eval 'db.services.remove({"name": "Tickets Query Service"});' 127.0.0.1:27017/test

[Install]
WantedBy=default.target
```

Registration is handled by the *ExecStartPost* and *ExecStopPost* directives by calling the command-line Mongo client (included in all standard MongoDB installations).

Get the [code](https://github.com/auth0/blog-microservices-part3).

## Aside: use Auth0 for your microservices
Auth0 and microservices go hand-in-hand thanks to the magic of [JWT](http://jwt.io/). Check it out:

```javascript
var express = require('express');
var app = express();
var jwt = require('express-jwt');

var jwtCheck = jwt({
  secret: new Buffer('your-auth0-client-secret', 'base64'),
  audience: 'your-auth0-client-id'
});

app.use('/api/path-you-want-to-protect', jwtCheck);

// (...)
```

Your *client id* and *client secret* are available through the Auth0 dashboard. Create a new account and [start hacking](https://auth0.com/docs)!

## Conclusion
The service registry is an essential part of a microservice-based architecture. There are different ways of handling registration and discovery that fit different architectural complexities. Consider the pros and cons described above for each alternative before committing to one. In Part 4 we will study service dependencies in detail and how to manage them efficiently.


An Introduction to Microservices, Part 3: The Service Registry

Learn about API gateways and how they work in a microservice-based architecture



In this post in the microservices series we will talk about API gateways and how they can help us solve some important concerns in a microservice-based architecture. We described these and other issues in our [first post](https://auth0.com/blog/2015/09/04/an-introduction-to-microservices-part-1/) in the series.

-----

## What is an API gateway and why use it?

In all service-based architectures there are several concerns that are shared among all (or most) services. A microservice-based architecture is not an exception. As we said in the first post, microservices are developed almost in isolation. Cross-cutting concerns are dealt with by upper layers in the software stack. The API gateway is one of those layers. Here is a list of common concerns handled by API gateways:

- Authentication
- Transport security
- Load-balancing
- Request dispatching (including fault tolerance and service discovery)
- Dependency resolution
- Transport transformations

### Authentication
Most gateways perform some sort of authentication for **each request** (or series of requests). According to **rules** that are specific to each service, the gateway either routes the request to the requested microservice(s) or returns an error code (or less information). Most gateways add authentication information to the request when passing it to the microservice behind them. This allows microservices to implement **user specific logic** whenever required.

### Security
Many gateways function as a single entry point for a public API. In such cases, the **gateways handle transport security** and then dispatch the requests either by using a different secure channel or by removing security constraints that are not necessary inside the internal network. For instance, for a RESTful HTTP API, a gateway may perform **"SSL termination"**: a secure SSL connection is established between the clients and the gateway, and proxied requests are then sent over non-SSL connections to internal services.

<include src="TweetQuote" quoteText="Many gateways function as a single entry point for a public API."/>

### Load-balancing
Under high-load scenarios, gateways can **distribute requests among microservice-instances** according to custom logic. Each service may have specific scaling limitations. Gateways are designed to balance the load by taking these limitations into account. For instance, some services may scale by having multiple instances running under different internal endpoints. Gateways can dispatch requests to these endpoints (or even request the dynamic instantiation of more endpoints) to handle load.

### Request-dispatching
Even under normal-load scenarios, gateways can provide custom logic for dispatching requests. In big architectures, **internal endpoints are added and removed** as teams work or new microservice instances are spawned (due to topology changes, for instance). Gateways may work in tandem with service registration/discovery processes or databases that describe how to dispatch each request. This provides exceptional **flexibility** to development teams. Additionally, **faulty services** can be routed to backup or generic services that allow the request to complete rather than fail completely.

### Dependency resolution
As microservices deal with very specific concerns, some microservice-based architectures tend to become "chatty": to perform useful work, many requests need to be sent to many different services. For convenience and performance reasons, gateways may provide **facades** ("virtual" endpoints) that internally are **routed to many different microservices**.

### Transport transformations
As we learnt in the first post of this series, microservices are usually developed in isolation and development teams have great flexibility in choosing the development platform. This may result in microservices that return data and use transports that are **not convenient for clients** on the other side of the gateway. The gateway must perform the necessary **transformations** so that clients can still communicate with the microservices behind it.

## An API gateway example
Our example is a simple node.js gateway. It handles HTTP requests and forwards them to the appropriate internal endpoints (performing the necessary transformations in transit). It handles the following concerns:

### Authentication
Authentication using **JWT**. A single endpoint handles initial authentication: /login. User details are stored in a Mongo database and access to endpoints is restricted by roles.

```javascript
/*
 * Simple login: returns a JWT if login data is valid.
 */
function doLogin(req, res) {
    getData(req).then(function(data) {
        try {
            var loginData = JSON.parse(data);
            User.findOne({ username: loginData.username }, function(err, user) {
                if(err) {
                    logger.error(err);
                    send401(res);
                    return;
                }

                if(user.password === loginData.password) {
                    var token = jwt.sign({
                        jti: uuid.v4(),
                        roles: user.roles
                    }, secretKey, {
                        subject: user.username,
                        issuer: issuerStr
                    });

                    res.writeHeader(200, {
                        'Content-Length': token.length,
                        'Content-Type': "text/plain"
                    });
                    res.write(token);
                    res.end();                
                } else {
                    send401(res);
                }
            }, 'users');
        } catch(err) {
            logger.error(err);            
            send401(res);
        }
    }, function(err) {
        logger.error(err);            
        send401(res);
    });
}

/*
 * Authentication validation using JWT. Strategy: find existing user.
 */
function validateAuth(data, callback) {
    if(!data) {
        callback(null);
        return;
    }

    data = data.split(" ");
    if(data[0] !== "Bearer" || !data[1]) {
        callback(null);
        return;
    }

    var token = data[1];    
    try {
        var payload = jwt.verify(token, secretKey);
        //Your custom validation logic goes here.
        if(!payload.jti || revokedTokens[payload.jti]) {
            logger.debug('Revoked token, access denied: ' + payload.jti);
            callback(null);
        } else {        
            callback({jwt: payload});                
        }
    } catch(err) {
        logger.error(err);
        callback(null);
    }
}
```

> Disclaimer: the code shown in this post is not production ready. It is used just to show concepts. Don't copy paste it blindly :)

### Transport security
Transport security is handled through **TLS**: all public requests are received first by a reverse nginx proxy setup with sample certificates.

### Load balancing
Load-balancing is handled by **nginx**. See the sample [config](https://github.com/sebadoom/auth0/blob/master/microservices/gateway/nginx.conf).

### Dynamic dispatching, data aggregation and failures
Requests are **dynamically dispatched** according to a configuration stored in a database. Two types of requests are supported: HTTP and AMQP.

Requests also support the **aggregation strategy** for splitting requests among several microservices: a single public endpoint may aggregate data from many different internal endpoints (microservices). All returned data is in JSON format. See this excellent [post by Netflix](http://techblog.netflix.com/2013/01/optimizing-netflix-api.html) on how this strategy helped them achieve better performance. Also check our [post on Falcor](https://auth0.com/blog/2015/08/28/getting-started-with-falcor/) which allows for easy data fetching from many sources.

![Aggregation strategy](https://images.ctfassets.net/23aumh6u8s0i/5czB8vNeCDzOlE0SO9SYif/83a87ab75bd2bbe0a9a7d353ef33613d/aggregation)

**Failed internal requests** are handled by logging the error and returning less information than requested.

```javascript
/*
 * Parses the request and dispatches multiple concurrent requests to each
 * internal endpoint. Results are aggregated and returned.
 */
function serviceDispatch(req, res) {
    var parsedUrl = url.parse(req.url);

    Service.findOne({ url: parsedUrl.pathname }, function(err, service) {
        if(err) {
            logger.error(err);
            send500(res);
            return;
        }

        var authorized = roleCheck(req.context.authPayload.jwt, service);
        if(!authorized) {
            send401(res);
            return;
        }       

        // Fanout all requests to all related endpoints.
        // Results are aggregated (more complex strategies are possible).
        var promises = [];
        service.endpoints.forEach(function(endpoint) {   
            logger.debug(sprintf('Dispatching request from public endpoint ' +
                '%s to internal endpoint %s (%s)',
                req.url, endpoint.url, endpoint.type));

            switch(endpoint.type) {
                case 'http-get':
                case 'http-post':
                    promises.push(httpPromise(req, endpoint.url,
                        endpoint.type === 'http-get'));
                    break;
                case 'amqp':
                    promises.push(amqpPromise(req, endpoint.url));
                    break;
                default:
                    logger.error('Unknown endpoint type: ' + endpoint.type);
            }            
        });

        //Aggregation strategy for multiple endpoints.
        Q.allSettled(promises).then(function(results) {
            var responseData = {};

            results.forEach(function(result) {
                if(result.state === 'fulfilled') {
                    responseData = _.extend(responseData, result.value);
                } else {
                    logger.error(result.reason.message);
                }
            });

            res.setHeader('Content-Type', 'application/json');
            res.end(JSON.stringify(responseData));
        });
    }, 'services');
}
```

### Role checks
```javascript
var User = userDb.model('User', new mongoose.Schema ({
    username: String,
    password: String,
    roles: [ String ]
}));

var Service = servicesDb.model('Service', new mongoose.Schema ({
    name: String,
    url: String,
    endpoints: [ new mongoose.Schema({
        type: String,
        url: String
    }) ],
    authorizedRoles: [ String ]
}));

function roleCheck(jwt_, service) {
    var intersection = _.intersection(jwt_.roles, service.authorizedRoles);
    return intersection.length === service.authorizedRoles.length;
}
```

### Transport and data transformations
**Transport transformations** are performed to convert between HTTP and AMQP requests.

### Logging
**Logging** is centralized: all logs are published to the console and to an internal message-bus. Other services listening on the message-bus can take action according to these logs.

Get the full [code](https://github.com/sebadoom/auth0/tree/master/microservices/gateway).

## Aside: How webtask and Auth0 implement these patterns?

We told you about [webtasks](https://webtask.io) in our first post in the series. As webtasks *are* microservices they too run behind a gateway. The webtasks gateway handles authentication, dynamic-dispatching and centralized logging so that you don't have too.

* For authentication, [Auth0](https://auth0.com) is the issuer of tokens and webtask will verify those tokens. There is a trust relationship between them so that tokens can be verified.
* For real time logging webtask implemented a stateless resilient [ZeroMQ architecture](http://tomasz.janczuk.org/2015/09/from-kafka-to-zeromq-for-log-aggregation.html) which works across the cluster.
* For dynamic-dispatching, there is a custom-built Node.js proxy which uses [CoreOS etcd](https://github.com/coreos/etcd) as a pub-sub mechanism to route webtasks accordingly.

![Webtask](https://images.ctfassets.net/23aumh6u8s0i/26xA1D0RD9OZNmwuVPCCFw/6395ac83c869db331a701848bfa0e59f/webtask)

## Conclusion
API gateways are an essential part of any microservice-based architecture. Cross-cutting concerns such as authentication, load balancing, dependency resolution, data transformations and dynamic request dispatching can be handled in a convenient and generic way. Microservices can then focus on their specific tasks without code-duplication. This results in easier and faster development of each microservice.


"API-gateway"