OSGi allows you to build your systems out of well defined, reusable components, which brings both exciting new benefits as well as a set of challenges. One of these is the actual management of components, deployed on different target systems.

Traditional, monolithic systems usually have fairly straightforward and linear release schedules. It is quite common for most target systems to have the same version and configuration of such a system.

Component based systems can easily be customized on a per target case, meaning there might be many different configurations out there. When components are developed over time, they might be released individually and a lot more often than these traditional systems.

Keeping track of what is installed where becomes quite a challenge if the number of components and targets grows, and this is where Apache ACE comes in.

Apache ACE is a software distribution framework. It is written as a set of OSGi components and consists of three major subsystems:

1. dependency management, which handles the complexity of managing the dependencies between component, aggregating them into groups and licenses and associating those to targets
2. deployment management, which ensures that the right components get installed onto the right targets in a robust and scalable way
3. feedback management, which collects life cycle feedback on the target and aggregates that on a central server

A typical topology consists of:

• a server, holding the components and their metadata
• multiple target systems, which all connect to the server
• a client, usually a web browser, on which the user interacts with the server

The Apache ACE software, which consists of a set of OSGi bundles, gets deployed on a server. A target can be any OSGi framework (Apache Felix, Equinox or Knopflerfish) with the Apache ACE management agent installed. This agent will connect to the server, identify itself and poll for updates.

Introduction

This guide shows the core functionality of ACE, organizing bundles and other artifacts into logical features and distributions and associating those with specific targets, all done using a convenient web interface.

Using Apache ACE

The following steps can be followed to get started:

