Archiving

Corus allows "archiving" its current state, for certain types of objects. This functionality can be used in the context of rollbacks, for example, where we'd then "unarchive" the previous state (which is the case in the context of a rollback).

The objects that can be archived are the following:

  • Process properties;
  • tags;
  • execution configurations;
  • port ranges;
  • distributions.

Commands

Before delving into the details of archival, let us provide an overview of the available commands:

For process properties and tags (respectively):

  • conf archive -p -rev <rev_id>
  • conf archive -t -rev<rev_id>
  • conf unarchive -p -rev <rev_id>
  • conf unarchive -t -rev <rev_id>

For port ranges:

  • port archive -rev <rev_id>
  • port unarchive -rev <rev_id>

For execution configurations:

  • exec archive -e -rev <rev_id>
  • exec unarchive -e -rev <rev_id>

For performing multiple archivals at once

There are also two commands that bundle all operations above:

  • archive -rev <rev_id>
  • unarchive -rev <rev_id>

These do what the previous commands do, in one shot, for archiving and unarchiving respectively (archive will trigger the archiving of process properties, tags, port ranges, and execution configurations, while unarchive will do the same for unarchiving).

Distribution Archiving

In addition to the above-mentioned commands pertaining to the archival of configuration, it is also possible to archive distributions. This aims at supporting the following scenario:

  1. A new distribution version is deployed.
  2. The current version is undeployed, but in fact kept on the Corus side in case it should be revived due to a rollback.
  3. Rolling back would involve (among others): undeploying the latest distribution, and redeploying the previous one.

There is no special command for archiving distributions. Rather, archival is done through the undeploy command, and "unarchival" is performed with deploy.

The idea is that when undeploying, we'd want to keep a copy of the distribution on the side of Corus, to make sure we can quickly redeploy the exact same distribution package if need be. The undeploy command therefore supports the -rev option, for passing in the revision "under" which the distribution being undeployed should be archived, as illustrated by the example below:

undeploy -d * -v * -rev previous

We've chosen "previous" as a revision identifier, to illustrate that relatively to the new distribution version that will be deployed, the one being undeployed is in fact the previous version. Revision IDs however are completely arbitrary, and it is up to users to pick the ones they see fit.

Now in the context of a rollback, we would: undeploy the new distribution, redeploy the previous one. That is reflected by the commands below:

undeploy -d * -v *
deploy -rev previous

Note two things: first, the undeploy above is not provided with the -rev option: our intent is indeed to completely remove the new distribution, since at this point it is probably faulty.

Second, we are actually not deploying a distribution package: we're just indicating Corus that it should deploy the distribution it has archived - under the "previous" revision.

Revisions in Detail

When archiving, the current state of objects being archived is kept in a bucket called a "revision". As was mentioned previously, a revision is tagged with a user-supplied identifier. Here's an example:

conf -p archive -rev previous

In this case, we're archiving process properties under a revision called "previous" - there's no imposed conventions on revision identifiers, other than that they can only contain alpha-numeric characters, dashes (-), underscores (_) and periods. In our case, using "previous" makes it clearer, when unarchiving, that we're doing the operation to restore the "previous" state, as shown below:

conf unarchive -rev previous

Also, If an archival is performed using a given revision identifier, and re-archive later on using that same identifier, object state kept as part of the preceding revision is lost, and the new object state takes over.

For example, consider the following sequence:

  1. conf add -t tag1,tag2
  2. conf archive -rev previous
  3. conf del -t *
  4. conf add -t tag3,tag4
  5. conf archive -rev previous
  6. conf del -t *
  7. conf unarchive -rev previous
  8. conf ls -t

The last command (conf ls -t) will return tags tag3 and tag4: even though tag1 and tag2 had been previously archived (#2), they have been overwritten by the archiving of tag3 and tag4, (#5) under the same revision identifier.

A more comprehensive picture of how to use the archiving functionality is provided in the Packaging Scripts with Distributions section.