Repository: karaf-cellar Updated Branches: refs/heads/cellar-3.0.x 658a032f3 -> e8aeca8cc
Use article format 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/e8aeca8c Tree: http://git-wip-us.apache.org/repos/asf/karaf-cellar/tree/e8aeca8c Diff: http://git-wip-us.apache.org/repos/asf/karaf-cellar/diff/e8aeca8c Branch: refs/heads/cellar-3.0.x Commit: e8aeca8cc079ceecf48e2ab6f03fb4ada86a252b Parents: 658a032 Author: Jean-Baptiste Onofré <[email protected]> Authored: Mon Jan 4 16:59:34 2016 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Mon Jan 4 16:59:34 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 | 4 +-- .../architecture-guide/supported_events.adoc | 2 +- manual/src/main/asciidoc/index.adoc | 6 ++-- manual/src/main/asciidoc/user-guide/cloud.adoc | 23 ++++++++------- 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 | 24 ++++++++------- .../src/main/asciidoc/user-guide/hazelcast.adoc | 16 +++++++--- .../main/asciidoc/user-guide/installation.adoc | 31 +++++++++++--------- .../main/asciidoc/user-guide/introduction.adoc | 12 ++++---- manual/src/main/asciidoc/user-guide/nodes.adoc | 31 +++++++++++++------- manual/src/main/asciidoc/user-guide/obr.adoc | 8 ++--- .../src/main/asciidoc/user-guide/transport.adoc | 2 +- 17 files changed, 107 insertions(+), 80 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/e8aeca8c/manual/pom.xml ---------------------------------------------------------------------- diff --git a/manual/pom.xml b/manual/pom.xml index e2d7d3e..7495279 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/e8aeca8c/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 c42636e..266a949 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. Each command http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/e8aeca8c/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 a9b04e2..5576984 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: @@ -25,7 +25,7 @@ The design works with the following entities: * *Command* A special type of event that is linked to a list of events that represent the outcome of the command. * *Result* 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 paradigm 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/e8aeca8c/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/e8aeca8c/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 2127e27..da312ef 100644 --- a/manual/src/main/asciidoc/architecture-guide/overview.adoc +++ b/manual/src/main/asciidoc/architecture-guide/overview.adoc @@ -12,13 +12,13 @@ // 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) and a topic which is used to exchange events with the rest of the group nodes. -image::images/architecture.png[] +image::architecture.png[] Each group comes with a configuration, which defines which events are to be broadcasted and which are not. Whenever a local change occurs to a node, the node will read the setup information of all the http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/e8aeca8c/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/e8aeca8c/manual/src/main/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc index 942ea2b..8738f1d 100644 --- a/manual/src/main/asciidoc/index.adoc +++ b/manual/src/main/asciidoc/index.adoc @@ -15,14 +15,14 @@ Apache Karaf Cellar 3.x - Documentation ======================================= Apache Software Foundation -:doctype: book +:doctype: article :toc: left :toclevels: 3 :toc-position: left :toc-title: Apache Karaf Cellar 3.x - Documentation :numbered: -= User Guide +== User Guide include::user-guide/introduction.adoc[] @@ -44,7 +44,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/e8aeca8c/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 b8e895b..9197805 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,12 +62,15 @@ container=cellar validity=360000 ---- -NB: you can find the cloud providers supported by jclouds here http://repo1.maven.org/maven2/org/apache/jclouds/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. It handles scheduling onto nodes in a compute cluster and actively manages workloads to ensure that their state matches @@ -81,7 +84,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`. @@ -93,7 +96,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/e8aeca8c/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 01122f6..727f4b1 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. @@ -47,7 +47,7 @@ cellar-cloud | 3.0.3 | | karaf-cellar-3.0.3 | Cloud cellar-webconsole | 3.0.3 | | karaf-cellar-3.0.3 | Cellar plugin for Karaf WebConsole ---- -=== Starting Cellar +==== Starting Cellar To start Cellar in your Karaf instance, you only need to install the Cellar feature: @@ -74,7 +74,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/e8aeca8c/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 53a503b..0f3528e 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/e8aeca8c/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 33cfebc..4cc8ff6 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 @@ -135,7 +136,7 @@ The listener listens for the following local feature changes: * install feature * uninstall feature -==== Bundles +===== Bundles Cellar can manipulate bundles on cluster groups. @@ -195,7 +196,7 @@ The bundle listener listens the following local bundle changes: * stop bundle * uninstall bundle -==== Configurations +===== Configurations Cellar can manipulate configurations on cluster groups. @@ -280,15 +281,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). @@ -309,7 +310,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/e8aeca8c/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 a2f7e06..181c64e 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: @@ -121,11 +125,15 @@ But you can specify an interface: 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/e8aeca8c/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 7ee21e1..8792293 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,17 +38,20 @@ 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. -1. From a browser, navigate to link::http://karaf.apache.org/sub-projects/cellar/download.html. -2. Select the desired distribution. +. From a browser, navigate to link::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`. -3. 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. -4. Build Karaf Cellar using Maven 3.0.3 or greater and Java 6. +. 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 6. The recommended method of building Karaf Cellar is the following: ---- @@ -61,14 +64,14 @@ where `[cellar_install_dir]` is the directory in which Karaf Cellar was uncompre mvn ---- -=== Building on Unix +==== Building on Unix This procedure explains how to download and install the source distribution on an Unix system. -1. From a browser, navigate to link::http://karaf.apache.org/sub-projects/cellar/download.html. -2. Select the desired distribution. +. From a browser, navigate to link::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.tar.gz`. -3. Extract the files from the tarball file into a directory of your choice. For example: +. Extract the files from the tarball file into a directory of your choice. For example: ---- gunzip apache-karaf-cellar-x.y-src.tar.gz @@ -76,7 +79,7 @@ tar xvf apache-karaf-cellar-x.y-src.tar ---- Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc. -4. Build Karaf using Maven: +. Build Karaf using Maven: The preferred method of building Karaf is the following: ---- http://git-wip-us.apache.org/repos/asf/karaf-cellar/blob/e8aeca8c/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 f53668e..0ac9fc0 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 -=== Karaf Cellar use cases +==== Karaf Cellar use cases The first purpose of Cellar is to synchronize the state of several Karaf instances (named nodes). @@ -47,17 +47,17 @@ Finally, Cellar also provides "runtime clustering" by providing dedicated featur Please, see the sections dedicated to those features. -=== Cross topology +==== Cross topology -image::images/cross_topology.jpg[] +image::cross_topology.jpg[] This is the default Cellar topology. Cellar is installed on every 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 -image::images/star_topology.jpg[] +image::star_topology.jpg[] 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/e8aeca8c/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 60fb0a2..213955a 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,13 +33,19 @@ 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. By default, Cellar uses multicast to discover the nodes. +[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 [Core Configuration|hazelcast] 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. Now, in Cellar 3.0.x, the default +[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 [Core Configuration|hazelcast] for details. +==== -=== Testing nodes +==== Testing nodes You can ping a node to test it: @@ -53,14 +59,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: @@ -109,7 +115,7 @@ It's also possible to sync only a resource using: or a given cluster group using the -g (--group) option. -=== Producer, consumer, and handlers +==== Producer, consumer, and handlers To notify the other nodes in the cluster, Cellar produces a cluster event. @@ -180,7 +186,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. @@ -191,10 +197,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/e8aeca8c/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 6ec9f65..3906789 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/e8aeca8c/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 38cd2ce..f0222a1 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.