1. First we need to actually checkout and build ACE. Follow the link to get more information on how to do that.
2. Once ACE is built, we can start the server with integrated Web UI. Go to ace-target-devserver/target/org.apache.ace.target.devserver-*-distribution/ace-devserver. Start it using the run.sh or run.bat file.
3. Now the server is started, let's connect to it. Launch a browser and point it to: http://localhost:8080/ace/ You should now be greeted with a login prompt. Log in with user "d" password "f" and you should see a view with 4 empty columns and some buttons at the top of the screen.
4. Click on 'Retrieve' to get the initial version of the repository. It will look as if nothing's happened, but you have now in fact retrieved the first, empty version of the repository and can start manipulating it. Once you're happy with it, you can commit it back (which we'll do a bit later).
5. Upload some sample bundles into the artifacts column by first clicking the 'Add Artifact...' button. In the dialog that appears, you can upload a bundle using the 'Upload' button in the middle of the window. You can perform this step multiple times if you want to upload more than one bundle. Finally, hit the 'Add' button to add all uploaded artifacts to ACE.
6. Create a feature by clicking on the 'Add Feature...' button. Features are the first level of logical grouping for artifacts.
7. Create a distribution by clicking on the 'Add Distribution...' button. Distributions are another level of logical grouping: you group features into distributions.
8. Drag an artifact onto a feature to create an association between the two. By repeating this process you can associate all relevant artifacts to features.
9. Drag a feature onto a distribution and again repeat this process until you've associated all your features with their relevant distributions.
10. Now we need a target to actually deploy our artifacts to. To start a target, go to ace-launcher/target and start it using java -jar org.apache.ace.launcher*.jar.
11. After a few seconds, the target should show up in the Web UI. To associate it with a distribution, drag that distribution onto the target.
12. Click on 'Store' to actually store changes on the server, which should trigger the actual deployment of the artifacts to the target.

Debugging

You can hook up a standard remote debugger to either target. To do that, edit the run.sh (or run.bat) script and include the following extra parameter for Pax Runner:

--vmOptions="-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y"

Now run the target, and start the debugger of your favorite IDE.

Introduction

Apache ACE consists of a number of components, which can be deployed more-or-less independently.

Overview

ACE consists of several components, distributed over a number of nodes in the network. The image above shows the most elaborate situation, consisting of five nodes, each running their part of some functionality of ACE.

The system has the following nodes,

• Client A client system has functionality for altering the configuration of the deployment process.
• Server The server contains all necessary metadata to allow provisioning, and acts as a hub for logging information.
• Relay A relay server keeps a copy of the metadata of the server, and can provide a target with all functionality a 'regular' server can. Note that this allows for offline provisioning, and note that there can be a chain of relay servers.
• Target The target is the system to which software is to be provisioned.
• OBR The OBR contains the actual software to be provisioned.

The nodes together have the following components,

• Deployment See below.
• Logging See below.
• Identification Each target needs a unique name; the Identification components provide this functionality.
• Discovery Targets and relays need to find the next server 'upstream' from the current node.
• Configuration ACE uses its own configuration mechanism, which works by reading configuration files, and putting that information into Config Admin.
• Scheduling Some components needs to have scheduled actions to allow logging and provisioning; the Scheduling component helps with that.

Given this information, it might also be useful to compare this with the Software Architecture.

Alternative topologies

TODO create more professional looking images

The three topologies below are just examples; you can take (almost) any component, and drop it somewhere in your network, all components are intended to be distributed.

Single server

In the case of a single server, the OBR and the required server components are deployed on one system, and all target nodes connect to that one. This is the scenario that Getting Started with the File Based Server uses.

Offline

This scenario can be used in the case of a service engineer who takes his laptop to a machine to be serviced. Assuming that these devices do not have internet connectivity (for cost- or security reasons), the engineer loads up his laptop with the most recent situation from the server (this will happen automatically), and later connect it to the machine. The machine will get its new software, and upload its logs to the service laptop; the logs will later be synced back to the server.

Firewalled

In this scenario, the administration is done on the 'big bad internet', but the server on the internet only contains metadata. The actual code is located in the OBR's behind the firewall; here, we also see the distribution possiblities.

Provisioning

Software provisioning is the main task of ACE. The provisioning components are responsible for determining the set of bundles to be deployed to a given target, creating a deployment package, and feeding the deployment package to the Deployment Admin.

Components

TODO show the components of the provisioning mechanism, and where they operate. Remember to point out that the gateway contains separate bundles, but there is also an integrated management agent.

Further reading

TODO create a child page that describes the provisioning part in more detail

Logging and reporting

ACE contains a logging and reporting facility. This mechanism allows a target to send back logging information to the server, and allows the storing of arbitrary key-value pairs.

The logging mechanism is extensible with extra logging information. The basic implementation will log framework events (e.g., starting and stopping of bundles), and deployment events.

Components

• o.a.a.server.log The server's log bundle handles the access to the access logs on the server, and provides a servlet that is used for synchronizing logs between target (or relay) and server.
• o.a.a.server.log.store Stores the log on the file; this functionality is separated to allow some other storage mechanism than the file system.

• o.a.a.server.log.task This task is provided to the o.a.a.scheduler so the relay server can synchronize its logs with the 'master' server.

• o.a.a.log Contains general interfaces for the gateway's logs.
• o.a.a.log.listener Listens for framework events, and logs those to the gateway log.
• o.a.a.gateway.log Provides a Log service to which events can be logged.
• o.a.a.gateway.log.store Stores the logs on the gateway until they can be synchronized.

• o.a.a.scheduler The scheduler is used to, configurably, run a task with a given interval. This is used by both the gateway and the relay to synchronize the log.

Further reading

TODO create a child page that shows what the logging is about, and how to add your own logging to the mechanism.

There are basically three ways to use the management agent. You can use the ACE launcher, which combines an OSGi framework with an embedded management agent in a single, executable JAR file. This by far is the easiest way to get started. The second option is to use the "all in one" management agent bundle. You can drop this one in an existing OSGi framework easily and configure it with just a few options. The third and last option is to use the set of bundles that make up the management agent. If you want to extensively customize it, this is the best way to do so, but for normal use cases it's probably more complex than necessary.

Using the launcher

Usage: java -jar ace-launcher.jar [identification=<id>] [discovery=<ace-server>] [options...]

All known options are:

• identification: sets the target ID to use
• discovery: sets the ACE server to connect to
• agents: configures multiple management agents: agent-id,identification,discovery[;agent-id,identification,discovery]*
• fwOption: sets framework options for the OSGi framework to be created. This argument may be repeated
• help: prints this help message

Example:
java -jar ace-launcher.jar identification=MyTarget discovery=http://provisioning.company.com:8080 fwOption=org.osgi.framework.system.packages.extra=sun.misc,com.sun.management

Using the management agent bundle

We have a pre-configured and pre-packaged management agent as a single bundle. It can be configured using system properties:

• identification: sets the target ID to use
• discovery: sets the ACE server to connect to
• agents: configures multiple management agents: agent-id,identification,discovery[;agent-id,identification,discovery]*

Using the set of fine grained bundles

For development, the options above provide a lot of flexibility.

The bundles that are needed for the management agent are:

• org.apache.ace.identification.ifconfig implements and publishes the Identification service, which is used to identify the gateway. This bundle uses ifconfig to get to the MAC address of the network card.
• org.apache.ace.discovery.property implements the Discovery service, which uses a configured property to "discover" the URL of the provisioning server.
• org.apache.ace.deployment contains the actual deployment engine to install and update deployments.
• org.apache.ace.deployment.task contains the schedulable task that invokes the deployment engine.
• org.apache.ace.scheduler a simple scheduler that schedules tasks.
• org.apache.ace.configurator a bundle that picks up configurations from a "conf" folder and puts them in Configuration Admin. It uses plain property files that are named after the symbolic names of the bundles they configure (with .cfg extension). Factories are represented as directories (with .cfg files inside).
• org.apache.ace.gateway.log log synchronization task, which synchronizes local logs with the provisioning server.
• org.apache.ace.gateway.log.store local log store, stores all logs locally.
• org.apache.ace.log log contains some logging interfaces.
• org.apache.ace.log.listener listener for log events that need to be recorded to the audit log.
• org.osgi.compendium OSGi compendium bundle, contains interfaces.
• org.osgi.mobile OSGi mobile compendium bundle, contains interfaces.
• javax.servlet servlet API, required by the OSGi compendium.
• org.apache.felix.dependencymanager dependency manager implementation bundle.
• org.apache.felix.configadmin configuration admin service implementation, needed to configure certain aspects of the management agent.
• org.apache.felix.eventadmin event admin implementation, needed to listen to certain vital events during deployment.
• org.apache.felix.deploymentadmin deployment admin implementation from Apache Felix.
• log_all log service, any implementation will do here, this one is from Knopflerfish.
• consolelogger dumps the log to the console, using any log service implementation.

So, what can you actually configure?

• The management agent itself can be configured and uses Configuration Admin. The configurator bundle is merely a way to get data in Configuration Admin, but could be replaced if you, for example, want to hardcode this information in a different way.
• The scheduler actually makes sure the tasks (which are services) are invoked regularly. You can replace it with your own scheduler that uses a completely different algorithm to invoke these tasks.
• The identification service determines the way the management agent identifies itself to the server.
• The discovery service determines the way the management agent actually "discovers" the server.