Deployment
An interface to an application deployment
Overview
Deployment:
An interface to an application deployment
- Define an object that encapsulates the life-cycle of software deployment.
- Separate the concerns of software installation from software configuration.
- Encourage abstracting software deployments so that a single definition can be used in multiple environment contexts.
Problem
We want to design a reusable software deployment procedures, but dependencies between software packages and environment-specific configuration demonstrate that an inflexible "hard-coded" result often ensues.
Discussion
The post development application life-cycle is dominated by migrating software from one environment to another. Primarily, the migration tasks fall into two categories:
- software installation: locating and distributing the needed files to the designated host
- configuration setup: customizing the software installation using the needed application and environment specific parameters
Because a software deployment can differ depending on context, the installer must often be aware of both the constant and variable details and then mentally translate the steps of the deployment process accordingly. The figure below illustrates the different dimensions of information a person deploying an application must consider.
The differences between deployments within their specific application environment context undermine a desirable goal to have a single procedure that can be used anywhere in any environment and any software version. This jumble of configuration and procedural information seem intertwined and difficult to separate.
An alternate approach would be to introduce an abstraction of deployment that breaks the configuration and installation problem into separate concerns and encapsulate the contextual application environment differences.
This offers several advantages: Configuration and installation are decoupled from one another, many mappings between environment contexts and configuration and installation can be maintained and the entire deployment procedure can be extended by defining derived classes.
Further, the deployment abstraction defines a standard structure for software deployment as well as, a standard deployment life-cycle.
As a standard structure, the deployment abstraction accounts for key parameters like installation root and deployment base directory, two properties which may be the same in some cases, but should be separable to distinguish directories where static executable files reside from those where runtime files supporting configuration and logging exist.
Along similar lines, the deployment structure organizes dependency, configuration and environment information into a mapped context that facilitates abstracting configuration files and procedures. The abstracted configuration and procedures can then take form as template files increasing their reuse and decreasing the maintenance of environment specific variations.
Finally, the deployment abstraction defines a standard update life-cycle for the deployment processes promoting the configuration and installation steps into formalized and standard operations.
Example
The Deployment type defines an object that maintains environment and dependency context, as well as, one that coordinates the installation and configuration processes. A deployment of an Apache web server is a simple yet representative scenario wherein a set of package dependencies, configuration files and environment specific parameters must be combined to produce a working httpd deployment.
The figure below illustrates these parts. A Deployment named "apache" is defined to depend on two packages - httpd-2.0.1.tgz and mod_jk.zip, and corresponding configuration files, httpd.conf and jk.conf. The environment specific context is provided to the Deployment object which in turn uses it when parameterizing the configuration and package installation steps.
Structure
The deployment abstraction breaks down into a common design pattern comprised of several types
- Deployment: provides parameters and procedures that govern the deployment life-cycle.
- Package: encapsulates the package format specific installation procedures (e.g., extraction and verification).
- Document: encapsulate the generation of configuration files from templates.
Check List
- Identify the package dependencies and configuration files required for the deployment
- Discern the parameters that differ across environments that affect the configuration and installation process.
- Encapsulate those parameters as attributes of a new class of Deployment.
- Delegate the package installation and doc generation to objects of those types.
Design
- Super Type
- Managed-Entity
| Role | Concrete. (Objects can be created.) |
| Instance Names | Unique |
| Notification | false |
| Template Directory | |
| Data View | Children, proximity: 1 |
| Logger Name | Deployment |
Constraints
Allowed Child Dependencies
- DeploymentSetting
- FilePath
Allowed Parent Dependencies
- Deployment
- Node
Allowed Property Values
| Property | Allowed Values | Default | Enforced | Description |
|---|---|---|---|---|
| manages-deployments |
|
true |
Deprecated |
Commands
Configure
runs the configuration cycle
The Configure command manages the configuration phase of the deployment lifecycle and invokes the Docs-Generate to generate any configured template-based documents. The typical usage of Configure, is to customize a Deployment's configuration according to its environmental context after the package installation step has occurred. Subtypes can override the Configure workflow to include additional configuration related commands.
- Usage
- Configure
Workflow
Docs-Generate
generates all defined docs
The role of the Docs-Generate command is to generate any template based documents. Typically, these are configuration file templates that reference property names provided by the object context. The implementation provided by Deployment is to iterate over the set of properties of the pattern: ^document.(.*).template$ and to call the command, Doc-Generate for each one.
If -archivedir <directory> option is used then any files that were created from the previous run of Docs-Generate are copied to that that directory.
- Usage
- Docs-Generate [-archivedir <${entity.instance.dir}/var>]
Options
| Option | Description |
|---|---|
| archivedir | dir to store current output docs |
Docs-Verify
verifies all generated docs
The Docs-Verify command generates all the defined template based documents to a temporary location and then compares them to the ones last generated by Docs-Generate. If any differences are found an error is raised. This command can be useful to determine if modifications occured outside the framework.
- Usage
- Docs-Verify
Get-Properties
Gets the properties for the object
The Get-Properties command requests information about the object from the server and saves its local instance directory in the CTL project depot.
The -direction and -proximity arguments use command settings defined with the module for defaults.
Internally, Get-Properties uses an Ant task to communicate with the server to retrieve object model information which is transformed into Java properties key/value pair format. To reduce load on the server, the Get-Properties command only requires the server to generate data if the object revision has changed since the last invocation. This check can be defeated through the use of the -force flag which will first call Remove-Properties.
- Usage
- Get-Properties [-destfile <${entity.properties.file}>] [-direction <>] [-force] [-print] [-proximity <>]
Options
| Option | Description |
|---|---|
| destfile | file to save property data |
| direction | dependency view direction (internal, external, bidirectional) |
| force | Remove old properties file first |
| flag specifying Properties command should run after properties are saved | |
| proximity | dependency view proximity |
Install
Installs the object, and its modules
Installs the object into the local CTL project depot. The Install command is essentially a command workflow that calls the Install-Module and Get-Properties command (though there are boolean flags to skip those commands).
- Usage
- Install [-basedir <${entity.instance.dir}>] [-depot <${context.depot}>] [-name <${context.name}>] [-nodir] [-nomodule] [-noproperties] [-subdirs <>] [-type <${context.type}>]
Options
| Option | Description |
|---|---|
| basedir | instance directory |
| depot | project depot |
| name | object name |
| nodir | do not create directories |
| nomodule | do not update module |
| noproperties | do not update properties |
| subdirs | directory list |
| type | object type |
Packages-Install
installs all the package dependencies
The Packages-Install command iterates over all the package object dependencies declared in the object context, and for each one, calls Package's install command. Packages-Install parses the object context for properties matching the pattern: ^package\.(${opts.packagetype})\.(.*)\.package-install-rank.
It is possible to only install packages of a certain type using the -packagetype option.
- Usage
- Packages-Install [-packagetype <[^\.]*>]
Options
| Option | Description |
|---|---|
| packagetype | type of packages to install |
Properties
prints object properties.
The Properties command prints out the contents of the object properties file generated by the Get-Properties command.
By default, the command uses the -format pretty option to present the property data in a human readable form. The -format plain option will print the property data in the normal Java property key/value form.
The -detail flag will include detail about child object data.
- Usage
- Properties [-detail] [-format <pretty>]
Options
| Option | Description |
|---|---|
| detail | print more detail |
| format | output format. pretty or plain |
Register
Registers the object
The Register command registers an object in the project model maintained in the server. The registration information will include the values specified by the depot,type,name as well as -basedir, -installroot and -node. The -node argument specifies what node this object should be a child dependency to.
If the -install flag is set, the Install command is also run.
- Usage
- Register [-basedir <>] [-depot <>] [-description <>] [-install] [-installrank <>] [-installroot <>] [-name <>] [-node <${framweork.node}>] [-type <>]
Options
| Option | Description |
|---|---|
| basedir | base directory |
| depot | project depot name |
| description | object description |
| install | after registration, run Install command |
| installrank | install rank |
| installroot | install directory |
| name | object name |
| node | after registration, bind this object to the specified node |
| type | type name |
Register-Dependency
Registers an object-to-object dependency
The Register-Dependency command defines a dependency relationship between two objects. The -relation option specifies what direction the dependency should be defined. When child is set, then the object is made a child of the -type and -object. When parent is set, then the object is made a parent of the -type and -object.
The Register-Dependency command will check to see that both objects exists before attempting to define the dependency and will fail if either does not exist.
To make a dependency like: (Deployment) deployment -> (Setting) aSetting, run:
ctl -p project -t Deployment -o deployment -c Register-Dependency -- \ -type Setting -o aSetting -relation child
To make a dependency like: (Node) aNode -> (Deployment) deployment, run:
ctl -p project -t Deployment -o deployment -c Register-Dependency -- \ -type Node -o aNode -relation parent
- Usage
- Register-Dependency -object <> [-relation <child>] -type <>
Options
| Option | Description |
|---|---|
| object | object name |
| relation | parent or child (default) |
| type | type name |
Update
executes the deployment cycle
Update is a workflow that executes the commands that comprise deployment lifecycle: Packages-Install and Configure.
- Usage
- Update