deployadactyl

README

Deployadactyl is a Go library for deploying applications to multiple Cloud Foundry instances. Deployadactyl utilizes blue green deployments and if it's unable to push an application it will rollback to the previous version. It also utilizes Go channels for concurrent deployments across the multiple Cloud Foundry instances.

Check out our stories on Pivotal Tracker!

• How It Works
• Why Use Deployadactyl?
• Usage Requirements
  • Dependencies
  • Configuration File
    • Example Configuration yml
    • Environment Variables
• How to Download Dependencies
• How To Run Deployadactyl
• How to Push Deployadactyl to Cloud Foundry
  • Available Flags
  • API
    • Example Curl
• Event Handling
  • Available Emitted Event Types
  • Event Handler Example
  • Event Handling Example
• Contributing

How It Works

Deployadactyl works by utilizing the Cloud Foundry CLI to push an application. The general flow is to get a list of Cloud Foundry instances, check that the instances are available, download an artifact, log into each instance, and concurrently call cf push in the deploying applications directory. If an application fails to deploy on any instance, Deployadactyl will automatically roll the application back to the previous version.

Why Use Deployadactyl?

As an application grows, it will have multiple foundations for each environment. These scaling foundations make deploying an application time consuming and difficult to manage. If any errors occur during a deployment it can greatly increase downtime.

Deployadactyl makes the process easy and efficient with:

• Management of multiple environment configurations
• Concurrent deployments across environment foundations
• Automatic rollbacks for failures or errors
• Prechecking foundation availablity before deployments
• Event handlers for third-party services

Usage Requirements

Dependencies

Deployadactyl has the following dependencies within the environment:

• CloudFoundry CLI
• Go 1.6 or later

Configuration File

Deployadactyl needs a yml configuration file to specify environments to deploy to. Each environment has a name, domain and a list of foundations.

The configuration file can be placed anywhere within the Deployadactyl directory, or outside, as long as the location is specified when running the server.

Param	Necessity	Type	Description
name	Required	string	Used in the deploy when the users are sending a request to Deployadactyl to specify which environment from the config they want to use.
foundations	Required	[]string	A list of Cloud Foundry instance URLs.
domain	Optional	string	Used to specify a load balanced URL that has previously been created on the Cloud Foundry instances.
authenticate	Optional	bool	Used to specify if basic authentication is required for users. See the authentication section in the API documentation for more details
skip_ssl	Optional	bool	Used to skip SSL verification when Deployadactyl logs into Cloud Foundry.
instances	Optional	int	Used to set the number of instances an application is deployed with. If the number of instances is specified in a Cloud Foundry manifest, that will be used instead.

Example Configuration yml

---
environments:
  - name: preproduction
    domain: preproduction.example.com
    foundations:
    - https://preproduction.foundation-1.example.com
    - https://preproduction.foundation-2.example.com
    authenticate: false
    skip_ssl: true
    instances: 2

  - name: production
    domain: production.example.com
    foundations:
    - https://production.foundation-1.example.com
    - https://production.foundation-2.example.com
    - https://production.foundation-3.example.com
    - https://production.foundation-4.example.com
    authenticate: true
    skip_ssl: false
    instances: 4

Environment Variables

Authentication is optional as long as CF_USERNAME and CF_PASSWORD environment variables are exported. We recommend making a generic user account that is able to push to each Cloud Foundry instance.

$ export CF_USERNAME=some-username
$ export CF_PASSWORD=some-password

Optional: The log level can be changed by defining DEPLOYADACTYL_LOGLEVEL. DEBUG is the default log level.

How to Download Dependencies

We use Godeps to vendor our dependencies. To grab the dependencies and save them to the vendor folder, run the following commands:

$ go get -u github.com/tools/godep
$ rm -rf Godeps                      # this will clean the repo of it's dependencies
$ godep save ./...

or

$ make dependencies

How To Run Deployadactyl

After a configuration file has been created and environment variables have been set, the server can be run using the following commands:

$ cd ~/go/src/github.com/compozed/deployadactyl && go run server.go

or

$ cd ~/go/src/github.com/compozed/deployadactyl && go build && ./deployadactyl

How to Push Deployadactyl to Cloud Foundry

To push Deployadactyl to Cloud Foundry, edit the manifest.yml to include the CF_USERNAME and CF_PASSWORD environment variables. In addition, be sure to create a config.yml. Then you can push to Cloud Foundry like normal:

$ cf login
$ cf push

or

$ make push

Available Flags

Flag	Usage
-config	location of the config file (default "./config.yml")
-envvar	turns on the environment variable handler that will bind environment variables to your application at deploy time
-health-check	turns on the health check handler that confirms an application is up and running before finishing a push

API

A deployment by hitting the API using curl or other means. For more information on using the Deployadactyl API visit the API documentation in the wiki.

Example Curl

curl -X POST \
     -u your_username:your_password \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{ "artifact_url": "https://example.com/lib/release/my_artifact.jar", "health_check_endpoint": "/health" }' \
     https://preproduction.example.com/v1/apps/environment/org/space/t-rex

Event Handling

With Deployadactyl you can optionally register event handlers to perform any additional actions your deployment flow may require. For example, you may want to do an additional health check before the new application overwrites the old application.

Available Events

|Event Type|Returned Struct|Emitted| |---|---|---|---|---| |deploy.start|DeployEventData|Before deployment starts |deploy.success|DeployEventData|When a deployment succeeds |deploy.failure|DeployEventData|When a deployment fails |deploy.error|DeployEventData|When a deployment throws an error |deploy.finish|DeployEventData|When a deployment finishes, regardless of success or failure |push.finished|PushEventData| Happens before a push finishes. If it receives an error, it will stop the deployment and trigger an undo push |validate.foundationsUnavailable|PrecheckerEventData|When a foundation you're deploying to is not running

Event Handler Example

See the Health Checker for an example of how to write an event handler.

Contributing

See our CONTRUBUTING section for more information.