Deployer Quickstart Guide

For a deployer, interaction with Scap is straight-forward.

The two most-typical commands are scap deploy and scap deploy-log.

Below we demo deployment using a fake service called Mockbase located at deployXXXX:/srv/deployment/mockbase/deploy.

scap deploy

The first step to deploying new code from your deployment_host (in most cases this will be one of the servers behind deployment.eqiad.wmnet) is to use git pull, git checkout, git cherry-pick, and git commit to bring the repository on the deployment_host into the state that you want deployed to your targets.

deployer@deployXXXX:/srv/deployment/mockbase/deploy$ echo "Add a README" > README
deployer@deployXXXX:/srv/deployment/mockbase/deploy$ git add README
deployer@deployXXXX:/srv/deployment/mockbase/deploy$ git commit -m 'Added a README'
[master 70eb01e] Added a README
 1 file changed, 1 insertion(+)
  create mode 100644 README

Once the repository state is correct, use the deploy command to release the finished code:

deployer@deployXXXX:/srv/deployment/mockbase/deploy$ scap deploy
20:46:12 Started deploy_mockbase/deploy
Entering 'mockbase'
20:46:12
== DEFAULT ==
:* scap-target-07
:* scap-target-08
:* scap-target-09
:* scap-target-04
:* scap-target-05
:* scap-target-06
:* scap-target-10
:* scap-target-01
:* scap-target-02
:* scap-target-03
deploy_mockbase/deploy_config_deploy: 100% (ok: 10; fail: 0; left: 0)
deploy_mockbase/deploy_fetch: 100% (ok: 10; fail: 0; left: 0)
deploy_mockbase/deploy_promote: 100% (ok: 10; fail: 0; left: 0)
deploy_mockbase/deploy_finalize: 100% (ok: 10; fail: 0; left: 0)
20:46:42 Finished deploy_mockbase/deploy (duration: 00m 29s)

The default output has several sections:

1. Deploy group target list

   Scap will list the targets of the deploy. Scap lists both the deploy target names and the deploy group. In the example output below, the deploy group is “DEFAULT” and the targets are listed beneath. (see Configuring a Git Repo for more info on targets). If you have more than one deploy group, you will see more than one of these sections.

   == DEFAULT ==
   :* scap-target-07
   :* scap-target-08
   :* scap-target-09
   :* scap-target-04
   :* scap-target-05
   :* scap-target-06
   :* scap-target-10
   :* scap-target-01
   :* scap-target-02
   :* scap-target-03
   

2. Deployment stages reporters

   There are four stages to a deployment:

   1. config_deploy Where your configration files are deployed.

   2. fetch Where the code from your repository is fetched to targets.

   3. promote Where your currently running code is swapped for newly fetched code.

   4. finalize Where deploy state is recorded and old deployments are cleaned up.

   Each of these stages is run sequentially and you can see the progress of these stages via the reporters:

   deploy_mockbase/deploy_config_deploy: 100% (ok: 10; fail: 0; left: 0)
   deploy_mockbase/deploy_fetch: 100% (ok: 10; fail: 0; left: 0)
   deploy_mockbase/deploy_promote: 100% (ok: 10; fail: 0; left: 0)
   deploy_mockbase/deploy_finalize: 100% (ok: 10; fail: 0; left: 0)
   

The scap deploy command also accepts the --verbose argument which may be useful in troubleshooting. The full options of the scap deploy command can be found in the deploy documentation.

scap deploy-log

The scap deploy-log command is designed to be used in tandem with the scap deploy command. It can be run either during a scap deploy, or it may be used to inspect the log afterward.

Below is a gif that demonstrates a simple use of scap deploy-log; running along-side a scap deploy that targets only a single host (using the -l|--limit flag).

At first, in the right pane, the tail of the logfile from the previous deployment is opened; however, after starting the scap deploy in the left pane, a new logfile is tailed.

scap deploy-log supports advanced filtering both during and post deployment. A deployer can match a particular host, log message, or error level using one of several comparison operators (see ``scap deploy-log`` examples)

Deployment information

A log of deployments is kept in several places. A full log of every deployment is available via Logstash. Also, a json record of the last deployment is kept inside your repo’s git directory on the deploy_host at .git/DEPLOY_HEAD.

The .git/DEPLOY_HEAD file shows the date, user, and commit of the last deployment from this repository. The deployed commit is also tagged locally with this information via an annotated git tag.

deployer@deployXXXX:/srv/deployment/mockbase/deploy$ jq '.' < .git/DEPLOY_HEAD
{
  "timestamp": "2015-11-17T22:05:53.277869",
  "user": "deployer",
  "tag": "scap/sync/2015-11-17/0014",
  "commit": "70eb01ed946c6bdc7d94b5b71abe81b9ea2e8d0c"
}