Adding Custom Stager to Staging Pipeline
This tutorial shows how to append a custom stager to the built-in Ruby staging pipeline. The custom stager is an RSpec test runner that runs a number of RSpec tests once the code been compiled by the built-in stager. If any of the tests fail, the custom stager reports an error to the staging coordinator causing it to fail the staging process.
- Setup
- About the Custom Stager
- Deploy the Custom Stager
- Append the Custom Stager
- Deploy an Application using the custom Ruby pipeline
Setup
To complete this tutorial you must first clone the sample-apps repository to your local machine. You will be using the demo-ruby-sinatra sample application included in that repository.
About the Custom Stager
The demo-ruby-sinatra sample application includes a custom stager that executes RSpec tests. It implements the Stager API, an HTTP-based API for communicating with the staging coordinator. It performs the following basic steps:
- Downloads the application package (source code) from the staging coordinator.
- Install dependencies (using Bundler) required to run the specs.
- Executes the rspec tests.
- Issues an HTTP POST to
$STAGER_URL/done
if the tests completed successfully, or to$STAGER_URL/failed
if there were failures. The$STAGER_URL
environment variable is made available to the running stager instance.
Deploy the Custom Stager
Stagers are jobs that run within Apcera like any other job. The first step is to deploy the custom stager using APC.
To deploy the custom Ruby stager:
-
Open a terminal and navigate to the
sample-apps/demo-ruby-sinatra
directory.Note: You can safely ignore any message about "ruby-1.9.3-p392 is not installed".
-
Run the following command to create a new stager:
apc stager create my-rspec-stager --path rspec-stager --start-command ./rspec-stager --additive --allow-egress
This creates a custom stager named "my-rspec-stager" using the bash script located in the
rspec-stager
directory, and specifies the command to start the stager. The--allow-egress
permits the stager external network access so that it can install required Ruby dependencies. To verify that the custom stager was created, run the following command:apc package list
The summary table list the new stager.
Name Runtime Namespace my-rspec-stager my-rspec-stager /sandbox/tim
The next step is to append the my-rspec-stager
stager to a clone of the pre-built ruby
staging pipeline.
Append the Custom Stager
Next you'll create a clone of the built-in Ruby staging pipeline in your own namespace and append the custom stager to it. A staging pipeline is an ordered set of one or more stagers. You can change the order in which stagers run within a staging pipeline by adding one or more stagers to the beginning (prepend) or end (append) of the pipeline.
To append the custom stager to a clone of the Ruby pipeline:
-
Clone the built-in Ruby staging pipeline to your current namespace:
apc staging pipeline clone /apcera::ruby
This command clones the system-provided Ruby staging pipeline to your
/sandbox/<user-name>/
namespace. You can verify the cloned staging pipeline exists with the following command:apc staging pipeline list
Working in "/sandbox/tim"
Name Namespace Stagers ruby /sandbox/tim job::/apcera/stagers::ruby -
Append the custom stager to your cloned Ruby pipeline:
apc staging pipeline append ruby my-rspec-stager
You should see that the ruby staging pipeline is successfully updated. To view the properties of the cloned pipeline run the following command:
apc staging pipeline show ruby
The Stagers field displayed in the summary table should list two stagers: the cloned
ruby
stager and the custommy-rspec-stager
.Staging Pipeline: ruby FQN: stagpipe::/sandbox/tim::ruby Created by: tim Created at: 2015-07-07 23:46:48.468797811 +0000 UTC Updated by: tim Updated at: 2015-07-07 23:48:05.093408341 +0000 UTC Stagers: job::/apcera/stagers::ruby job::/sandbox/tim::my-rspec-stager
Deploy an Application using the custom Ruby pipeline
Now you're ready to deploy the demo Ruby application using the customized ruby
pipeline. First you'll stage the app successfully (with passing tests). Then you'll modify the test spec so it will fail and attempt to re-deploy the application, which fails due to the test failures.
To successfully deploy the application using the custom Ruby pipeline:
-
Still in the demo-ruby-sinatra/ directory, run the following command from a terminal prompt:
apc app create my-ruby-app --start --staging ruby
Note that the pipeline is referenced simply by name (without any namespace) since it exists in your current namespace (user/sandbox).
It's useful to look at the output of this command to learn how staging pipelines are processed. First, the staging coordinator loads the ruby
pipeline specified on the command line and notices it consists of two stagers (namely, the ruby
and my-rspec-stager
stagers).
[staging] Beginning staging with 'stagpipe::/sandbox/tim::ruby' pipeline, 2 stager(s) defined.
First, it launches the ruby
stager, which compiles the Ruby source provided to APC:
[staging] Launching instance of stager 'ruby'...
[staging] Downloading package for processing...
Once the ruby
stager has completed successfully, the appended my-rspec-stager
stager is launched. The package contents are downloaded and extracted to the /app
folder, dependencies are installed, and finally the tests are run. In this case, all the tests passed and the application is successfully staged as a runnable package.
[staging] Launching instance of stager 'my-rspec-stager'...
[staging] Downloading to /app
[staging] -----> Running bundle install for test dependencies
[staging] Installing diff-lcs 1.2.4
[staging] ...
[staging] -----> Running tests
[staging] ...
[staging] 3 examples, 0 failures
[staging] -----> Rspec tests passed.
[staging] Staging is complete.
Because the --start
option was included with the apc app create
invocation, the application is immediately provisioned and started.
Creating app "my-ruby-app"... done
Start Command: bundle exec rackup config.ru -p
Waiting for the application to start...
...
App should be accessible at "http://my-ruby-app.tim.sandbox.continuum-demo.io"
Next you'll "break" the rspec test so it fails, causing the staging process to abort.
To re-deploy the application with a broken rspec test:
-
Open demo-ruby-sinatra/spec/app_spec.rb and change the expectation at line 14 from
last_response.body.should == "Alive"
tolast_response.body.should == "Dead"
. -
Re-deploy the application:
apc app deploy my-ruby-app --staging ruby
The command output includes the failure messages from the test runner and, lastly, "Error: Staging has failed." Fix the error you injected into the test case and deploy the app again, which should complete successfully.