Configuration

The following instructions apply to both Docker-based and Kubernetes-based installations. Configuration options can be set via environment variables, command line flags, or YAML configuration files. Order of precedence is command line flags first, then environment variables, configuration files, and lastly default values.

To run the sidecar with a configuration file, use the following command:

a8sidecar -config /path/to/a8sidecar.yaml

Options Reference

The following table lists all the configuration options, their equivalent environment variable name, the command line switch and the field in the YAML file.

Configuration Topics

• Kubernetes configuration
• Service registration
• Health checks
• Request routing
• Process supervision

Service registration

Registration and heartbeat with the Amalgam8 service registry can be enabled by setting the following environment variables or setting the equivalent fields in the config file:

A8_SERVICE=service_name:service_version_tag,some_other_tag
A8_ENDPOINT_PORT=port_where_service_is_listening
A8_ENDPOINT_TYPE=https
A8_REGISTER=true
A8_REGISTRY_URL=http://a8registryURL

Equivalent YAML config:

#a8sidecar.yaml
service:
  name: service_name
  tags: 
    - service_version_tag
    - some_other_tag
  
endpoint:
  port: port_where_service_is_listening
  type: https

register: true
registry:
  url:   http://registry:8080

The default endpoint type is http. So, the environment variable A8_ENDPOINT_TYPE and the YAML key type under endpoint section can be omitted, when registering an http endpoint.

Health checks

In addition to automatic service registration, the sidecar can periodically check the health of the application through TCP, HTTP or simply by running a specified command. When the application fails to respond or returns an error, the sidecar will immediately unregister the service instance from the Amalgam8 registry.

Health checks can configured using environment variable in the following manner:

A8_HEALTHCHECKS=http://localhost:8080/health1,tcp://localhost:9090

Alternatively, a more expressive and customizable health check can be configured in the YAML configuration file:

healthchecks:
  - type: http
    value: http://localhost:8080/health1
    interval: 15s
    timeout: 5s
    code: 200
  - type: tcp
    value: http://localhost:9090
    interval: 30s
    timeout: 3s
  - type: file
    value: /opt/check_my_app.sh
    interval: 10s
    timeout: 5s

where

• type indicates the type of health check. Sidecar versions upto 0.4.0 support HTTP health checks only. 0.4.1 and higher support TCP, and command based health checks as well.
• value indicates the health check URL, or TCP endpoint or the path to the script to be executed. In case of HTTP, the sidecar will access the specified URL via the GET method only.
• interval indicates the frequency of the health check. Time intervals can be suffixed with s, m to indicate seconds or minutes.
• timeout indicates how long the sidecar will wait for the health check to execute.
• code indicates the HTTP response code that the sidecar should expect from the application in HTTP/HTTPS health checks and the exit code to expect from the command run in command health checks.

Note: When using HTTPS endpoints, self-signed certificates will cause the health checks to fail as the connection attempt will fail in the first place.

Request routing

For microservices that make outbound calls to other microservices, service discovery and client-side load balancing, version and content-based routing can be enabled by the following options:

A8_SERVICE=service_name:service_version_tag
A8_PROXY=true
A8_REGISTRY_URL=http://a8registryURL
A8_REGISTRY_POLL=5s
A8_CONTROLLER_URL=http://a8controllerURL
A8_CONTROLLER_POLL=5s

Equivalent YAML config:

service:
  name: service_name
  tags: 
    - service_version_tag
    - some_other_tag

proxy: true

registry:
  url:   http://registry:8080
  poll:  5s
  
controller:
  url:   http://controller:8080
  poll:  5s

If you want to enable both request routing and registration, add the following to the above config:

A8_REGISTER=true

or in YAML:

register: true

Process supervision

When packaging the sidecar along with the application in the same docker container, the sidecar can be made to act as the supervisor process that launches the application process and other agents in the container. Upon graceful termination (or a crash) of the application process, the sidecar will also terminate, effectively causing the container to terminate as well.

For sidecar versions 0.4.1 and above: Sidecar can start and supervise any number of application processes. If one of the applications dies, supervisor can be configured to terminate the sidecar process as well.

