Github user aledsage commented on a diff in the pull request:
https://github.com/apache/brooklyn-server/pull/879#discussion_r149336746
--- Diff:
policy/src/main/java/org/apache/brooklyn/policy/ha/ElectPrimaryConfig.java ---
@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.brooklyn.policy.ha;
+
+import org.apache.brooklyn.api.effector.Effector;
+import org.apache.brooklyn.api.entity.Entity;
+import org.apache.brooklyn.api.sensor.AttributeSensor;
+import org.apache.brooklyn.config.ConfigKey;
+import org.apache.brooklyn.core.config.ConfigKeys;
+import org.apache.brooklyn.core.effector.Effectors;
+import org.apache.brooklyn.core.sensor.Sensors;
+import org.apache.brooklyn.util.time.Duration;
+
+public interface ElectPrimaryConfig {
+
+ public enum TargetMode { CHILDREN, MEMBERS, AUTO }
+ public static final ConfigKey<TargetMode> TARGET_MODE =
ConfigKeys.builder(TargetMode.class, "primary.target.mode")
+ .description("where should the policy look for primary candidates;
one of 'children', 'members', or 'auto' (members if it's a group)")
+ .defaultValue(TargetMode.AUTO)
+ .build();
+
+ public enum SelectionMode { FAILOVER, BEST, STRICT }
+ public static final ConfigKey<SelectionMode> SELECTION_MODE =
ConfigKeys.builder(SelectionMode.class, "primary.selection.mode")
+ .description("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)")
+ .defaultValue(SelectionMode.FAILOVER)
+ .build();
+
+ public static final ConfigKey<Duration> BEST_WAIT_TIMEOUT =
ConfigKeys.newDurationConfigKey("primary.stopped.wait.timeout",
+ "if the highest-ranking primary is not starting, the effector will
wait this long for it to be starting before picking a less highly-weighted
primary; "
+ + "default 5s, 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, "
+ + "the short duration is sufficient for the theoretical best to
become waiting where the `primary.starting.wait.timeout` applies",
+ Duration.seconds(5));
+
+ public static final ConfigKey<Duration> BEST_STARTING_WAIT_TIMEOUT =
ConfigKeys.newDurationConfigKey("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",
+ Duration.minutes(5));
+
+ public static final ConfigKey<String> PRIMARY_SENSOR_NAME =
ConfigKeys.newStringConfigKey("primary.sensor.name",
+ "name of sensor to publish, defaulting to 'primary'",
+ PrimaryDefaultSensorsAndEffectors.PRIMARY.getName());
+
+ public static final ConfigKey<String> PRIMARY_WEIGHT_NAME =
ConfigKeys.newStringConfigKey("primary.weight.name",
+ "config key or sensor to scan from candidate nodes to determine
who should be primary",
+ PrimaryDefaultSensorsAndEffectors.PRIMARY_WEIGHT_SENSOR.getName());
+
+ public static final ConfigKey<String> PROMOTE_EFFECTOR_NAME =
ConfigKeys.newStringConfigKey("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)",
--- End diff --
It was not clear that we'll first try to invoke `promote()` on the parent
entity, but if the effector is not defined there then we'll lookup and invoke
the `promote` effector on the `newPrimary`. That needs to be documented
somewhere.
Same for `demote`.
It's also difficult to document it, because the behaviour depends on
whether someone has passed in their own `primary.election.effector` - if they
have, then whether these config keys are used or what they mean is entirely up
to the implementor of that effector!
---
