You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by dr...@apache.org on 2017/11/14 10:35:55 UTC

[1/5] brooklyn-docs git commit: document the new ElectPrimaryPolicy and related items

Repository: brooklyn-docs
Updated Branches:
  refs/heads/master 23b26ca65 -> 7402753b1


document the new ElectPrimaryPolicy and related items


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/20e497bf
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/20e497bf
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/20e497bf

Branch: refs/heads/master
Commit: 20e497bf34971e72a97ee8899b55b90e4d4c7880
Parents: ba27cf1
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Mon Nov 6 14:39:07 2017 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Mon Nov 6 14:39:07 2017 +0000

----------------------------------------------------------------------
 guide/blueprints/_elect-primary-policies.md | 149 +++++++++++++++++++++++
 guide/blueprints/policies.md                |  16 ++-
 2 files changed, 163 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/20e497bf/guide/blueprints/_elect-primary-policies.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/_elect-primary-policies.md b/guide/blueprints/_elect-primary-policies.md
new file mode 100644
index 0000000..603c331
--- /dev/null
+++ b/guide/blueprints/_elect-primary-policies.md
@@ -0,0 +1,149 @@
+
+There are a collection of policies, enrichers, and effectors to assist with common
+failover scenarios and more general anything which wants a primary elected and
+re-elected.
+
+These can be used for:
+
+* Nominating one child among many to be noted as a primary via a sensor (simply add the `ElectPrimaryPolicy`)
+* Allowing preferences for such children to be specified  (via `ha.primary.weight`)
+* Causing the primary to change if the current primary goes down or away
+* Causing `promote` and `demote` effectors to be invoked on the appropriate nodes when the primary is elected/changed
+  (with the parent reset to `STARTING` while this occurs)
+* Mirroring sensors and optionally effectors from the primary to the parent
+
+A simple example is as follows, deploying two `item` entities with one designated as primary
+and its `main.uri` sensor published at the root. If "Preferred Item" fails, "Failover Item"
+will be become the primary. Any `demote` effector on "Preferred Item" and any `promote` effector
+on "Failover Item" will be invoked on failover.
+
+```
+brooklyn.policies:
+- type: org.apache.brooklyn.policy.ha.ElectPrimaryPolicy
+  brooklyn.config:
+    # `best` will cause failback to occur automatically when possible; could use `failover` instead
+    primary.selection.mode: best
+    propagate.primary.sensors: [ main.uri ]
+
+brooklyn.enrichers:
+- # this enricher will cause the parent to report as failed if there is no primary
+  type: org.apache.brooklyn.policy.ha.PrimaryRunningEnricher
+
+services:
+- type: item
+  name: Preferred Item
+  brooklyn.config:
+    ha.primary.weight: 1
+- type: item
+  name: Failover Item
+```
+
+
+#### ElectPrimary Policy
+
+- org.apache.brooklyn.policy.ha.ElectPrimaryPolicy
+
+The ElectPrimaryPolicy acts to keep exactly one of its children or members as primary, promoting and demoting them when required.
+
+A simple use case is where we have two children, call them North and South, and we wish for North to be primary.  If North fails, however, we want to promote and fail over to South.  This can be done by:
+
+* adding this policy at the parent
+* setting ` ha.primary.weight` on North
+* optionally defining `promote` on North and South (if action is required there to promote it)
+* observing the `primary` sensor to see which is primary
+* optionally setting `propagate.primary.sensor: main.uri` to publish `main.uri` from whichever of North or South is active
+* optionally setting `primary.selection.mode: best` to switch back to North if it comes back online
+
+The policy works by listening for service-up changes in the target pool (children or members) and listening for `ha.primary.weight` sensor values from those elements.  On any change, it invokes an effector to perform the primary election.  By default, the effector invoked is `electPrimary`, but this can be changed with the `primary.election.effector` config key.  If this effector does not exist, the policy will add a default behaviour using `ElectPrimaryEffector`.  Details of the election are described in that effector, but to summarize, it will find an appropriate primary from the target pool and publish a sensor indicating who the new primary is.  Optionally it can invoke `promote` and `demote` on the relevant entities.
+
+All the `primary.*` parameters accepted by that effector can be defined on the policy and will be passed to the effector, along with an `event` parameter indicating the sensor which triggered the election.
+
+The policy also accepts a `propagate.primary.sensors` list of strings or sensors.
+If present, this will add the `PropagatePrimaryEnricher` enricher with those sensors set to
+be propagated (but not effectors).
+For more sophisticated configuration, that enricher can be added and configured directly instead.  
+
+If no quorum.up or quorum.running is set on the entity, both will be set to a constant 1.
+
+
+#### ElectPrimary Effector
+
+- org.apache.brooklyn.policy.ha.ElectPrimaryEffector
+
+This effector will scan candidates among children or members to determine which should be noted as "primary".  
+The primary is selected from service-up candidates based on a numeric weight as a sensor or config on the candidates 
+(`ha.primary.weight`, unless overridden), with higher weights being preferred and negative indicating not permitted.  
+In the case of ties, or a new candidate emerging with a weight higher than a current healthy primary, 
+behaviour can be configured with `primary.selection.mode`.
+
+If there is a primary and it is unchanged, the effector will end.
+
+If a new primary is detected, the effector will:
+
+* set the local entity to the STARTING state
+
+* clear any "primary-election" problem
+
+* publish the new primary in a sensor called `primary` (or the sensor set in `primary.sensor.name`)
+
+* set service up true
+
+* cancel any other ongoing promote calls, and if there is an ongoing demote call on the entity being promoted, cancel that also
+
+* in parallel
+
+    * invoke `promote` (or the effector called `primary.promote.effector.name`) on the local entity or the entity being promoted
+    
+    * invoke `demote` (or the effector called `primary.promote.effector.name`) on the local entity or the entity being demoted, if an entity is being demoted
+    
+* set the local entity to the RUNNING state
+
+
+If no primary can be found, the effector will:
+
+* add a "primary-election" problem so that service state logic, if applicable, will know that the entity is unhealthy
+
+* demote any old primary
+
+* set service up false
+
+* if the local entity is expected to be RUNNING, it will set actual state to ON_FIRE
+
+* if the local entity has no expectation, it will set actual state to STOPPED
+
+
+More details of behaviour in edge conditions can be seen and set via the parameters on this effector.
+
+* `primary.target.mode`:  where should the policy look for primary candidates; one of 'children', 'members', or 'auto' (members if it has members and no children)
+
+* `primary.selection.mode`:  under what circumstances should the primary change:  `failover` to change only if an existing primary is unhealthy, `best` to change so one with the highest weight is always selected, or `strict` to act as `best` but fail if several advertise the highest weight (for use when the weight sensor is updated by the nodes and should tell us unambiguously who was elected)
+
+* `primary.stopped.wait.timeout`:  if the highest-ranking primary is stopped (but not failed), the effector will wait this long for it to be starting before picking a less highly-weighted primary; default 3s, typically long enough to avoid races where multiple children are started concurrently but they complete extremely quickly and one completes before a better one starts
+
+* `primary.starting.wait.timeout`:  if the highest-ranking primary is starting, the effector will wait this long for it to be running before picking a less highly-weighted primary (or in the case of `strict` before failing if there are ties); default 5m, typically long enough to avoid races where multiple children are started and a sub-optimal one comes online before the best one
+
+* `primary.sensor.name`:  name to publish, defaulting to `primary`
+
+* `primary.weight.name`:  config key or sensor to scan from candidate nodes to determine who should be primary
+
+* `primary.promote.effector.name`: effector to invoke on promotion, default `promote` and with no error if not present (but if set explicitly it will cause an error if not present)
+
+* `primary.demote.effector.name`: effector to invoke on demotion, default `demote` and with no error if not present (but if set explicitly it will cause an error if not present)
+
+
+#### PrimaryRunning Enricher
+
+- org.apache.brooklyn.policy.ha.PrimaryRunningEnricher
+
+This adds service not-up and problems entries if the primary is not running, 
+so that the parent will only be up/healthy if there is a healthy primary.
+
+
+#### PropagatePrimary Enricher
+
+- org.apache.brooklyn.policy.ha.PropagatePrimaryEnricher
+
+This allows sensors and effectors from the primary to be available at the parent.
+This takes the same config as `Propagator`, as well as `propagate.effectors` (true or false)
+for whether effectors should be propagated.
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/20e497bf/guide/blueprints/policies.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/policies.md b/guide/blueprints/policies.md
index 486b356..33fcde3 100644
--- a/guide/blueprints/policies.md
+++ b/guide/blueprints/policies.md
@@ -68,7 +68,7 @@ brooklyn.policies:
     failOnRecurringFailuresInThisDuration: 5m
 ```
 
-Typically this is used in conjunction with the FailureDetector enricher to emit the trigger sensor.
+Typically this is used in conjunction with the ServiceFailureDetector enricher to emit the trigger sensor.
 The [introduction to policies]({{book.path.docs}}/start/policies.md) shows a worked 
 example of these working together.
 
@@ -78,11 +78,18 @@ example of these working together.
 - org.apache.brooklyn.policy.ha.ServiceReplacer
 
 The ServiceReplacer attaches to a DynamicCluster and replaces a failed member in response to 
-`ha.entityFailed` (or other configurable sensor).  
+`ha.entityFailed` (or other configurable sensor) as typically emitted by the ServiceFailureDetector enricher.  
 The [introduction to policies]({{book.path.docs}}/start/policies.md) shows a worked 
 example of this policy in use.
 
 
+#### ServiceFailureDetector Enricher
+
+- org.apache.brooklyn.policy.ha.ServiceFailureDetector
+
+TODO
+
+
 #### SshMachineFailureDetector Policy
 
 - org.apache.brooklyn.policy.ha.SshMachineFailureDetector
@@ -97,6 +104,11 @@ The SshMachineFailureDetector is an HA policy for monitoring an SshMachine, emit
 The ConnectionFailureDetector is an HA policy for monitoring an http connection, emitting an event if the connection is lost/restored.
 
 
+### Primary Election / Failover Policies
+
+{% include _elect-primary-policies.md %}
+
+
 ### Optimization Policies
 
 #### PeriodicEffector Policy


[2/5] brooklyn-docs git commit: address PR comments

Posted by dr...@apache.org.
address PR comments


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/b48dae67
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/b48dae67
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/b48dae67

Branch: refs/heads/master
Commit: b48dae6759982140d77b76f828013779f73868c6
Parents: 20e497b
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Mon Nov 6 23:41:10 2017 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Mon Nov 6 23:41:10 2017 +0000

----------------------------------------------------------------------
 guide/blueprints/_elect-primary-policies.md | 7 +++----
 guide/blueprints/policies.md                | 5 ++++-
 2 files changed, 7 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b48dae67/guide/blueprints/_elect-primary-policies.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/_elect-primary-policies.md b/guide/blueprints/_elect-primary-policies.md
index 603c331..b8b94fe 100644
--- a/guide/blueprints/_elect-primary-policies.md
+++ b/guide/blueprints/_elect-primary-policies.md
@@ -1,7 +1,6 @@
 
 There are a collection of policies, enrichers, and effectors to assist with common
-failover scenarios and more general anything which wants a primary elected and
-re-elected.
+failover scenarios and more generally anything which requires the election and re-election of a primary member.
 
 These can be used for:
 
@@ -48,7 +47,7 @@ The ElectPrimaryPolicy acts to keep exactly one of its children or members as pr
 A simple use case is where we have two children, call them North and South, and we wish for North to be primary.  If North fails, however, we want to promote and fail over to South.  This can be done by:
 
 * adding this policy at the parent
-* setting ` ha.primary.weight` on North
+* setting `ha.primary.weight` on North
 * optionally defining `promote` on North and South (if action is required there to promote it)
 * observing the `primary` sensor to see which is primary
 * optionally setting `propagate.primary.sensor: main.uri` to publish `main.uri` from whichever of North or South is active
@@ -63,7 +62,7 @@ If present, this will add the `PropagatePrimaryEnricher` enricher with those sen
 be propagated (but not effectors).
 For more sophisticated configuration, that enricher can be added and configured directly instead.  
 
-If no quorum.up or quorum.running is set on the entity, both will be set to a constant 1.
+If no `quorum.up` or `quorum.running` is set on the entity, both will be set to a constant 1.
 
 
 #### ElectPrimary Effector

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b48dae67/guide/blueprints/policies.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/policies.md b/guide/blueprints/policies.md
index 33fcde3..f34fdf3 100644
--- a/guide/blueprints/policies.md
+++ b/guide/blueprints/policies.md
@@ -87,7 +87,10 @@ example of this policy in use.
 
 - org.apache.brooklyn.policy.ha.ServiceFailureDetector
 
-TODO
+The ServiceFailureDetector enricher detects problems and fires an `ha.entityFailed` (or other configurable sensor)
+for use by ServiceRestarter and ServiceReplacer.
+The [introduction to policies]({{book.path.docs}}/start/policies.md) shows a worked 
+example of this in use.
 
 
 #### SshMachineFailureDetector Policy


[4/5] brooklyn-docs git commit: add file type after triple backtick

Posted by dr...@apache.org.
add file type after triple backtick


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/9f44cec3
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/9f44cec3
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/9f44cec3

Branch: refs/heads/master
Commit: 9f44cec3906a2cb5f5a174ac5e16a1fecefbb44c
Parents: fc9c81a
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Fri Nov 10 11:24:01 2017 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Fri Nov 10 11:24:01 2017 +0000

----------------------------------------------------------------------
 guide/blueprints/_elect-primary-policies.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/9f44cec3/guide/blueprints/_elect-primary-policies.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/_elect-primary-policies.md b/guide/blueprints/_elect-primary-policies.md
index 09bcefe..6ceccfc 100644
--- a/guide/blueprints/_elect-primary-policies.md
+++ b/guide/blueprints/_elect-primary-policies.md
@@ -16,7 +16,7 @@ and its `main.uri` sensor published at the root. If "Preferred Item" fails, "Fai
 will be become the primary. Any `demote` effector on "Preferred Item" and any `promote` effector
 on "Failover Item" will be invoked on failover.
 
-```
+```yaml
 brooklyn.policies:
 - type: org.apache.brooklyn.policy.failover.ElectPrimaryPolicy
   brooklyn.config:


[5/5] brooklyn-docs git commit: This closes #231

Posted by dr...@apache.org.
This closes #231


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/7402753b
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/7402753b
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/7402753b

Branch: refs/heads/master
Commit: 7402753b1f18c080b8578665ac8a5bfe0c706f65
Parents: 23b26ca 9f44cec
Author: Duncan Godwin <dr...@googlemail.com>
Authored: Tue Nov 14 10:35:48 2017 +0000
Committer: Duncan Godwin <dr...@googlemail.com>
Committed: Tue Nov 14 10:35:48 2017 +0000

----------------------------------------------------------------------
 guide/blueprints/_elect-primary-policies.md | 146 +++++++++++++++++++++++
 guide/blueprints/policies.md                |  19 ++-
 2 files changed, 163 insertions(+), 2 deletions(-)
----------------------------------------------------------------------



[3/5] brooklyn-docs git commit: update for simpler primary propagator

Posted by dr...@apache.org.
update for simpler primary propagator


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/fc9c81a4
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/fc9c81a4
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/fc9c81a4

Branch: refs/heads/master
Commit: fc9c81a48127ef763b45e62b25d2f7b124dbd1bb
Parents: b48dae6
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Thu Nov 9 16:00:11 2017 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Thu Nov 9 16:00:11 2017 +0000

----------------------------------------------------------------------
 guide/blueprints/_elect-primary-policies.md | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/fc9c81a4/guide/blueprints/_elect-primary-policies.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/_elect-primary-policies.md b/guide/blueprints/_elect-primary-policies.md
index b8b94fe..09bcefe 100644
--- a/guide/blueprints/_elect-primary-policies.md
+++ b/guide/blueprints/_elect-primary-policies.md
@@ -18,7 +18,7 @@ on "Failover Item" will be invoked on failover.
 
 ```
 brooklyn.policies:
