No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
pelger Merge pull request #12 from apparatus/external_dns
Added support for external DNS entries
Latest commit 17ae81b Nov 13, 2017

README.md

Fuge-Config

Configuration file parser for fuge.

If you're using this module, and need help, you can:

Install

fuge-config provides configuration file parsing for fuge. To install fuge use npm:

$ npm install -g fuge

Format

The fuge config file format is yaml based and is structured as follows:

fuge_global:
  .
  .
  <global settings>
  .
  .
<service1 settings>:
  .
  .
<service2 settings>:
  .
  .
include:
  - <docker-compose-file>

Settings are provided at a global and per service level. Generally, any global settings may be overridden at the container / service level. Global settings are applied to all containers.

You may optionally include a list of docker-compose formatted files through the use of the include setting. Fuge supports V1, V2 and V3 docker-compose syntax.

Examples

A simple example is provided below:

fuge_global:
  run_containers: true
  monitor_excludes:
    - '**/node_modules/**'
    - '**/.git/**'
    - '*.log'
  environment:
    - NODE_ENV=DEV
frontend:
  type: process
  path: ./frontend
  run: 'npm start'
  ports:
    - http=3000
mongo:
  type: container
  image: mongodb
  ports:
    - tcp=27017:27017

In the simple example fuge will run a frontend process (called frontend) and a mongodb container. This might be the configuration for a monolithic MEAN stack application. The application can be started through the Fuge shell:

$ fuge shell <path to config file>
fuge> start all

A more complicated example follows:

fuge_global:
  run_containers: true
  host: 127.0.0.1
  monitor_excludes:
    - '**/node_modules/**'
    - '**/.git/**'
    - '*.log'
  dns_enabled: true
  dns_namespace: testns
  dns_suffix: svc.cluster.local
  dns_external:
    - "mydatabse.mydomain.internal.com IN A 192.0.2.1"
    - "_main._tcp.mydatabse.mydomain.internal.com IN SRV 0 5 5060 mydatabase.mydomain.internal.com"
  auto_generate_environment: true
  auto_port_start: 20000
  environment:
    - NODE_ENV=DEV
frontend:
  delay_start: 5
  type: process
  path: ./frontend
  run: 'npm start'
  ports:
    - http=3000
service_one:
  type: process
  path: ./service_one
  run: 'npm start'
service_two:
  type: process
  path: ./service_two
  run: 'npm start'
mongo:
  type: container
  image: mongodb
  ports:
    - tcp=27017:27017

In the above example fuge will generate environment variables and dns entries for frontend, service_one, service_two and mongodb. Again the entire system can be started using the fuge shell.

Emulating production environments

Fuge will emulate your production environment allowing you to run code with the same configuration in development as would run in production. In the example above fuge has been configured to emulate Kubernetes for local development. Fuge will generate Kubernetes style dns entries and and environment variables. The DNS entries generated are as follows:

type  domain                                            address                                port
A     frontend.testns.svc.cluster.local                 127.0.0.1                              -
A     service_one.testns.svc.cluster.local              127.0.0.1                              -
A     service_two.testns.svc.cluster.local              127.0.0.1                              -
A     mongo.testns.svc.cluster.local                    127.0.0.1                              -
SRV   _http._tcp.frontend.testns.svc.cluster.local      frontend.testns.svc.cluster.local      3000
SRV   _main._tcp.service_one.testns.svc.cluster.local   service_one.testns.svc.cluster.local   20000
SRV   _main._tcp.service_two.testns.svc.cluster.local   service_one.testns.svc.cluster.local   20001
SRV   _tcp._tcp.mongo.testns.svc.cluster.local          mongo.testns.svc.cluster.local         27017

Fuge will also generate Kubernetes style environment variables as follows from the above example:

