Deployment tool with consul/serf event notification.
Go Makefile
Latest commit 476b525 Jan 5, 2017 @fujiwara update LICENSE

README.md

Stretcher

A deployment tool with Consul / Serf event.

Example manifest

src: s3://example.com/app.tar.gz
checksum: e0840daaa97cd2cf2175f9e5d133ffb3324a2b93
dest: /home/stretcher/app
commands:
  pre:
    - echo 'staring deploy'
  post:
    - echo 'deploy done'
  success:
    - echo 'deploy success'
  failure:
    - echo 'deploy failed!!'
    - cat >> /path/to/failure.log
excludes:
  - "*.pid"
  - "*.socket"

Run

stretcher agent

$ stretcher -h
Usage of stretcher:
  -max-bandwidth string
        max bandwidth for download src archives (Bytes/sec)
  -random-delay float
        sleep [0,random-delay) sec on start
  -retry int
        retry count for download src archives
  -retry-wait int
        wait for retry download src archives (sec) (default 3)
  -timeout int
        timeout for download src archives (sec)
  -v    show version
  -version
        show version

with Consul

A stretcher agent is designed as running under "consul watch" and will be kicked by Consul event.

$ consul watch -type event -name deploy /path/to/stretcher
  • -name: your deployment identity name.

with Serf

A stretcher agent can be running as Serf event handler.

$ serf agent -event-handler="user:deploy=/path/to/stretcher >> /path/to/stretcher.log 2>&1"

Load AWS credentials

When you specify a S3 URL in manifest, requires a AWS credential setting one of below.

  • ~/.aws/config and ~/.aws/credentials (overridden by AWS_CONFIG_FILE environment variable.)
    • AWS_DEFAULT_PROFILE is supported to select a profile from multiple credentials in file.
  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION environment variable.
  • EC2 IAM role.
    • requires AWS_DEFAULT_REGION environment variable.

Deployment process

Preparing

This process is not included in a stretcher agent.

  1. Create a tar(or tar.gz) archive for deployment.
  2. Upload the archive file to remote server (S3 or HTTP(S)).
  3. Create a manifest file (YAML) and upload it to remote server.

Executing with Consul

Create a consul event to kick stretcher agents.

$ consul event -name [event_name] [manifest_url]
$ consul event -name deploy s3://example.com/deploy-20141117-112233.yml
  • -name: consul event name (specified by consul watch -name)

Executing with Serf

Create a serf user event to kick stretcher agents.

$ serf event [event_name] [manifest_url]
$ serf event deploy s3://example.com/deploy-20141117-112233.yml
  • event_name: user event name (specified by serf event handler).

Executing as command

Stretcher can read a manifest URL from stdin simply.

$ echo s3://example.com/deploy-20141117-112233.yml | stretcher

You can execute stretcher via ssh or any other methods.

Deployment process

A stretcher agent executes a following process.

  1. Receive a manifest URL as Consul/Serf event's payload.
  2. Get a manifest.
  3. Get src URL and store it to a temporary file, and Check checksum.
  4. Invoke pre commands.
  5. Extract src archive to a temporary directory.
  6. Sync files from extracted archive to dest directory.
    • use rsync -a --delete or mv
    • sync strategy is switched by sync_strategy
  7. Invoke post commands. 8.
    • Invoke success commands when the deployment process succeeded.
    • Invoke failure commands when the deployment process failed.

Manifest spec

src

Source archive URL.

  • URL schema: 's3', 'http', 'file'
  • Format: 'tar', 'tar.gz'
src: http://example.com/src/archive.tar.gz

checksum

Checksum of source archive.

  • Type: 'md5', 'sha1', 'sha256', 'sha512'
checksum: e0840daaa97cd2cf2175f9e5d133ffb3324a2b93

dest

Destination directory.

dest: /home/stretcher/app

dest_mode

Destination directory mode. Default: 0755

dest_mode: 0711

Destination directory mode will be set as...

  1. src archive includes . => same as . in the archive.
  2. src archive does not include . => dest_mode

commands

  • pre: Commands which will be invoked at before src archive extracted.
  • post: Commands which will be invoked at after dest directory synced.
  • success: Commands which will be invoked at deployment process is succeeded.
  • failure: Commands which will be invoked at deployment process is failed.
commands:
  pre:
    - echo 'staring deploy'
  post:
    - echo 'deploy done'
  success:
    - echo 'deploy success'
  failure:
    - echo 'deploy failed!!'
    - cat >> /path/to/failure.log

stretcher agent logs will be passed to STDIN of success and failure commands.

excludes

Pass to rsync --exclude arguments.

excludes:
  - "*.pid"
  - "*.socket"

exclude_from

Pass to rsync --exclude-from arguments. The file must be included in src archive.

exclude_from: exclude.list

sync_strategy

A strategy for syncing src extracted directory to dest directory.

  • rsync: Default
    • Use rsync(1) command with option -av --delete
  • mv
    • Use os.Rename() of Golang.
    • Deployment will be failed if dest directory is already exists.

Requirements

  • tar
  • rsync

tar and rsync must be exist in PATH environment.

If you use stretcher under systemd, You can see unfinished stdout with journald. You should add RateLimitBurst=0 into /etc/systemd/journald.conf for getting stdout completely.

Commands execution only mode

If src is not defined in a manifest, Stretcher runs pre/post and success/failure commands simply.

LICENSE

The MIT License (MIT)

Copyright (c) 2014 FUJIWARA Shunichiro / (c) 2014 KAYAC Inc.