-- type: org.apache.brooklyn.policy.ha.ElectPrimaryPolicy
+- type: org.apache.brooklyn.policy.failover.ElectPrimaryPolicy
   brooklyn.config:
     # `best` will cause failback to occur automatically when possible; could use `failover` instead
     primary.selection.mode: best
@@ -26,7 +26,7 @@ brooklyn.policies:
 
 brooklyn.enrichers:
 - # this enricher will cause the parent to report as failed if there is no primary
-  type: org.apache.brooklyn.policy.ha.PrimaryRunningEnricher
+  type: org.apache.brooklyn.policy.failover.PrimaryRunningEnricher
 
 services:
 - type: item
@@ -40,7 +40,7 @@ services:
 
 #### ElectPrimary Policy
 
-- org.apache.brooklyn.policy.ha.ElectPrimaryPolicy
+- org.apache.brooklyn.policy.failover.ElectPrimaryPolicy
 
 The ElectPrimaryPolicy acts to keep exactly one of its children or members as primary, promoting and demoting them when required.
 
@@ -59,15 +59,14 @@ All the `primary.*` parameters accepted by that effector can be defined on the p
 
 The policy also accepts a `propagate.primary.sensors` list of strings or sensors.
 If present, this will add the `PropagatePrimaryEnricher` enricher with those sensors set to
-be propagated (but not effectors).
-For more sophisticated configuration, that enricher can be added and configured directly instead.  
+be propagated.  
 
 If no `quorum.up` or `quorum.running` is set on the entity, both will be set to a constant 1.
 
 
 #### ElectPrimary Effector
 
-- org.apache.brooklyn.policy.ha.ElectPrimaryEffector
+- org.apache.brooklyn.policy.failover.ElectPrimaryEffector
 
 This effector will scan candidates among children or members to determine which should be noted as "primary".  
 The primary is selected from service-up candidates based on a numeric weight as a sensor or config on the candidates 
@@ -142,7 +141,6 @@ so that the parent will only be up/healthy if there is a healthy primary.
 
 - org.apache.brooklyn.policy.ha.PropagatePrimaryEnricher
 
-This allows sensors and effectors from the primary to be available at the parent.
-This takes the same config as `Propagator`, as well as `propagate.effectors` (true or false)
-for whether effectors should be propagated.
+This allows selected sensors from the primary to be available at the parent.
+As the primary changes, the indicated sensors will be updated to reflect the values from the new primaries.