FRONTEND_SERVICE_HOST=127.0.0.1
FRONTEND_SERVICE_PORT=3000
FRONTEND_PORT=tcp://127.0.0.1:3000
FRONTEND_PORT_3000_TCP=tcp://127.0.0.1:3000
FRONTEND_PORT_3000_TCP_PROTO=tcp
FRONTEND_PORT_3000_TCP_PORT=3000
FRONTEND_PORT_3000_TCP_ADDR=127.0.0.1
DNS_HOST=0.0.0.0
DNS_PORT=53053
DNS_NAMESPACE=testns
DNS_SUFFIX=svc.cluster.local
SERVICE_ONE_SERVICE_HOST=127.0.0.1
SERVICE_ONE_SERVICE_PORT=20000
SERVICE_ONE_PORT=tcp://127.0.0.1:20000
SERVICE_ONE_PORT_20000_TCP=tcp://127.0.0.1:20000
SERVICE_ONE_PORT_20000_TCP_PROTO=tcp
SERVICE_ONE_PORT_20000_TCP_PORT=20000
SERVICE_ONE_PORT_20000_TCP_ADDR=127.0.0.t
SERVICE_TWO_SERVICE_HOST=127.0.0.1
SERVICE_TWO_SERVICE_PORT=20001
SERVICE_TWO_PORT=tcp://127.0.0.1:20001
SERVICE_TWO_PORT_20001_TCP=tcp://127.0.0.1:20000
SERVICE_TWO_PORT_20001_TCP_PROTO=tcp
SERVICE_TWO_PORT_20001_TCP_PORT=20001
SERVICE_TWO_PORT_20001_TCP_ADDR=127.0.0.1
MONGO_SERVICE_HOST=127.0.0.1
MONGO_SERVICE_PORT=27017
MONGO_PORT=tcp://127.0.0.1:27017
MONGO_PORT_27017_TCP=tcp://127.0.0.1:27017
MONGO_PORT_27017_TCP_PROTO=tcp
MONGO_PORT_27017_TCP_PORT=27017
MONGO_PORT_27017_TCP_ADDR=127.0.0.1
NODE_ENV=DEV

Environment Handling

Fuge supports loading of environment files both at the global and service scope. It also supports environment variable interpolation in the fuge config file and and included docker compose files.

Detail

Global Settings

Valid global settings are as follows:

Global Settings

nametypeeffectdefault
run_containers boolean when enabled fuge will run docker containers using the local docker api. A container is specified as having type 'container' true
container_engine_url url The url to used to connect to the Docker container engine (e.g. /var/run/docker.sock). If not set this will be picked up from the environment. ''
host string Host name or IP address to use for this host when starting Docker containers 127.0.0.1
tail boolean toggles tail behavior, when enabled at global level all container and process logs will be tailed true
monitor boolean toggles monitor behavior, when enabled at global level all processes will be watched for changes and restarted true
monitor_excludes array of regex Array of [anymatch](https://github.com/es128/anymatch) compatible path expressions that should be excluded from monitoring typically this should be set to ['**/node_modules/**', '**/.git/**', '*.log' or similar []
dns_enabled boolean when enabled will start the internal fuge DNS sever and generate A and SRV records for each service. false
dns_host string host ip address for dns server to bind to. 0.0.0.0
dns_port integer port for dns server 53053
dns_namespace string Used as a global namespace during dns name generation ''
dns_suffix string Used as a global suffix during dns name generation ''
dns_external array of string inject addtional dns records into the fuge dns server. Can be used to connect to external databases during development ''
auto_generate_environment boolean When enabled fuge will generate an environment variable block for each service true
auto_port_start integer Provide a base port number to use during environment generation 10000
environment array of string Provide global environment variables to each service []
env_file array of string Specifiy a list of environment files to load into the global environment []
host string provide a global host name or ip address localhost
delay_start integer delay this many seconds when starting processes 0
restart_on_error boolean attempt to restart crashed service processes false
max_restarts integer maximum number of times to attempt service restart after crash 5
include Array of string List of docker compose files to include in this fuge system []

Service Settings

Most of the global settings documented above may be specified at the service level. When specified at the service level, settings override the global options. In addition at the service level the following settings are required/allowed:

nametypeeffectdefault
type string one of 'process' or 'container', tells fuge how to execute this service none - required
path string If type 'process' path is required. Relative path to the process executable none - required if process
image string If type 'container' image is requried. Name of the docker container to execute none - required if container
build string build script for the process, relative to the path setting ''
test string test script for the process, relative to the path setting ''
run string run script for the process, relative to the path setting none - required for processes
environment array of string Provide environment variables specific to this process or container. Will be merged with the global environment []
ports array of string Provide port name value pairs specific to this process / container []

What's not supported

Fuge does not support container volumes from docker files or container linking. If you need these features then docker-compose is going to work better for you. Note however it is possible to run a portion of your system under compose (the bits that don't change much) and a portion under fuge (the bits that are under development) by setting run_containers to false and importing your docker-compose file. For an example of this see services-and-infrastructure sample in this repo: https://github.com/apparatus/fuge-examples

License

Copyright Peter Elger 2016 & Contributors, Licensed under [MIT][].