10.3. The Deployment Agent
The deployment agent listens for local configuration changes on the
io.fabric8.agentPID. Any change in that configuration will trigger the deployment agent.
When the deployment agent is triggered, it performs the following actions:
- The deployment agent reads the whole
io.fabric8.agentPID and calculates what bundles are to be installed in the container.
- If the profiles assigned to the container specify any Karaf features, the deployment agent translates them into a list of bundles, so that the agent obtains a complete list of bundles to install.
- The deployment agent compares the list of bundles to install with the list of bundles currently installed, in order to identify:
- Bundles to uninstall,
- Bundles to install,
- Bundles to update.
- The deployment agent then performs the bundle uninstalling, installing, and updating in the container.
The deployment agent is capable of downloading artifacts from two different types of maven repository:
- Registered Fabric Maven proxies
- Configured Maven repositories (any Maven repository configured in the profile overlay).
Priority is always given to the Fabric Maven proxies. If more than one Maven proxy is registered in the fabric, the proxies are used in order, from the oldest to the newest.
If the target artifact is not found in the Maven proxies, the configured Maven repositories are used instead. The list of repositories is determined by the
org.ops4j.pax.url.mvn.repositoriesproperty of the
To change the list of repositories for a specific profile, you can simply change the
org.ops4j.pax.url.mvn.repositoriesproperty using the
fabric:profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories=http://repositorymanager.mylocalnetwork.net default
It is recommended that you specify this configuration in one profile only, and have the rest of profiles inherit from it. The
defaultprofile, which is the ancestor of all of the standard profiles, is the ideal place for this.
In most cases, when a container is provisioned by the provisioning agent, the container is kept alive and no restart is needed. A restart becomes necessary, however, whenever the following changes are made:
- Changes to the OSGi framework;
- Changes to the OSGi framework configuration.
The normal case is where the container stays alive during provisioning, because it is rarely necessary to make changes to the underlying OSGi framework. If a container does need to restart, the restart is performed automatically by the deployment agent and, after the restart, the container reconnects to the cluster without any manual intervention.
Monitoring the provisioning status
Throughout the whole process of deploying and provisioning, the deployment agent stores the provisioning status in the runtime registry, so that it is available to the whole cluster. The user can check the provisioning status at any time using the
JBossFuse:karaf@root> fabric:container-list [id] [version] [alive] [profiles] [provision status] root* 1.0 true fabric, fabric-ensemble-0000-1 success mq1 1.0 true mq success mq2 1.0 true mq downloading billing-broker 1.0 true billing success admin-console 1.0 true web, admin-console success
To monitor the provisioning status in real time, you can pass the
fabric:container-listcommand as an argument to the
shell:watchcommand, as follows:
Resolution and startup ordering
To figure out what bundles need to be installed and what bundles need to be removed, the Fabric agent uses the OSGi Bundle Repository (OBR) resolver. The OBR resolver makes sure that all requirements are met (usually package requirements, but potentially also service requirements). To discover a bundle's requirements, the OBR reads the following bundle headers:
- For each package listed here, the OBR resolver searches for a bundle that declares the package in a corresponding
- For each service listed here, the OBR resolver searches for a bundle that declares the service in a corresponding
If you are using Blueprint configuration files, it is especially important to be aware of the need to add an
Export-Serviceheader to bundles that implement services. Blueprint configuration files with mandatory references to services will automatically be packaged with the
Import-Servicebundle header (assuming that you use the
maven-bundle-plugin). If the bundle that exports the service does not explicitly specify an
Export-Serviceheader, resolution will fail. To fix this error, either the exporter bundle must add an
Export-Servicedeclaration, or the importer bundle must remove the
If resolution is successful, the Fabric agent will start the bundles. Even though you should try to avoid having requirements in the startup order of your bundles, the Fabric agent will attempt to start the bundles based on their expressed requirements and capabilities. This will not solve all issues, especially in cases where asynchronous service registration is involved. The best way to deal with this kind of issues is to use OSGi services.