Name: deploy_doc
Owner: Microservices Demo
Description: Test the deployment documentation of your application from the markdown source
Created: 2016-11-24 14:22:10.0
Updated: 2016-12-01 10:08:56.0
Pushed: 2017-01-06 10:11:16.0
Homepage: null
Size: 120
Language: Ruby
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
With DeployDoc, you can test the deployment of your microservice constellation to multiple platforms, based on your end user documentation. Usually, a project will have documented the required steps to deploy the microservices. This documentation typically consists of a text with these steps embedded in it. We realized that by adding some annotations, these steps could be parsed by a computer and run in a CI pipeline. See the syntax section below for more information about how to write these Markdown files.
ruby image.deploy_doc tool parses, extracts and converts the Markdown file into a JSON file which
contains all the steps that need to be run. (See the syntax section below on
how to write these Markdown files).deploy_doc tool creates a docker container, and mounts (a) the JSON file containing the
steps that need to be run, (b) the runner script that interprets the JSON file and (c) the
data dir to /deploy_doc/data. The runner returns an appropriate status code to communicate
the result of the test run to the CI environment (see the usage section below).
Install the deploy_doc gem, see the installation instructions below.
E: deploy_doc <markdown_file> [options]
-h, --help Print help
-r, --run-test Run tests
-j, --dump-json Just parse the Markdown file and dump the steps to JSON
-c, --shell-in-container Start a (temporary) docker container with the same environment as the tests will run in
-i, --docker-image=IMG_NAME Use this docker image instead of the default 'ruby:2.3'
-d, --data-dir=DIR Set the data directory, instead of the default '.'
STATUS:
all test passed, and the infrastructure has been cleaned up, 0 is returned.
something went wrong, but there the infrastructure has been destroyed correctly,
1 error status is returned, but if the destruction of the infrastructure did not complete,
e process returns an error status 2. These cases will probably require manual cleanup steps.
nally, a error status 3 is returned if the program is aborted. We cannot give any guarantees in this case!
NOTE: If you use a custom docker image, be sure that it contains a Ruby implementation with version >= 2.1
The test runner has four phases:
pre-install, in which required additional software should be installed, such as Terraform.
If this phase fails, the tests just aborts, without attempting to destroy the infrastructure.
NOTE: This implies that it is very important to also install any the tool that is required
to tear down the infrastructure.create-infrastructure, in which the cloud resources are created. If this phase fails,
the tests are skipped, but the destroy-infrastructure phase is executed.run-tests, which should contain instructions that validate that the infrastructure is up and
running and that the microservices are deployed correctly.destroy-infrastructure, which must tear down the infrastructure.There is an additional require-env phase, that can be used to pass in environmental variables to
the steps. If they are not present, testing the documentation will result in an error message that
these variables are not present.
The expected syntax is compatible with Jekyll.
We expect the Markdown file to start with a YAML section, enclosed in a --- delimiter.
Multiple shell snippets (steps) can be added to a phase. The phases are run in the order give in the previous section, after which each snippet is executed in the order of declaration in the file.
The following syntaxes are supported to add snippets:
Single line annotation, not visible in Markdown output
<!-- deploy-doc PHASE [VALUE]* -->
Hidden multi-line annotation
<!-- deploy-doc-start PHASE [VALUE]*
CONTENT
-->
Visible multi-line annotation
<!-- deploy-doc-start PHASE [VALUE]* -->
CONTENT
<!-- deploy-doc-end -->
Note that due to current technical limitations of the test runner, each step is executed in a separate shell. This implies that setting an environmental variable in one step, will not be available in a next step. A work-around is to load/store this information in files. The externally required environmental variables to store secrets are available in all steps.
oyDoc: true
llo World
deploy-doc require-env ENV_A ENV_B -->
deploy-doc-start pre-install -->
apt-get update
apt-get install -yq jq terraform
deploy-doc-end -->
deploy-doc-hidden pre-install
rl https://nixos.org/nix/install | sh
x-env -i nixops
deploy-doc-start create-infrastructure -->
# This both creates the infrastructure, and
# deploys a distributed application to it.
nixops create -d test_deployment ./deployment.nix
nixops deploy -d test_deployment
deploy-doc-end -->
deploy-doc-start run-tests -->
# Get the public endpoint
WEBAPP_HOST=`nixops export -d test_deployment | jq ' .[].resources["load-balancer"].publicIpv4' -r`
# Test that the webapp is up.
curl $WEBAPP_HOST
deploy-doc-end -->
deploy-doc-start destroy-infrastructure -->
nixops destroy -d test_deployment
deploy-doc-end -->
Add this line to your application's Gemfile:
'deploy_doc'
And then execute:
$ bundle
Or install it yourself as:
$ gem install deploy_doc
After checking out the repo, run bundle install to install dependencies.
Then, run rake test to run the tests.
You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install.
To release a new version, update the version number in version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags,
and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/microservices-demo/deploy_doc. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.