All arguments provided after the flags will be considered a part of a single application invocation. By default, the sidecar process will exit if this application terminates. The following ENTRYPOINT can be placed in a Dockerfile to start the sidecar process as well as one python application:

ENTRYPOINT ["a8sidecar", "python", "productpage.py", "9080", "http://localhost:6379" ]

More advanced supervision modes can be configured by providing a yaml config. For instance, if you wanted to run the filebeat log shipping agent and a python application, the following yaml could be provided:

commands:
  - cmd: [ "filebeat", "-c", "/etc/filebeat.yml" ]
    env: [ "GODEBUG=netdns=go" ]
    on_exit: ignore
  - cmd: [ "python", "productpage.py", "9080", "http://localhost:6379" ]
    on_exit: terminate

where

• cmd indicates the commands you want to run.
• env indicates any additional environment variables the application may need to run with.
• on_exit can have the values ignore or terminate which indicates what the sidecar process should do if this application terminates.

ignore vs terminate: When the on_exit field for a particular process is set to ignore, the sidecar will not restart the process when it exits (even if the process exits with an error). When the on_exit field is set to terminate, all processes managed by the sidecar will be terminated and the sidecar will shutdown/exit. If the sidecar is the primary process in a Docker container, i.e.

ENTRYPOINT ["a8sidecar", "--config", "sidecar.yaml" ]

then failure of one of the managed processes whose on_exit is set to terminate will cause the container itself to terminate (after shutting down other processes in the container).

It is advisable to use the on_exit: ignore for non-essential helper processes in the container, while the on_exit: terminate should be used for the main applicaton processes.

For sidecar versions 0.4.0 and below: Prior to 0.4.1, only a single process can be supervised by the sidecar. To supervise a single process, specify the –supervise flag in the command line. For example,

ENTRYPOINT ["a8sidecar", "python", "productpage.py", "9080", "http://localhost:6379" ]

and the equivalent YAML configuration:

##Setting up app supervision
supervise: true
app: [ "python", "productpage.py", "9080", "http://localhost:6379" ]

Dealing with daemons and child processes: When the parent process managed by the sidecar exits, the sidecar will automatically kill all the child processes that the parent process had spawned. If an application launches background processes and then exits gracefully, it will cause the sidecar to terminate all child processes and exit as well.

For example, run nginx in foreground with daemon off; instead of the default background mode.

commands:
    # Disable daemons and let nginx run in the foreground.
  - cmd: [ "nginx", "-g", "daemon off;" ]
    on_exit: terminate

As another example, in the following configuration, the sidecar will kill all processes eventhough this may not be what is intended.

commands:
  - cmd: [ "/opt/launchapps.sh" ]
    on_exit: terminate

where launchapps.sh is a simple script that launches the application and all the processes as background processes and exits immediately.

#!/bin/bash
nginx ## daemonizes, and nginx launches worker processes
python myappserver.py &

Instead, the prescribed method for launching these processes should be via the sidecar config file

commands:
  - cmd: [ "nginx", "-g", "daemon off;" ]
    on_exit: terminate
  - cmd: [ "python", "myappserver.py" ]
  - on_exit: terminate

A complete configuration file

The following is an example config file for a sidecar that supervises a python application called productpage.py, starts up the filebeat log shipping agent, registers the application with the service registry, monitors its health and proxies outbound requests to other services. If the application terminates, the sidecar kills other processes and exits, thereby causing the container to terminate.

#registration
register: true
registry:
  url:   http://registry:8080
  poll:  5s

endpoint:
  port: 9080

#request proxying
proxy: true
controller:
  url:   http://controller:8080
  poll:  30s

#Process management
commands:
    #start the app process. If app terminates, terminate container
  - cmd: [ "python", "productpage.py", "9080", "http://localhost:6379" ]
    on_exit: terminate
  - cmd: [ "filebeat", "-c", "/etc/filebeat.yml" ]
    env: [ "GODEBUG=netdns=go" ]
    on_exit: ignore

healthchecks:
  - type: http
    value: http://localhost:8080/health1
    interval: 15s
    timeout: 5s
    code: 200
  - type: http
    value: http://localhost:9090/health2
    interval: 30s
    timeout: 3s
    code: 201