Repository: karaf-cellar Updated Branches: refs/heads/master d58dd5899 -> 0f49d5ddf
Use article for documentation Project: http://git-wip-us.apache.org/repos/asf/karaf-cellar/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf-cellar/commit/0f49d5dd Tree: http://git-wip-us.apache.org/repos/asf/karaf-cellar/tree/0f49d5dd Diff: http://git-wip-us.apache.org/repos/asf/karaf-cellar/diff/0f49d5dd Branch: refs/heads/master Commit: 0f49d5ddfcc3d6c7cbe688c86e32c70d7faed5ef Parents: d58dd58 Author: Jean-Baptiste Onofré <[email protected]> Authored: Mon Jan 4 16:44:33 2016 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Mon Jan 4 16:44:33 2016 +0100 ---------------------------------------------------------------------- manual/pom.xml | 4 +-- .../broadcasting_commands.adoc | 2 +- .../asciidoc/architecture-guide/design.adoc | 4 +-- .../asciidoc/architecture-guide/hazelcast.adoc | 4 +-- .../asciidoc/architecture-guide/overview.adoc | 2 +- .../architecture-guide/supported_events.adoc | 2 +- manual/src/main/asciidoc/index.adoc | 6 ++-- manual/src/main/asciidoc/user-guide/cloud.adoc | 27 ++++++++++-------- manual/src/main/asciidoc/user-guide/deploy.adoc | 8 +++--- manual/src/main/asciidoc/user-guide/event.adoc | 6 ++-- manual/src/main/asciidoc/user-guide/groups.adoc | 26 +++++++++++------- .../src/main/asciidoc/user-guide/hazelcast.adoc | 15 +++++++--- .../main/asciidoc/user-guide/http-balancer.adoc | 11 +++++--- .../main/asciidoc/user-guide/http-session.adoc | 6 ++-- .../main/asciidoc/user-guide/installation.adoc | 17 +++++++----- .../main/asciidoc/user-guide/introduction.adoc | 10 ++++--- manual/src/main/asciidoc/user-guide/nodes.adoc | 29 +++++++++++++------- manual/src/main/asciidoc/user-guide/obr.adoc | 8 +++--- .../src/main/asciidoc/user-guide/transport.adoc | 2 +- 19 files changed, 111 insertions(+), 78 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/pom.xml ---------------------------------------------------------------------- diff --git a/manual/pom.xml b/manual/pom.xml index fe19082..1b883db 100644 --- a/manual/pom.xml +++ b/manual/pom.xml @@ -49,7 +49,7 @@ <configuration> <sourceHighlighter>coderay</sourceHighlighter> <backend>html5</backend> - <doctype>book</doctype> + <doctype>article</doctype> <attributes> <toc/> <linkcss>false</linkcss> @@ -60,7 +60,7 @@ <configuration> <sourceDirectory>src/main/asciidoc</sourceDirectory> <headerFooter>true</headerFooter> - <imagesDir>../resources/images</imagesDir> + <imagesDir>src/main/asciidoc/images</imagesDir> </configuration> </plugin> <plugin> http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/architecture-guide/broadcasting_commands.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/architecture-guide/broadcasting_commands.adoc b/manual/src/main/asciidoc/architecture-guide/broadcasting_commands.adoc index 3cd5d13..6ecfe14 100644 --- a/manual/src/main/asciidoc/architecture-guide/broadcasting_commands.adoc +++ b/manual/src/main/asciidoc/architecture-guide/broadcasting_commands.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Broadcasting commands +=== Broadcasting commands Commands are a special kind of event. They imply that when they are handled, a `Result` event will be fired containing the outcome of the command. For each command, we have one result per recipient. http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/architecture-guide/design.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/architecture-guide/design.adoc b/manual/src/main/asciidoc/architecture-guide/design.adoc index 52f8629..c009a74 100644 --- a/manual/src/main/asciidoc/architecture-guide/design.adoc +++ b/manual/src/main/asciidoc/architecture-guide/design.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Design +=== Design The design works with the following entities: @@ -26,7 +26,7 @@ The design works with the following entities: * *Command* is a special type of event that is linked to a list of events that represent the outcome of the command. * *Result* is a special type of event that represents the outcome of a command. Commands and results are correlated. -image::images/event_flow.jpg[] +image::event_flow.jpg[] The OSGi specification uses the `Events` and `Listener` paradigms in many situations (e.g. `ConfigurationChangeEvent` and `ConfigurationListener`). By implementing such a Listener and exposing it as an OSGi service to the Service http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/architecture-guide/hazelcast.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/architecture-guide/hazelcast.adoc b/manual/src/main/asciidoc/architecture-guide/hazelcast.adoc index 81481cf..bf08081 100644 --- a/manual/src/main/asciidoc/architecture-guide/hazelcast.adoc +++ b/manual/src/main/asciidoc/architecture-guide/hazelcast.adoc @@ -12,13 +12,13 @@ // limitations under the License. // -== The role of Hazelcast +=== The role of Hazelcast The idea behind the clustering engine is that for each unit that we want to replicate, we create an event, broadcast the event to the cluster and hold the unit state to a shared resource, so that the rest of the nodes can look up and retrieve the changes. -image::images/shared_architecture.jpg[] +image::shared_architecture.jpg[] For instance, we want all nodes in our cluster to share configuration for PIDs a.b.c and x.y.z. On node "Karaf A" a change occurs on a.b.c. "Karaf A" updated the shared repository data for a.b.c and then notifies http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/architecture-guide/overview.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/architecture-guide/overview.adoc b/manual/src/main/asciidoc/architecture-guide/overview.adoc index 4680a2d..3553280 100644 --- a/manual/src/main/asciidoc/architecture-guide/overview.adoc +++ b/manual/src/main/asciidoc/architecture-guide/overview.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Architecture Overview +=== Architecture Overview The core concept behind Karaf Cellar is that each node can be a part of one or more groups that provide the node distributed memory for keeping data (e.g. configuration, features information, other) http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/architecture-guide/supported_events.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/architecture-guide/supported_events.adoc b/manual/src/main/asciidoc/architecture-guide/supported_events.adoc index 0adcbb5..af9cdab 100644 --- a/manual/src/main/asciidoc/architecture-guide/supported_events.adoc +++ b/manual/src/main/asciidoc/architecture-guide/supported_events.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Supported Events +=== Supported Events There are 3 types of events: http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc index e52f8db..c8200ae 100644 --- a/manual/src/main/asciidoc/index.adoc +++ b/manual/src/main/asciidoc/index.adoc @@ -15,14 +15,14 @@ Apache Karaf Cellar 4.x - Documentation ======================================== Apache Software Foundation -:doctype: book +:doctype: article :toc: left :toclevels: 3 :toc-position: left :toc-title: Apache Karaf Cellar 4.x - Documentation :numbered: -= User Guide +== User Guide include::user-guide/introduction.adoc[] @@ -48,7 +48,7 @@ include::user-guide/transport.adoc[] include::user-guide/cloud.adoc[] -= Architecture Guide +== Architecture Guide include::architecture-guide/overview.adoc[] http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/cloud.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/cloud.adoc b/manual/src/main/asciidoc/user-guide/cloud.adoc index 4cbf8de..d484b1d 100644 --- a/manual/src/main/asciidoc/user-guide/cloud.adoc +++ b/manual/src/main/asciidoc/user-guide/cloud.adoc @@ -12,26 +12,26 @@ // limitations under the License. // -== Discovery Services +=== Discovery Services The Discovery Services allow you to use third party libraries to discover the nodes member of the Cellar cluster. -=== jClouds +==== jClouds -Cellar relies on Hazelcast (http://www.hazelcast.com) in order to discover cluster nodes. This can happen either by using unicast, multicast or specifying the ip address of each node. +Cellar relies on http://www.hazelcast.com[Hazelcast] in order to discover cluster nodes. This can happen either by using unicast, multicast or specifying the ip address of each node. See the link:hazelcast[Core Configuration] section for details. Unfortunately multicast is not allowed in most IaaS providers and the alternative of specifying all IP addresses creates maintenance difficulties, especially since in most cases the addresses are not known in advance. -Cellar solves this problem using a cloud discovery service powered by jclouds (http://jclouds.apache.org). +Cellar solves this problem using a cloud discovery service powered by http://jclouds.apache.org[jClouds]. -==== Cloud discovery service +===== Cloud discovery service Most cloud providers provide cloud storage among other services. Cellar uses the cloud storage via jclouds, in order to determine the IP addresses of each node so that Hazelcast can find them. This approach is also called blackboard and refers to the process where each node registers itself in a common storage are so that other nodes know its existence. -==== Installing Cellar cloud discovery service +===== Installing Cellar cloud discovery service To install the cloud discovery service simply install the appropriate jclouds provider and then install cellar-cloud feature. Amazon S3 is being used here for this example, but the below applies to any provider supported by jclouds. @@ -62,14 +62,17 @@ container=cellar validity=360000 ---- -NB: you can find the cloud providers supported by jclouds here http://repo1.maven.org/maven2/org/apache/jclouds/provider/. -You have to install the corresponding jclouds feature for the provider. +[NOTE] +==== +You can find the cloud providers supported by jClouds here http://repo1.maven.org/maven2/org/apache/jclouds/provider/. +You have to install the corresponding jClouds feature for the provider. +==== After creating the file the service will check for new nodes. If new nodes are found the Hazelcast instance configuration will be updated and the instance restarted. -=== Kubernetes & docker.io +==== Kubernetes & docker.io -link:http://kubernetes.io[Kubernetes] is an open source orchestration system for docker.io containers. +http://kubernetes.io[Kubernetes] is an open source orchestration system for docker.io containers. It handles scheduling onto nodes in a compute cluster and actively manages workloads to ensure that their state matches the users declared intentions. @@ -83,7 +86,7 @@ folder, etc. so that your Kubernetes container may bootstrap everything on boot. The Cellar Kubernetes discovery service is a great complement to the Karaf docker.io feature (allowing you to easily create and manage docker.io images in and for Karaf). -==== Kubernetes discovery service +===== Kubernetes discovery service In order to determine the IP address of each node, so that Hazelcast can connect to them, the Kubernetes discovery service queries the Kubernetes API for containers labeled with the `pod.label.key` and `pod.label.key` specified in `etc/org.apache.karaf.cellar.kubernetes-name.cfg`. @@ -96,7 +99,7 @@ So, you *must be sure* to label your containers (pods) accordingly. After a Cellar node starts up, Kubernetes discovery service will configure Hazelcast with currently running Cellar nodes. Since Hazelcast follows a peer-to-peer all-shared topology, whenever nodes come up and down, the cluster will remain up-to-date. -==== Installing Kubernetes discovery service +===== Installing Kubernetes discovery service To install the Kubernetes discovery service, simply install cellar-kubernetes feature. http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/deploy.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/deploy.adoc b/manual/src/main/asciidoc/user-guide/deploy.adoc index a5aa4c2..c98be09 100644 --- a/manual/src/main/asciidoc/user-guide/deploy.adoc +++ b/manual/src/main/asciidoc/user-guide/deploy.adoc @@ -12,12 +12,12 @@ // limitations under the License. // -== Deploy Cellar +=== Deploy Cellar This chapter describes how to deploy and start Cellar into a running Apache Karaf instance. This chapter assumes that you already know Apache Karaf basics, especially the notion of features and shell usage. -=== Registering Cellar features +==== Registering Cellar features Karaf Cellar is provided as a Karaf features XML descriptor. @@ -33,7 +33,7 @@ Now you have Cellar features available in your Karaf instance: karaf@root()> feature:list |grep -i cellar ---- -=== Starting Cellar +==== Starting Cellar To start Cellar in your Karaf instance, you only need to install the Cellar feature: @@ -53,7 +53,7 @@ And Cellar cluster commands are now available: karaf@root()> cluster:<TAB> ---- -=== Optional features +==== Optional features Optionally, you can install additional features. http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/event.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/event.adoc b/manual/src/main/asciidoc/user-guide/event.adoc index 3cceac5..7430525 100644 --- a/manual/src/main/asciidoc/user-guide/event.adoc +++ b/manual/src/main/asciidoc/user-guide/event.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== OSGi Event Broadcasting support (eventadmin) +=== OSGi Event Broadcasting support (eventadmin) Apache Karaf Cellar is able to listen all OSGi events on the cluster nodes, and broadcast each events to other nodes. -=== Enable OSGi Event Broadcasting support +==== Enable OSGi Event Broadcasting support OSGi Event Broadcasting is an optional feature. To enable it, you have to install the cellar-eventadmin feature: @@ -24,7 +24,7 @@ OSGi Event Broadcasting is an optional feature. To enable it, you have to instal karaf@root()> feature:install cellar-eventadmin ---- -=== OSGi Event Broadcast in action +==== OSGi Event Broadcast in action As soon as the cellar-eventadmin feature is installed (on all nodes that should use the clustered eventadmin), Cellar listens all OSGi events, and broadcast these events to all nodes of the same cluster group. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/groups.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/groups.adoc b/manual/src/main/asciidoc/user-guide/groups.adoc index 433ea69..6e49cb7 100644 --- a/manual/src/main/asciidoc/user-guide/groups.adoc +++ b/manual/src/main/asciidoc/user-guide/groups.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Cellar groups +=== Cellar groups You can define groups in Cellar. A group allows you to define specific nodes and resources that are to be working together. This permits some nodes (those outside the group) not to need to sync'ed with changes of @@ -29,7 +29,7 @@ x | default | node2:5702 node1:5701(x) The 'x' indicates a local group. A local group is a group containing the local node (where we are connected). -=== New group +==== New group You can create a new group using the group-create command: @@ -47,9 +47,9 @@ x | default | node2:5702 node1:5701(x) | test | ---- -=== Clustered Resources and Cluster Groups +==== Clustered Resources and Cluster Groups -==== Features +===== Features Cellar can manipulate features and features repositories on cluster groups. @@ -72,6 +72,7 @@ org.ops4j.pax.web-3.1.2 | cluster/local | mvn:org.ops4j.pax.web/pax-web-feat You have the name of the repository, and the URL, like in the feature:repo-list command. However, the cluster:feature-repo-list command provides the location of the features repository: + * cluster means that the repository is defined only on the cluster group * local means that the repository is defined only on the local node (not on the cluster) * cluster/local means that the repository is defined both on the local node, but also on the cluster group @@ -129,12 +130,13 @@ feature.listener = false ---- The listener listens for the following local feature changes: + * add features repository * remove features repository * install feature * uninstall feature -==== Bundles +===== Bundles Cellar can manipulate bundles on cluster groups. @@ -188,12 +190,13 @@ bundle.listener = false ---- The bundle listener listens the following local bundle changes: + * install bundle * start bundle * stop bundle * uninstall bundle -==== Configurations +===== Configurations Cellar can manipulate configurations on cluster groups. @@ -277,15 +280,15 @@ You can modify this list using the same command, or by editing the `etc/org.apac config.excluded.properties = service.factoryPid, felix.fileinstall.filename, felix.fileinstall.dir, felix.fileinstall.tmpdir, org.ops4j.pax.url.mvn.defaultRepositories ---- -==== OBR (optional) +===== OBR (optional) See the link:obr[OBR section] for details. -==== EventAdmin (optional) +===== EventAdmin (optional) See the link:event[EventAdmin section] for details. -=== Blocking policy +==== Blocking policy You can define a policy to filter the cluster events exchanges by the nodes (inbound or outbound). @@ -306,7 +309,10 @@ OUTBOUND: blacklist: [config, cellar*, hazelcast, management] ---- -NB: * is a wildcard. +[NOTE] +==== +* is a wildcard. +==== You have the equivalent command for bundle and config: http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/hazelcast.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/hazelcast.adoc b/manual/src/main/asciidoc/user-guide/hazelcast.adoc index 8f3caa8..d77995e 100644 --- a/manual/src/main/asciidoc/user-guide/hazelcast.adoc +++ b/manual/src/main/asciidoc/user-guide/hazelcast.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Core runtime and Hazelcast +=== Core runtime and Hazelcast Cellar uses Hazelcast as cluster engine. @@ -20,10 +20,11 @@ When you install the cellar feature, a hazelcast feature is automatically instal configuration file. The `etc/hazelcast.xml` configuration file contains all the core configuration, especially: + * the Hazelcast cluster identifiers (group name and password) * network discovery and security configuration -=== Hazelcast cluster identification +==== Hazelcast cluster identification The `<group/>` element in the `etc/hazelcast.xml` defines the identification of the Hazelcast cluster: @@ -36,7 +37,7 @@ The `<group/>` element in the `etc/hazelcast.xml` defines the identification of All Cellar nodes have to use the same name and password (to be part of the same Hazelcast cluster). -=== Network +==== Network The `<network/>` element in the etc/hazelcast.xml contains all the network configuration. @@ -87,9 +88,12 @@ By default, it will bind to all interfaces on the node machine. It's possible to <aws enabled="false"/> ---- -NB: in previous Hazelcast versions (especially the one used by Cellar 2.3.x), it was possible to have multicast and tcp-ip enabled in the same time. +[NOTE] +==== +In previous Hazelcast versions (especially the one used by Cellar 2.3.x), it was possible to have multicast and tcp-ip enabled in the same time. In Hazelcast 3.3.x (the version currently used by Cellar 3.0.x), only one discover mechanism can be enabled at a time. Cellar uses multicast by default (tcp-ip is disabled). If your network or network interface don't support multicast, you have to enable tcp-ip and disable multicast. +==== You can also discover nodes located on a Amazon instance: @@ -123,10 +127,13 @@ Finally, you can also enable security transport on the cluster. Two modes are supported: * SSL: + ---- <ssl enabled="true"/> ---- + * Symmetric Encryption: + ---- <symmetric-encryption enabled="true"> <!-- http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/http-balancer.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/http-balancer.adoc b/manual/src/main/asciidoc/user-guide/http-balancer.adoc index be47c62..a166c32 100644 --- a/manual/src/main/asciidoc/user-guide/http-balancer.adoc +++ b/manual/src/main/asciidoc/user-guide/http-balancer.adoc @@ -12,13 +12,13 @@ // limitations under the License. // -== HTTP Balancer +=== HTTP Balancer Apache Karaf Cellar is able to expose servlets local to a node on the cluster. It means that a client (browser) can use any node in the cluster, proxying the requests to the node actually hosting the servlets. -=== Enable HTTP Balancer +==== Enable HTTP Balancer To enable Cellar HTTP Balancer, you have to first install the `http` and `http-whiteboard` features: @@ -42,7 +42,7 @@ karaf@root()> cluster:feature-install default cellar-http-balancer It's done: the Cellar HTTP Balancer is now enabled. It will expose proxy servlets on nodes. -=== Balancer in action +==== Balancer in action To illustrate Cellar HTTP Balancer in action, you need at least a cluster with two nodes. @@ -100,13 +100,16 @@ karaf@node1()> feature:repo-add cellar 4.0.0 karaf@node1()> feature:install cellar ---- -WARNING: if you run the nodes on a single machine, you have to provision `etc/org.ops4j.pax.web.cfg` configuration file +[NOTE] +==== +If you run the nodes on a single machine, you have to provision `etc/org.ops4j.pax.web.cfg` configuration file containing the `org.osgi.service.http.port property` with a port number different to 8181. For this example, we use the following `etc/org.ops4j.pax.web.cfg` file: ---- org.osgi.service.http.port=8041 ---- +==== On node1, as we installed the `cellar-http-balancer` using `cluster:feature-install` command, it's automatically installed when node2 joins the default cluster group. http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/http-session.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/http-session.adoc b/manual/src/main/asciidoc/user-guide/http-session.adoc index 85e0a4f..442e6a3 100644 --- a/manual/src/main/asciidoc/user-guide/http-session.adoc +++ b/manual/src/main/asciidoc/user-guide/http-session.adoc @@ -12,14 +12,14 @@ // limitations under the License. // -== HTTP Session Replication +=== HTTP Session Replication Apache Karaf Cellar supports replication of the HTTP sessions on the cluster. It means that the same web application deployed on multiple nodes in the cluster will share the same HTTP sessions pool, allowing clients to transparently connect to any node, without loosing any session state. -=== Enable Cluster HTTP Session Replication +==== Enable Cluster HTTP Session Replication In order to be able to be stored on the cluster, all HTTP Sessions used in your web application have to implement Serializable interface. Any non-serializable attribute has to be flagged as transient. @@ -35,7 +35,7 @@ karaf@root()> feature:repo-add cellar karaf@root()> feature:install cellar ---- -=== Web Application Session Replication +==== Web Application Session Replication In order to use HTTP session replication on the cluster, you just have to add a filter in your web application. http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/installation.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/installation.adoc b/manual/src/main/asciidoc/user-guide/installation.adoc index a10b457..a62ee18 100644 --- a/manual/src/main/asciidoc/user-guide/installation.adoc +++ b/manual/src/main/asciidoc/user-guide/installation.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== Installation +=== Installation This chapter describes how to install Apache Karaf Cellar into your existing Karaf based installation. -=== Pre-Installation Requirements +==== Pre-Installation Requirements Cellar is installed on running Karaf instances. @@ -25,7 +25,7 @@ have an internet connection from the Karaf running instance. See link:deploy to how to install and start Cellar. -=== Building from Sources +==== Building from Sources If you intend to build Karaf Cellar from the sources, the requirements are: @@ -38,15 +38,18 @@ If you intend to build Karaf Cellar from the sources, the requirements are: * Java SE Development Kit 1.7.x or greater ([http://www.oracle.com/technetwork/java/javase/]). * Apache Maven 3.0.3 ([http://maven.apache.org/download.html]). -*Note:* Karaf Cellar requires Java 7 to compile, build and run. +[NOTE] +==== +Karaf Cellar requires Java 7 to compile, build and run. +==== -=== Building on Windows +==== Building on Windows This procedure explains how to download and install the source distribution on a Windows system. . From a browser, navigate to http://karaf.apache.org/sub-projects/cellar/download.html . Select the desired distribution. -For a source distribution, the filename will be similar to: {{apache-karaf-cellar-x.y-src.zip}}. +For a source distribution, the filename will be similar to: `apache-karaf-cellar-x.y-src.zip`. . Extract Karaf Cellar from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc. . Build Karaf Cellar using Maven 3.0.3 or greater and Java 7. @@ -64,7 +67,7 @@ mvn Proceed to the link:deploy[Deploy Cellar] section. -=== Building on Unix +==== Building on Unix This procedure explains how to download and install the source distribution on an Unix system. http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/introduction.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/introduction.adoc b/manual/src/main/asciidoc/user-guide/introduction.adoc index f380b9c..17c9bf8 100644 --- a/manual/src/main/asciidoc/user-guide/introduction.adoc +++ b/manual/src/main/asciidoc/user-guide/introduction.adoc @@ -12,9 +12,9 @@ // limitations under the License. // -== Introduction +=== Introduction -=== Use Cases +==== Use Cases The first goal of Karaf Cellar is to synchronize the status of several Karaf instances (named nodes). @@ -28,6 +28,7 @@ The nodes list could be discovered (using unicast or multicast), or "static" def and port list). Cellar is able to synchronize: + * bundles (remote or local) * config * features @@ -38,18 +39,19 @@ The second goal is to provide a Distributed OSGi runtime. It means that using Ce service located on a remote instance. See the link:transport[transport and DOSGi section] of the user guide. Finally, Cellar also provides "runtime clustering" by providing dedicated feature like: + * HTTP load balancing * HTTP sessions replication * log centralization Please, see the sections dedicated to those features. -=== Cross topology +==== Cross topology This is the default Cellar topology. Cellar is installed on all nodes, each node has the same function. It means that you can perform actions on any node, it will be broadcasted to all others nodes. -=== Star topology +==== Star topology In this topology, if Cellar is installed on all nodes, you perform actions only on one specific node (the "manager"). http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/nodes.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/nodes.adoc b/manual/src/main/asciidoc/user-guide/nodes.adoc index b59965b..b0f6558 100644 --- a/manual/src/main/asciidoc/user-guide/nodes.adoc +++ b/manual/src/main/asciidoc/user-guide/nodes.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== Cellar nodes +=== Cellar nodes This chapter describes the Cellar nodes manipulation commands. -=== Nodes identification +==== Nodes identification When you installed the Cellar feature, your Karaf instance became automatically a Cellar cluster node, and hence tries to discover the others Cellar nodes. @@ -33,16 +33,22 @@ x | node2:5702 | node2 | 5702 The starting 'x' indicates that it's the Karaf instance on which you are logged on (the local node). -NB: if you don't see the other nodes there (whereas they should be there), it's probably due to a network issue. +[NOTE] +==== +If you don't see the other nodes there (whereas they should be there), it's probably due to a network issue. By default, Cellar uses multicast to discover the nodes. If your network or network interface don't support multicast, you have to switch to tcp-ip instead of multicast. See link:hazelcast[Core Configuration section] for details. +==== -NB: in Cellar 2.3.x, Cellar used both multicast and tcp-ip by default. Due to a change in Hazelcast, it's no more possible to have both. +[NOTE] +==== +In Cellar 2.3.x, Cellar used both multicast and tcp-ip by default. Due to a change in Hazelcast, it's no more possible to have both. Now, in Cellar 3.0.x, the default configuration is multicast enabled, tcp-ip disabled. See link:hazelcast[Core Configuration section] for details. +==== -=== Testing nodes +==== Testing nodes You can ping a node to test it: @@ -56,14 +62,14 @@ from 4: req=node1:5701 time=7 ms from 5: req=node1:5701 time=12 ms ---- -=== Node Components: listener, producer, handler, consume, and synchronizer +==== Node Components: listener, producer, handler, consume, and synchronizer A Cellar node is actually a set of components, each component is dedicated to a special purpose. The `etc/org.apache.karaf.cellar.node.cfg` configuration file is dedicated to the configuration of the local node. It's where you can control the status of the different components. -=== Synchronizers and sync policy +==== Synchronizers and sync policy A synchronizer is invoked when you: @@ -183,7 +189,7 @@ You can stop or start a specific handler using the `cluster:handler-stop` and `c When a handler is stopped, it means that the node will receive the cluster event, but will not update the local resources dealt by the handler. -=== Listeners +==== Listeners The listeners are listening for local resource change. @@ -194,10 +200,13 @@ To avoid some unexpected behaviors (especially when you stop a node), most of th The listeners status are configured in the `etc/org.apache.karaf.cellar.node.cfg` configuration file. -NB: enabling listeners is at your own risk. We encourage you to use cluster dedicated commands and MBeans to manipulate +[NOTE] +==== +Enabling listeners is at your own risk. We encourage you to use cluster dedicated commands and MBeans to manipulate the resources on the cluster. +==== -== Clustered resources +=== Clustered resources Cellar provides dedicated commands and MBeans for clustered resources. http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/obr.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/obr.adoc b/manual/src/main/asciidoc/user-guide/obr.adoc index 1b072c4..12a4e07 100644 --- a/manual/src/main/asciidoc/user-guide/obr.adoc +++ b/manual/src/main/asciidoc/user-guide/obr.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== OBR Support +=== OBR Support Apache Karaf Cellar is able to "broadcast" OBR actions between cluster nodes of the same group. -=== Enable OBR support +==== Enable OBR support To enable Cellar OBR support, the `cellar-obr` feature must first be installed: @@ -26,7 +26,7 @@ karaf@root()> feature:install cellar-obr The Cellar OBR feature will install the Karaf OBR feature which provides the OBR service (RepositoryAdmin). -=== Register repository URL in a cluster +==== Register repository URL in a cluster The `cluster:obr-add-url` command registers an OBR repository URL (repository.xml) in a cluster group: @@ -74,7 +74,7 @@ When you remove a repository URL from the distributed OBR, the bundles' distribu karaf@root()> cluster:obr-remove-url group http://karaf.cave.host:9090/cave/repo-repository.xml ---- -=== Deploying bundles using the cluster OBR +==== Deploying bundles using the cluster OBR You can deploy a bundle (and that bundle's dependent bundles) using the OBR on a given cluster group: http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/0f49d5dd/manual/src/main/asciidoc/user-guide/transport.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/transport.adoc b/manual/src/main/asciidoc/user-guide/transport.adoc index 8c93e53..8aa87b8 100644 --- a/manual/src/main/asciidoc/user-guide/transport.adoc +++ b/manual/src/main/asciidoc/user-guide/transport.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== DOSGi and Transport +=== DOSGi and Transport DOSGi (Distributed OSGi) enables the distribution of OSGi services across the Cellar nodes.
