registry

README

Neighborhood Manager Service Registry

The Service Registry is a utility that will sit on the network and listen for services that advertise themselves via SSDP. The list of services a user wants to know about can be configured. When an advertisement is seen from a matching service, the Service Registry collects information about the service, and registers it with a storage backend of the user's choosing. Other applications can access this storage for aggregated information about all services on a network.

The Service Registry must have the ability to see multicast broadcasts from the services that advertise themselves. If there is a need to register services separated in multiple subnets, many instances of the Service Registry can be deployed to each broadcast domain and aggregation will still successfully occur.

Background Information

This section details how to set up a production environment for the Service Registry. If you are interested in a quick demo of the functionality, skip to the Try It Out section to start everything up quickly in containers.

Backend

Some type of storage backend is needed for the Service Registry to store information. At this time, the only backend supported is Consul.

The best practice for using Consul is to set up a cluster of at least three servers on different hosts, and run a client on the same host that the Service Registry will run on. This allows uninterrupted service if one of the servers in the cluster dies, and is more robust than running a server locally on the same host as the Service Registry.

Server

To create a cluster of Consul servers, reference this article on configuring consul, and see the section Creating the Bootstrap Configuration, then follow into the next section Creating the Regular Server Configuration

Client

When a cluster is in place, a consul client must be started on the same host that Service Registry will run on. The most extensible way to do this is to put all parameters in a config file, such as /etc/consul.d/client/config.json.

{
    "server":false,
    "datacenter": "dc1",
    "data_dir": "/var/consul",
    "log_level": "DEBUG",
    "enable_syslog": true,
    "start_join": ["192.168.1.1", "192.168.1.2", "192.168.1.3"],
    "bind_addr": "192.168.1.4"
}

Where the three addresses in the start_join field are the addresses of the three clustered servers, and the bind_addr field is the address of the host machine that this client will run on.

The consul client can then be started with consul agent -config-dir /etc/consul.d/client/config.json

Configuration of URN list

The Service Registry listens for services advertised by SSDP messages. These messages contain a URN that identifies the service, and an IP address where the service can be found.

To configure the list of services that the Service Registry should listen for, open the registry.json file in the source code. The schema for the configuration is:

{
    "ssdp":{
        "tags":{
            "Service-Tag":[
                "ServiceUrn",
                "ServiceUrn2"
            ],
            "ServiceTag2":[
                "ServiceUrn3",
                "ServiceUrn4"
            ]
        }
    }
}

In this file, the ServiceTag and ServiceTag2 identifiers under the tags field describe the services, and the ServiceUrn listings within them are the URNs found in matching SSDP messages.

The registry.json file found in the source code is currently configured to listen to advertisements from Inservice-Agent and RackHD

Building

We use docker to build our binaries. The following steps assume a host is installed with the latest docker version. Download the source from GitHub
git clone https://github.com/RackHD/neighborhood-manager.git

Build the dependencies
make deps

Build the Service Registry
make build

If the host system does not have docker installed the following commands can be run to build locally.

Build the dependencies
make deps-local

Build the Service Registry
make build-registry-local

Running

After building, the Service Registry binary (named registry) will be in the bin/ folder of the source directory. To run it from there, copy registry.json to that location.
cp registry/registry.json registry/bin/

Move to that directory and run the Service Registry.

cd registry/bin
./registry

Try It Out

The steps in this section will guide you through getting a test/dev environment up and running. Use these steps if you want to see the Service Registry in action.

Prerequisites

• Git
• Docker
• Docker-compose

Starting the environment

1. Change to a directory where you can clone the source code
2. git clone https://github.com/RackHD/neighborhood-manager.git
3. cd registry
4. make run-reg (Note that this will take some time when running for the first time. Docker has to pull several images from the internet. If any of the downloads fail, simply re-do the make run-reg command)

Interacting with the environment

You now have four docker containers running:

• Service Registry
• Consul Client
• Consul Server
• SSDP Spoofer

The SSDP Spoofer sends out dummy advertisement messages made to look like Inservice-Agent and RackHD. They are received by the Service Registry, passed to the Consul client, and sent to the Consul server for registration. You can interact with the Consul client in the same way the Service Registry does, to retrieve information that has been stored.

