registry

Amalgam8 Registry

The Amalgam8 Registry is a multi-tenant, highly-available service for service registration and service discovery in microservice applications.

High Availability: For high availability, run the Registry in clustered mode, where data in memory is replicated across registry instances. Alternatively, the Registry supports a Redis backend for storing instance information. In this mode, the Registry instances are stateless and can be scaled using standard autoscaling techniques. In tandem, the data store backend, i.e., Redis, needs to be deployed in HA mode. Please refer to the Redis Clustering documentation for details on setting up a highly available Redis backend.

In both cases, the Registry provides eventual consistency for data synchronization across Registry instances.

Extensibility: The Registry is built using an extensible catalog model that allows the user to update the Amalgam8 Registry with information stored in other service registries such as Kubernetes, Consul, etc. In addition, the Registry can be used as a drop-in replacement for Netflix Eureka with full API compatibility. Eureka compatibility enables the Registry to be used with Java clients using Netflix Ribbon.

Authentication & Multi-tenancy: By default, the Registry operates in a single-tenant mode without any authentication. In multi-tenant mode, it supports two authentication mechanisms: a trusted auth mode for local testing and development purposes, and a JWT auth mode for production deployments.

See https://www.amalgam8.io/docs for detailed documentation.

Usage

To get started, use the current stable version of the Registry from Docker Hub.

docker run amalgam8/a8-registry:latest

Command Line Flags and Environment Variables

The Amalgam8 Registry supports a number of configuration options, most of which are set through environment variables. The environment variables can be set via command line flags as well.

The following environment variables are available. All of them are optional.

Registry Configuration

Authentication and Authorization

The Amalgam8 Registry supports multi-tenancy by isolating each tenant into a separate namespace. A namespace is defined by an opaque string carried in the HTTP Authorization header of API requests. The following namespace authorization methods are supported and controlled via the A8_AUTH_MODE environment variable (or --auth_mode flag):

• None: if no authorization mode is defined, all instances are registered into a default shared namespace.
• Trusted: namespace is retrieved directly from the Authorization header. This provides namespace separation in a trusted environment (e.g., single tenant with multiple applications or environments).
• JWT: encodes the namespace value in a signed JWT token claim.

If jwt is specified, A8_JWT_SECRET (or --jwt_secret) must be set as well to allow encryption and decryption. Namespace value encoding must be present in every API call using HTTP Bearer Authorization:

Authorization: Bearer jwt.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...wifQ.Gbz4G_O...NqdY`

Clustering

Amalgam8 Registry uses a memory only storage solution, without persistency (although different storage backends can be implemented). To provide HA and scale, the Registry can be run in a cluster and supports replication between cluster members. To use a persistent storage backend, see the section Persistent Backend Storage.

Peer discovery currently uses a shared volume between all members. The volume must be mounted RW into each container. We are exploring alternative discovery mechanisms.

Persistent Backend Storage

Amalgam8 Registry supports a Redis backend for storing instance information as an alternative to the memory only clustering and replication option.

Catalog Extensions

The Amalgam8 Registry supports read-only catalogs extensions. The content of each catalog extension (e.g., Kubernetes, Docker-Swarm, FileSystem, etc) is read by the Registry and returned to the user along with the content of the Registry itself.

REST API

Amalgam8 Registry API documentation is available in Swagger format.

Building from source

Please refer to the developer guide for prerequisites and instructions on how to setup the development environment.

Building a Docker Image

To build the docker image for the Amalgam8 Registry service, run the following commands:

cd $GOPATH/src/github.com/amalgam8/amalgam8
make build dockerize.registry

You should now have a docker image tagged a8-registry:latest.

Building an Executable

The Amalgam8 Registry can also be run outside of a docker container as a Go binary. This is not recommended for production, but it can be useful for development or easier integration with your local Go tools.

The following commands will build and run it as a Go binary:

cd $GOPATH/src/github.com/amalgam8/amalgam8
make build.registry
./bin/a8registry

Makefile Targets

The following Makefile targets are available.