[Heartbeat] Make run_once syntax a boolean

Fixes elastic#28437. This is an improvement over
elastic#25972 which had a more complicated
config interface.

heartbeat/_meta/config/beat.yml.tmpl

@@ -37,17 +37,8 @@ heartbeat.monitors:
   # Name of corresponding APM service, if Elastic APM is in use for the monitored service.
   #service.name: my-apm-service-name
 
-# Experimental: Configure monitors that run exactly once.
-# If enabled, heartbeat.monitors will be ignored
-# Heartbeat will run these monitors once then exit.
-#heartbeat.run_once:
-#- type: http
-  #id: my-monitor
-  #name: My Monitor
-  #urls: ["http://localhost:9200"]
-  # NOTE: you must still provide the schedule field! Heartbeat
-  # Uses this to determine the contents of the monitor.timespan field
-  #schedule: '@every 10s'
+# Experimental: Set this to true to run heartbeat monitors exactly once at startup
+#heartbeat.run_once: true
 
 {{header "Elasticsearch template setting"}}
 

heartbeat/beater/heartbeat.go

@@ -89,7 +89,7 @@ func (bt *Heartbeat) Run(b *beat.Beat) error {
 	groups, _ := syscall.Getgroups()
 	logp.Info("Effective user/group ids: %d/%d, with groups: %v", syscall.Geteuid(), syscall.Getegid(), groups)
 
-	if bt.config.RunOnce != nil {
+	if bt.config.RunOnce {
 		err := bt.runRunOnce(b)
 		if err != nil {
 			return err
@@ -141,7 +141,6 @@ func (bt *Heartbeat) Run(b *beat.Beat) error {
 // runRunOnce runs the given config then exits immediately after any queued events have been sent to ES
 func (bt *Heartbeat) runRunOnce(b *beat.Beat) error {
 	logp.Info("Starting run_once run. This is an experimental feature and may be changed or removed in the future!")
-	cfgs := bt.config.RunOnce
 
 	publishClient, err := core.NewSyncClient(logp.NewLogger("run_once mode"), b.Publisher, beat.ClientConfig{})
 	if err != nil {
@@ -150,7 +149,7 @@ func (bt *Heartbeat) runRunOnce(b *beat.Beat) error {
 	defer publishClient.Close()
 
 	wg := &sync.WaitGroup{}
-	for _, cfg := range cfgs {
+	for _, cfg := range bt.config.Monitors {
 		err := runRunOnceSingleConfig(cfg, publishClient, wg)
 		if err != nil {
 			logp.Warn("error running run_once config: %s", err)

heartbeat/config/config.go

@@ -27,7 +27,7 @@ import (
 
 // Config defines the structure of heartbeat.yml.
 type Config struct {
-	RunOnce         []*common.Config     `config:"run_once"`
+	RunOnce         bool                 `config:"run_once"`
 	Monitors        []*common.Config     `config:"monitors"`
 	ConfigMonitors  *common.Config       `config:"config.monitors"`
 	Scheduler       Scheduler            `config:"scheduler"`

heartbeat/docs/heartbeat-options.asciidoc

@@ -114,32 +114,17 @@ include::monitors/monitor-browser.asciidoc[]
 [[run-once-mode]]
 === Run Once Mode (Experimental)
 
-You can configure {beatname_uc} run monitors exactly once then exit, bypassing the scheduler. This is referred to as running {beatname_uc} in "run once" mode. This is an experimental feature
-and is subject to change.
+You can configure {beatname_uc} run monitors exactly once then exit, bypassing the scheduler. This is referred to as running {beatname_uc} in 
+"run once" mode by setting `heartbeat.run_once: true`. All {beatname_uc} monitors will ignore their schedules and run exactly once at startup.
+This is an experimental feature and is subject to change. 
+
+Note, the `schedule` field is still required and is used by {beatname_uc} to set the expectation around when
+the next run will occur. That duration is encoded in the `monitor.timespan` field in the {beatname_uc} output.
 
 [source,yaml]
 ----------------------------------------------------------------------
 # heartbeat.yml
-heartbeat.run_once:
-- type: icmp
-  id: ping-myhost
-  name: My Host Ping
-  hosts: ["myhost"]
-  # Note that schedule is still needed to inform heartbeat when the next
-  # expected check is to be run. This is needed to populate the monitor.timespan field used by the Uptime app.
-  schedule: '@every 5s'
-- type: tcp
-  id: myhost-tcp-echo
-  name: My Host TCP Echo
-  hosts: ["myhost:777"]  # default TCP Echo Protocol
-  check.send: "Check"
-  check.receive: "Check"
-  schedule: '@every 5s'
-- type: http
-  id: service-status
-  name: Service Status
-  service.name: my-apm-service-name
-  hosts: ["http://localhost:80/service/status"]
-  check.response.status: [200]
-  schedule: '@every 5s'
+heartbeat.run_once: true
+heartbeat.monitors:
+# your monitor config here...
 ----------------------------------------------------------------------

heartbeat/heartbeat.yml

@@ -37,17 +37,8 @@ heartbeat.monitors:
   # Name of corresponding APM service, if Elastic APM is in use for the monitored service.
   #service.name: my-apm-service-name
 
-# Experimental: Configure monitors that run exactly once.
-# If enabled, heartbeat.monitors will be ignored
-# Heartbeat will run these monitors once then exit.
-#heartbeat.run_once:
-#- type: http
-  #id: my-monitor
-  #name: My Monitor
-  #urls: ["http://localhost:9200"]
-  # NOTE: you must still provide the schedule field! Heartbeat
-  # Uses this to determine the contents of the monitor.timespan field
-  #schedule: '@every 10s'
+# Experimental: Set this to true to run heartbeat monitors exactly once at startup
+#heartbeat.run_once: true
 
 # ======================= Elasticsearch template setting =======================
 

x-pack/heartbeat/heartbeat.yml

@@ -37,17 +37,8 @@ heartbeat.monitors:
   # Name of corresponding APM service, if Elastic APM is in use for the monitored service.
   #service.name: my-apm-service-name
 
-# Experimental: Configure monitors that run exactly once.
-# If enabled, heartbeat.monitors will be ignored
-# Heartbeat will run these monitors once then exit.
-#heartbeat.run_once:
-#- type: http
-  #id: my-monitor
-  #name: My Monitor
-  #urls: ["http://localhost:9200"]
-  # NOTE: you must still provide the schedule field! Heartbeat
-  # Uses this to determine the contents of the monitor.timespan field
-  #schedule: '@every 10s'
+# Experimental: Set this to true to run heartbeat monitors exactly once at startup
+#heartbeat.run_once: true
 
 # ======================= Elasticsearch template setting =======================