1. Open a new terminal prompt
2. Change to the neighborhood-manager source directory
3. make consul-shell

Now you can use the Consul Catalog API to interact with the backend storage. For example, to retrieve all services that have been registered:

root@c1208c34725f:/go/src/github.com/RackHD/neighborhood-manager# curl -s http://consulclient:8500/v1/catalog/services | python -mjson.tool
{
    "Inservice-service:agent:0.1": [],
    "Inservice-service:catalog-compute:0.1": [],
    "Inservice-service:lldp:0.1": [],
    "RackHD-device:on-http:1": [],
    "RackHD-service:api:1.1": [],
    "RackHD-service:api:2.0": [],
    "RackHD-service:redfish-rest:1.0": [],
    "consul": []
}

Notice the URL to which you are sending the request. The Docker containers have been configured in a way such that you can reference the container running the Consul client by name, even though the IP address of the container will change between runs. Port 8500 is the default port for HTTP communications in Consul.

As another example, to see all nodes that are offering the RackHD 2.0 API service:

root@50283b1b6a03:/go/src/github.com/RackHD/neighborhood-manager# curl http://consulclient:8500/v1/catalog/service/"RackHD-service:api:2.0" | python -mjson.tool
[
    {
        "Address": "192.168.1.1",
        "CreateIndex": 11,
        "ModifyIndex": 11,
        "Node": "228617159241066160",
        "ServiceAddress": "192.168.1.1",
        "ServiceEnableTagOverride": false,
        "ServiceID": "RackHD-service:api:2.0",
        "ServiceName": "RackHD-service:api:2.0",
        "ServicePort": 65535,
        "ServiceTags": []
    }
]

When you are done, run exit to stop the shell container, and docker-compose kill to stop the four containers running the Service Registry and its environment.

Documentation

Index

• type Registry
  • func NewRegistry(backend regStore.Backend, dc, backendAddr string) (*Registry, error)
  • func (p *Registry) AddSearchTerm(urn, tag string)
  • func (p *Registry) GetSearchTerms() map[string]string
  • func (p *Registry) NotifyAlive(message gossdp.AliveMessage)
  • func (p *Registry) NotifyBye(message gossdp.ByeMessage)
  • func (p *Registry) RemoveSearchTerm(urn string)
  • func (p *Registry) Response(message gossdp.ResponseMessage)
  • func (p *Registry) Run()
  • func (p *Registry) Start()
  • func (p *Registry) Stop()

Types

type Registry

type Registry struct {
	Store regStore.Registry
	// contains filtered or unexported fields
}

Registry is a service registry object

func NewRegistry

func NewRegistry(backend regStore.Backend, dc, backendAddr string) (*Registry, error)

NewRegistry creates a registry object

func (*Registry) AddSearchTerm

func (p *Registry) AddSearchTerm(urn, tag string)

AddSearchTerm adds a new tagged URN to the whitelist of SSDP URNs to act on

func (*Registry) GetSearchTerms

func (p *Registry) GetSearchTerms() map[string]string

GetSearchTerms returns the whitelist of SSDP URNs to act on

func (*Registry) NotifyAlive

func (p *Registry) NotifyAlive(message gossdp.AliveMessage)

NotifyAlive handles a NotifyAlive message from the SSDP listener

func (*Registry) NotifyBye

func (p *Registry) NotifyBye(message gossdp.ByeMessage)

NotifyBye handles a NotifyBye message from the SSDP listener

func (*Registry) RemoveSearchTerm

func (p *Registry) RemoveSearchTerm(urn string)

RemoveSearchTerm removes an entry from the whitelist of SSDP URNs to act on

func (*Registry) Response

func (p *Registry) Response(message gossdp.ResponseMessage)

Response handles an M-Search Response message

func (*Registry) Run

func (p *Registry) Run()

Run handles Service Registry startup

func (*Registry) Start

func (p *Registry) Start()

Start blocks until Stop is called

func (*Registry) Stop

func (p *Registry) Stop()

Stop closes a channel that should stop all capture