sidecar

Sidecar

Ambassador pattern for microservices made simple and powerful. The Amalgam8 sidecar enables intelligent request routing while automating service registration, discovery, and client-side load-balancing. The Amalgam8 sidecar is based on Go+Nginx and follows an architecture similar to Netflix Prana sidecar or AirBnB Smartstack.

Documentation related to the sidecar can be found at https://amalgam8.io/docs

TL;DR

• Install the sidecar in your Dockerized microservice

  RUN curl -sSL https://github.com/amalgam8/amalgam8/releases/download/${VERSION}/a8sidecar.sh | sh
  

• Launch your app via the sidecar

  ENTRYPOINT ["a8sidecar", "--register", "--proxy", "--supervise", "YOURAPP", "YOURAPP_ARG", "YOURAPP_ARG"]
  

• Inject environment variables into your container

  A8_SERVICE=service_name:service_tags
  A8_ENDPOINT_PORT=port_where_service_is_listening
  A8_ENDPOINT_TYPE=http|https
  A8_REGISTRY_URL=http://a8registryURL
  A8_CONTROLLER_URL=http://a8controllerURL
  

• Make API calls to other microservices via the sidecar

  http://localhost:6379/<serviceName>/<endpoint>

• Control traffic to different versions of microservices using the a8ctl utility

  a8ctl route-set serviceName --default v1 --selector 'v2(user="Alice")' --selector 'v3(user="Bob")'
  

1. Integrating the sidecar into your application

Single Docker container

Add the following line to your Dockerfile to install the sidecar in your docker container:

RUN curl -sSL https://github.com/amalgam8/amalgam8/releases/download/${VERSION}/a8sidecar.sh | sh

or

RUN wget -qO- https://github.com/amalgam8/amalgam8/releases/download/${VERSION}/a8sidecar.sh | sh

Replace ${VERSION} with the specific version of Amalgam8 you would like. The set of releases are available here.

Optional app supervision: The sidecar can serve as a supervisor process that automatically starts up your application in addition to the Nginx proxy. To use the sidecar to manage your application, add the following lines to your Dockerfile

ENTRYPOINT ["a8sidecar", "--supervise", "YOURAPP", "YOURAPP_ARG", "YOURAPP_ARG"]

If you wish to manage the application process by yourself, then make sure to launch the sidecar in the background when starting the docker container. The environment variables required to run the sidecar are described in detail below.

Kubernetes Pods

With Kubernetes, the sidecar can be run as a standalone container in the same Pod as your application container. No changes are needed to the application's Dockerfile. Modify your service's YAML file to launch the sidecar as another container in the same pod as your application container. The latest version of the sidecar is available in Docker Hub in two formats:

• amalgam8/a8-sidecar - ubuntu-based version
• amalgam8/a8-sidecar:alpine - alpine linux based version

2. Starting the sidecar

The following instructions apply to both Docker-based and Kubernetes-based installations. There are two modes for running the sidecar:

With automatic service registration only

For leaf nodes, i.e., microservices that make no outbound calls, only service registration is required. Inject the following environment variables while launching your application container in Docker or the sidecar container inside kubernetes

A8_PROXY=false
A8_REGISTER=true
A8_REGISTRY_URL=http://a8registryURL
#A8_REGISTRY_TOKEN=a8registry_auth_token #if registry is used in multi-tenant mode
#A8_REGISTRY_POLL=polling_interval_between_sidecar_and_registry(5s)
A8_SERVICE=service_name:service_tags
A8_ENDPOINT_PORT=port_where_service_is_listening
A8_ENDPOINT_TYPE=http|https|tcp|udp|user

With automatic service registration, discovery & intelligent routing

For microservices that make outbound calls to other microservices, service registration, service discovery and client-side load balancing, version-aware routing are required.

A8_REGISTER=true
A8_REGISTRY_URL=http://a8registryURL
#A8_REGISTRY_TOKEN=a8registry_auth_token #if registry is used in multi-tenant mode
#A8_REGISTRY_POLL=polling_interval_between_sidecar_and_registry(5s)
A8_SERVICE=service_name:service_tags
A8_ENDPOINT_PORT=port_where_service_is_listening
A8_ENDPOINT_TYPE=http|https|tcp|udp|user

A8_PROXY=true
A8_LOG=false
A8_CONTROLLER_URL=http://a8controllerURL
#A8_CONTROLLER_TOKEN=a8controller_auth_token #if controller is used in multi-tenant mode
#A8_CONTROLLER_POLL=polling_interval_between_sidecar_and_controller(5s)

Update propagation: The sidecar will periodically poll the Amalgam8 Controller for rule updates, and the Amalgam8 Registry for to obtain list of registered instances of various microservices.

Request logs: All logs pertaining to external API calls made by the Nginx proxy will be stored in /var/log/nginx/a8_access.log and /var/log/nginx/error.log. The access logs are stored in JSON format. Note that there is no support for log rotation. If you have a monitoring and logging system in place, it is advisable to propagate the request logs to your log storage system in order to take advantage of Amalgam8 features like resilience testing.

The sidecar installation comes preconfigured with Filebeat that can be configured automatically to ship the access logs to a Logstash server, which in turn propagates the logs to elasticsearch. If you wish to use the filebeat system for log processing, make sure to have Elasticsearch and Logstash services available in your application deployment. The following two environment variables enable the filebeat process:

A8_LOG=true
A8_LOGSTASH_SERVER='logstash_server:port'

Note: The logstash environment variable needs to be enclosed in single quotes.

3. Using the sidecar

The sidecar is independent of your application process. The communication model between a microservice, its sidecar and the target microservice is shown below:

When you want to make API calls to other microservices from your application, you should call the sidecar at localhost:6379. The format of the API call is http://localhost:6379/<serviceName>/<endpoint>

where the serviceName is the service name that was used when launching the target microservice (the A8_SERVICE environment variable), and the endpoint is the API endpoint exposed by the target microservice.

For example, to invoke the getItem API in the catalog microservice, your microservice would simply invoke the API via the URL: http://localhost:6379/catalog/getItem?id=123.

Note that service versions are not part of the URL. The choice of the service version (e.g., catalog:v1, catalog:v2, etc.), will be done dynamically by the sidecar, based on routing rules set by the Amalgam8 controller.

Configuration options

Configuration options can be set via environment variables, command line flags, or YAML configuration files. Order of precedence is command line flags first, then environmenmt variables, configuration files, and lastly default values.

Note: Atleast one of A8_REGISTER or A8_PROXY must be true.

Configuration precedence

Example configuration file:

register: true
proxy: true

service:
  name: helloworld
  tags: 
    - v1
    - somethingelse
  
endpoint:
  host: 172.10.10.1
  port: 9080
  type: https

registry:
  url:   http://registry:8080
  token: abcdef
  poll:  10s
  
controller:
  url:   http://controller:8080
  token: abcdef
  poll:  30s
  
supervise: true
app: [ "python", "helloworld.py ]

log: true
logstash_server: logstash:8092

log_level: debug

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 Sidecar, run the following commands:

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

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

Building an Executable

The sidecar can also be run as a standalone binary for debugging purposes. The following commands will build and run it as a Go binary:

cd $GOPATH/src/github.com/amalgam8/amalgam8
make build.sidecar
./bin/a8sidecar [args]

Make targets

The following targets are available. Each may be run with make <target>.