-
Notifications
You must be signed in to change notification settings - Fork 14
Tutorial Part 1
Previous: Tutorial Overview
Airship is a powerful piece of infrastructure and therefore requires some setup. This tutorial describes the "happy path"; the recommended way to set up and use airship. Familiarization with this setup is strongly suggested before starting to modify it.
Airship and its components require Java 7 to run. It must be installed on all machines and cloud images that should run any piece of airship.
Services installed into an airship environment consist of two pieces: The binary ("tarball") and configuration ("config"). Airship needs a central storage place for these pieces and use a Maven repository server for this.
If you want to use airship in a production environment, you must have a repository server. For the purpose of this tutorial, a local Maven repository is sufficient (it will be stored in ~/.m2/repository), however this will limit the scope of the tutorial to a single machine.
No repository server is required for this tutorial. This chapter is only for information and when setting up airship for production use. For evaluating airship and doing the tutorial, this chapter can be safely skipped!
Airship was extensively tested and productionized using Sonatype Nexus as a repository server and this is the recommended software to use.
The Nexus OSS edition is sufficient and can be downloaded from Sonatype. Follow the instructions from the download page to setup Nexus.
Airship must be able to publish artifacts to snapshot and release upload repositories on the server. It must be possible for airship to retrieve artifacts from snapshot and release download repositories. These are usually different URLs.
To use the released version of airship (which is available from Maven Central), the repository must also proxy requests from Maven Central. Nexus does this by default.
After setting up Nexus, the following information can be found on the Nexus GUI
-
Release download repository URL, e.g.
http://nexus.example.com/content/groups/public/(Called Public Repositories) -
Snapshot download repository URL, e.g.
http://nexus.example.com/content/groups/public-snapshots/(Called (Public Snapshot Repositories) -
Release upload repository URL, e.g.
http://nexus.example.com/content/repositories/releases/(Called Releases) -
Snapshot upload repository URL, (if different from the release repository URL), e.g.
http://nexus.example.com/content/repositories/snapshots/(Called Snapshots)
The remainder of the tutorial will focus on how to install airship using a local repository.
Airship provides two command line tools:
-
airshipitself is the command line interface (CLI) -
asconfigmanages configuration bundles
Both binaries can be downloaded from Maven Central:
AIRSHIP_VERSION=0.13
curl -o airship http://search.maven.org/remotecontent?filepath=io/airlift/airship/airship-cli/${AIRSHIP_VERSION}/airship-cli-${AIRSHIP_VERSION}-executable.jar
curl -o asconfig http://search.maven.org/remotecontent?filepath=io/airlift/airship/airship-config-bundler/${AIRSHIP_VERSION}/airship-config-bundler-${AIRSHIP_VERSION}-executable.jar
chmod 755 airship asconfigFor the remainder of the tutorial, it is assumed that both binaries are available on the search path.
The airship and asconfig tools have a built-in basic help function:
airship help
usage: airship [--batch] [--debug]
[(-e <environment> | --environment <environment>)] <command> [<args>]
The most commonly used airship commands are:
agent Manage agents
config Manage configuration
coordinator Manage coordinators
environment Manage environments
help Display help information about airship
install Install software in a new slot
kill Kill a server
reset-to-actual Reset slot expected state to actual
restart Restart server
show Show state of all slots
ssh ssh to slot installation
start Start a server
stop Stop a server
terminate Terminate (remove) a slot
upgrade Upgrade software in a slot
See 'airship help <command>' for more information on a specific command.
asconfig help
usage: asconfig <command> [<args>]
The most commonly used asconfig commands are:
add Add config for a component
help Display help information
info Show metadata
init Initialize a git config repository
release Build and release a config bundle
snapshot Deploy a snapshot config bundle
See 'asconfig help <command>' for more information on a specific command.
For each subcommand, help can be displayed using help <subcommand>:
asconfig help init
NAME
asconfig init - Initialize a git config repository
SYNOPSIS
asconfig init [--groupId <groupId>]
[--releasesRepository <releasesRepositoryId>]
[--releasesRepositoryUri <releasesRepositoryUri>]
[--snapshotsRepository <snapshotsRepositoryId>]
[--snapshotsRepositoryUri <snapshotsRepositoryUri>]
OPTIONS
--groupId <groupId>
Maven group id
--releasesRepository <releasesRepositoryId>
Default maven releases repository id
--releasesRepositoryUri <releasesRepositoryUri>
Default maven releases repository URI
--snapshotsRepository <snapshotsRepositoryId>
Default maven releases repository id
--snapshotsRepositoryUri <snapshotsRepositoryUri>
Default maven snapshots repository URI
Airship manages service configuration in Configuration Bundles. A configuration bundle is a ZIP file that contain a directory structure which is overlayed onto the installed binary. For example, a config bundle might contain an etc directory with some config files.
Config bundles are stored in the repository as versioned, immutable artifacts (releases) or mutable artifacts (snapshots).
Any binary or configuration installed by airship is described using Maven GAV coordinates. These consist of groupId (G), artifactId (A) and version (V). If the version is followed by -SNAPSHOT it is considered mutable (can be changed), if it is not, an artifact is considered to be immutable.
Binaries installed by airship are described by their maven coordinates, Configuration artifacts have an ampersand (@) prefixed to the GAV coordinates.