microservice-tools

Package with shared tools for the microservices

This package provides tools that can be used by all microservices, such as:

• API for service registry (Self registration and unregistration of a microservice)

Installation

To install run:

go get -u github.com/Microkubes/microservice-tools

Install it from the private repository

You'll might get a problem when installing because the github repository is private.

By default go get will try to user a https:// to clone the repository. If you have a valid key for accessing the repository (in ~/.ssh/) run the following command to force git to use ssh:// as protocol for access and to use your access key for the repository:

git config --global url."ssh://[email protected]:".insteadOf "https://github.com"

Microservice self-registration

Configuring the microservice

The service configuration is loaded from a JSON config file. The file has the following structure:

{
  "name": "user-microservice",
  "port": 8080,
  "virtual_host": "user.services.jormugandr.org",
  "hosts": ["localhost", "user.services.jormugandr.org"],
  "weight": 10,
  "slots": 100
}

Fields:

• name - the name of the microservice. This name will be used to register the API with on Kong. This has to be the same for all instances of the microservices.
• port - local port of the microservice.
• virtual_host - this is the domain name for the services group. This has to be the same for all instances of the microservice.
• hosts - list of valid hosts that can access the microservice. You need to put at least the virtual_host here, otherwise you won't be able to access the API via the gateway.
• weight - an integer value used by the API gateway for load balancing.
• slots - maximal number of instances (targets) for the same microservice group. When registering a service with the gateway, each instance creates a target on the gateway associated with the virtual_host. When a request passes through the gateway, the HTTP header Host is inspected, and based on that the virtual_host is determined. Then the gateway passes (proxies) the request to a specific the microservice instance. This number specifies the maximal number of targets for a group like this.

Adding self-registration to a microservice

To add self-registration logic in your microservice, you need to create a gateway.Registration and then use SelfRegister().

Here is an example of self-registration with Kong:

import (
  // other imports here

  // import the gateway package
  gateway "microservice-tools/gateway"
)

// other code in the main.go file

func main(){
  // load the Gateway URL and the config file path
  gatewayURL, configFile := loadGatewaySettings()

  // creates new Kong gateway.Registration with the config settings. We pass the default http client here.
  registration, err := gateway.NewKongGatewayFromConfigFile(gatewayURL, &http.Client{}, configFile)
  if err != nil {
    // if there is an error, it means we failed to build Registration for Kong.
    panic(err)
  }
  // at this point we do a self-registration by calling SelfRegister
  err = registration.SelfRegister()
  if err != nil {
    // if there is an error it means we failed to self-register so we panic with error
    panic(err)
  }

  // the unregistration is deferred for after main() executes. If we shut down
  // the service, it is nice to unregister, although it is not required.
  defer registration.Unregister()


  // rest of the code for main goes here
}

// loadGatewaySettings loads the API Gateway URL and the path to the JSON config file from ENV variables.
func loadGatewaySettings() (string, string) {
  gatewayURL := os.Getenv("API_GATEWAY_URL")
  serviceConfigFile := os.Getenv("SERVICE_CONFIG_FILE")

  if gatewayURL == "" {
    gatewayURL = "http://localhost:8001"
  }
  if serviceConfigFile == "" {
    serviceConfigFile = "config.json"
  }

  return gatewayURL, serviceConfigFile
}

Healthcheck

To add healthcheck to your microservice you need to mount the healtcheck middleware in the microservice main file:

service.Use(healthcheck.NewCheckMiddleware("/healthcheck"))

To test it out, build the microservice locally and do curl http://localhost:8080/healtcheck

It should return OK.

Version endpoint

To add version endpoint to your microservice, first you need to add the version of the microservice into configuration JSON file, for example:

{
    "version": "v1.0.0"
}

Next, mount the version endpoint middleware in the microservice main file:

service.Use(version.NewVersionMiddleware(cfg.Version, "/version"))

To test it out, build the microservice locally and do curl http://localhost:8080/version

It should return the microservice version.

Contributing

For contributing to this repository or its documentation, see the Contributing guidelines.