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.

An overview of the Amalgam8 project is available here: https://amalgam8.io/

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://git.io/a8sidecar.sh | sh

• Launch your app via the sidecar

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

• 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/sidecar/releases/download/${VERSION}/install-a8sidecar.sh | sh

or

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

where ${VERSION} is the version of the sidecar that you wish to install.

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
A8_REGISTRY_POLL=polling_interval_between_sidecar_and_registry(5s)
A8_SERVICE=service_name:service_version_tag
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
A8_REGISTRY_POLL=polling_interval_between_sidecar_and_registry(5s)
A8_SERVICE=service_name:service_version_tag
A8_SERVICE=service_name:service_version_tag
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
A8_CONTROLLER_POLL=polling_interval_between_sidecar_and_controller(5s)

**Update propagation: polling : By default, the sidecar will periodically poll the Amalgam8 Controller for rule updates on routing requests and fault injection. The sidecar will separately poll Amalgam8 Registry for updates on registered 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 through environment variables or command line flags.

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

Environment Key	Flag Name	Description	Default Value	Required
A8_LOG_LEVEL	--log_level	Logging level (debug, info, warn, error, fatal, panic)	info	no
A8_SERVICE	--service	service name to register with		yes
A8_SERVICE_VERSION	--service_version	service version to register with. Service is UNVERSIONED by default		needed if you wish to register different versions under same name
A8_ENDPOINT_HOST	--endpoint_host	service endpoint hostname. Defaults to the IP (e.g., container) where the sidecar is running	optional
A8_ENDPOINT_PORT	--endpoint_port	service endpoint port		yes
A8_ENDPOINT_TYPE	--endpoint_type	service endpoint type (http, https, udp, tcp, user)	http	no
A8_REGISTER	--register	enable automatic service registration and heartbeat	true	See note above
A8_PROXY	--proxy	enable automatic service discovery and load balancing across services using NGINX		See note above
A8_LOG	--log	enable logging of outgoing requests through proxy using FileBeat	true
A8_SUPERVISE	--supervise	Manage application process. If application dies, container is killed as well. This has to be the last flag. All arguments provided after this flag will considered as part of the application invocation	true	no
A8_CONTROLLER_TOKEN	--controller_token	Auth token for Controller instance		yes when -proxy is enabled
A8_TENANT_TTL	--tenant_ttl	TTL for Registry	60s	no
A8_TENANT_HEARTBEAT	--tenant_heartbeat	tenant heartbeat interval to Registry	45s	no
A8_REGISTRY_URL	--registry_url	registry URL		yes if -register is enabled
A8_REGISTRY_TOKEN	--registry_token	registry auth token		yes if -register is enabled
A8_REGISTRY_POLL	--registry_poll	interval for polling Registry	15s	no
A8_NGINX_PORT	--nginx_port	port for NGINX proxy. This port should be exposed in the Docker container.	6379	no
A8_CONTROLLER_URL	--controller_url	controller URL		yes if -proxy is enabled
A8_CONTROLLER_POLL	--controller_poll	interval for polling Controller	15s	no
A8_LOGSTASH_SERVER	--logstash_server	logstash target for nginx logs		yes if -log is enabled
	--help, -h	show help
	--version, -v	print the version

---

Building from source

The following sections describe options for building the sidecar from source.

Preprequisites

• Docker 1.8 or 1.9
• Go 1.6

Clone

Clone the repository manually, or use go get:

go get github.com/amalgam8/sidecar

Make targets

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

Make Target	Description
release	(Default) release builds the sidecar within a docker container and packages it into an image
test	test runs all tests using go test
clean	clean removes build artifacts. Note: this does not remove docker images

Release Workflow

This section includes instructions for working with releases, and is intended for the project's maintainers (requires write permissions)

Creating a release

1. Set a version for the release, by incrementing the current version according to the semantic versioning guidelines:

   export VERSION=v0.1.0

2. Update the APP_VER variable in the Makefile such that it matches with the VERSION variable above.

3. Create an annotated tag in your local copy of the repository:

   git tag -a -m "Release $VERSION" $VERSION [commit id]

   The [commit id] argument is optional. If not specified, HEAD is used.

4. Push the tag back to the Amalgam8 upstream repository on GitHub:

   git push upstream $VERSION

This command automatically creates a release object on GitHub, corresponding to the pushed tag. The release contains downloadable packages of the source code (both as .zip and .tag.gz archives).

1. Edit the CHANGELOG.md file, describing the changes included in this release.

2. Edit the GitHub release object, and add a title and description (according to CHANGELOG.md).

License

Copyright 2016 IBM Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contributing

Contributions and feedback are welcome! Proposals and pull requests will be considered. Please see the CONTRIBUTING.md file for more information.