Mediated control
Overview
It's unlikely you have just a few isolated Service deployments in your environment. It is more likely that you have sets of like services spread across multiple hosts. If you are running multi-tier applications, you will also have dependencies between some of those services.
Services can be grouped together so you can control them as one logical entity, through a Site. A Site is an object that aggregates a set of Services. You can also roll up multiple Site objects into a root Site object. This allows you to scale up your management and consolidate control into a single point.
This document describes several ways you can organize the services in your environment to help cope with large scale and coordinated control across homogeneous and heterogeneous sets of services.
Control dispatching
Sites really play the role of a logical control point, relaying the requested action to set of Services (or Sites). Sites and Services share a common set of workflows, including: Stop, Start, Status, Deploy. When a Site is asked to execute "Status", it relays the Status command to each of its Service objects and invokes each of them to run Status.
Topological Structures: Tier, Slice, Pool
One can describe the way the constituent services of an application are interrelated and arranged comprise that software system's structure, or topology.
A Site object allows you to arrange any number of Service and Site objects. You are free to invent any arrangement to suit your environment but there three patterns that are commonplace:
- Tier: A tier is a homogenous set of Services. Each instance of the service plays the same functional role and often share a similar pattern of configuration. Example: a set of Apache HTTPD server instances.
- Slice: A slice is a heterogeneous set and possibly interrelated set of services. In a multi-tier application one might imagine a slice as a cross section. Example: A set of interconnected web→app→db server instances.
- Pool: A pool is a grouping of tiers (homogeneous) or slices (heterogeneous) that consolidate control into a single common point.
Ultimately, Site objects allow you to provide the shape for how you want to manage sets of Services. Sites allow you define hierarchical control structures, important when you want to have activity governed by the application topology.
Ordering
Ordering the progression of action is important for controlling application deployments with runtime state. You can establish an ordering to the Site's control dispatching in one of several ways discussed below.
Relative ranking
Even among like Service objects it is sometimes desireable to have the Site dispatch commands in a particular order.
Both Service and Site objects have a property called "startup-rank" that allow you assign a ranking position. By default, Sites use startup-rank as a key to sort the Service objects in ascending order.
The graphic below depicts a set of Services that range from a startup-rank of 1 through 3.
Given that arrangement, the "staging" Site will dispatch first to rank=1, rank=2 and finally, to rank=3. For example, if "Start" command was called on the Site, it would first invoke Start on dev-catalog , next tomcat1, then apache1. This ensures that dev-catalog is up and running before tomcat1 starts, presumably because Tomcat will need to connect to a running dev-catalog database.
The "Stop" command is an notably different. It sorts by startup-rank in descending order. This supports the assumption that you want to shut down in the reverse order of Start. It is best practice to shutdown clients before their servers to avoid hanging connections or cause transactional interruptions. So for this example, the Stop action will first stop apache1 (closing connections to tomcat1), then stop tomcat1 (closing connections to dev-catalog), finally stopping dev-catalog.
Hierarchical
The next manner in which actions can be ordered is based on the topology of the Site and Service objects. Using this approach, A top-level Site dispatches to intermediate Site objects, which in turn dispatch to their Services.
The graphic below describes an example showing how a set of services arranged as a tier, and another set arranged as a slice is managed via a top level Site.
Combined
The two methods of ordering can be combined to first sort by relative ranking, and then via topological structure.
Setup
The following sections provide examples of project XML files that define the various arrangements of Services and Sites.
Tier
The following XML defines two Apache HTTPD server instances grouped together in a Site.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE project PUBLIC "-//ControlTier Software Inc.//DTD Project Document 1.0//EN"
"project.dtd">
<project>
<!--
**
** Describes set of homogeneous Services mediated via a Site
**
-->
<!--
**
** Describes an Apache web server:
**
-->
<deployment
type="Service"
name="apache1"
description="The Apache server."
startuprank="3"/>
<deployment
type="Service"
name="apache2"
description="The Apache server."
startuprank="3"/>
<!--
**
** Describes the site:
**
-->
<mediator
type="Site"
name="apacheTier"
description="The integrated site in the staging environment." />
<!--
**
** References the services as child dependencies
**
-->
<resources>
<resource name="apache1" type="Service" />
<resource name="apache2" type="Service" />
<resources>
</mediator>
</project>
Slice
The following XML provides an example for defining a set of interrelated set of heterogeneous Services.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE project PUBLIC "-//ControlTier Software Inc.//DTD Project Document 1.0//EN"
"project.dtd">
<project>
<!--
**
** Describes an integrated set of Services mediated via a Site
**
-->
<!--
**
** Describes a Mysql relational database
**
-->
<deployment
type="RdbService"
name="dev-catalog"
description="The Mysql database."
startuprank="1"/>
<!--
**
** Describes a Tomcat server
**
-->
<deployment
type="Service"
name="tomcat1"
description="The tomcat server."
startuprank="2">
<!--
**
** References the dev-catalog as a child dependency
**
-->
<resources>
<resource name="dev-catalog" type="RdbService" />
<resources>
</deployment>
<!--
**
** Describes an Apache web server:
**
-->
<deployment
type="Service"
name="apache1"
description="The Apache server."
startuprank="3">
<!--
**
** References the tomcat as a child dependency
**
-->
<resources>
<resource name="tomcat1" type="Service" />
<resources>
</deployment>
<!--
**
** Describes the site:
**
-->
<mediator
type="Site"
name="slice"
description="The integrated site in the staging environment." />
<!--
**
** References the services as child dependencies
**
-->
<resources>
<resource name="apache1" type="Service" />
<resource name="tomcat1" type="Service" />
<resource name="dev-catalog" type="RdbService" />
<resources>
</mediator>
</project>
Pool
The following XML example shows two sets of Services arranged as tiers grouped together under a common Site.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE project PUBLIC "-//ControlTier Software Inc.//DTD Project Document 1.0//EN"
"project.dtd">
<project>
<!--
**
** Describes pool of Tiers
**
-->
<!--
**
** Describes tier 1
**
-->
<mediator
type="Site"
name="webTier-evens"
description="The even numbered apache web server instances .">
<resources>
<resource name="apache2" type="Service" />
<resource name="apache4" type="Service" />
<resource name="apache6" type="Service" />
<resources>
</mediator>
<!--
**
** Describes tier 2
**
-->
<mediator
type="Site"
name="webTier-odds"
description="The odd numbered apache web server instances .">
<resources>
<resource name="apache1" type="Service" />
<resource name="apache3" type="Service" />
<resource name="apache5" type="Service" />
<resources>
</mediator>
<!--
**
** Describes the pool
**
-->
<mediator
type="Site"
name="webPool"
description="Combines all the web slices into one pool .">
<resources>
<resource name="webTier-evens" type="Site" />
<resource name="webTier-odds" type="Site" />
<resources>
</mediator>
</project>
Execution
This section describes how to execute commands against Services via a Site.
The general usage to run a command via a Site is:
ctl -p project -t Site -o name -c command
Example: Dispatch the Status command to the Services in the webTier Site:
ctl -p default -t Site webTier -c Status
Service management
Site objects can dispatch the following standard commands to Service objects: Prepare, Restart, Start, Status, Stop, Change-Dependencies, Configure, Deploy, Install, Properties, Update
Ad-hoc filtered dispatching
Besides using the standard Service management commands described above, you can also dispatch abitrarily via the command, dispatchCmd.
For example, if you want to tell each of the Service objects to run Status:
ctl -p default -t Site -o webTier -c dispatchCmd -- -command Status
... which is equivalent to:
ctl -p default -t Site webTier -c Status
A more interesting usage is to dispatch a command only to a subset of the Services using filtering. There are two options enabling filtering: -resourcename, to filter by the Service's name, and -resourcetype to filter by the Service's type. By default, these options are defaulted to wild card patterns to match all the Services.
Here's a couple examples showing off filtering. The first example dispatches to just the Services that have names starting with "tomcat":
ctl -p default -t Site -o webTier -c dispatchCmd -- -command Status \ -resourcename "tomcat.*"
This would match names like tomcat1 and tomcat2.
To match on the Service's type use the -resourcetype option:
ctl -p default -t Site -o webTier -c dispatchCmd -- -command Status \ -resourcetype RdbService
Both options can be combined:
ctl -p default -t Site -o webTier -c dispatchCmd -- -command Status \ -resource ".*" -resourcetype ".*"
In this case, all the Services are matched (the default).
You can order the execution via the -sortorder option:
ctl -p default -t Site -o webTier -c dispatchCmd -- -command Status \ -sortorder ascending
That will sort the Service objects based on their startup-rank in ascending order.