From b419a10c120870969cb9e2d127580a3dfd79dfad Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@elastic.co>
Date: Mon, 6 Nov 2023 09:12:18 -0600
Subject: [PATCH] [synthetics] Add `locations` and `private_locations`
 lightweight options (#3326)

* add locations and private_locations lightweight options

* address feedback

* apply suggestions from code review

Co-authored-by: DeDe Morton <dede.morton@elastic.co>

* update link

---------

Co-authored-by: DeDe Morton <dede.morton@elastic.co>
(cherry picked from commit a2f6d5e4e304839026ab541f2aa90a049cf192d0)
---
 .../synthetics-configuration.asciidoc         |  5 +-
 .../lightweight-config/common.asciidoc        | 72 +++++++++++++++++++
 2 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc
index 319d9735e9..e33d54895c 100644
--- a/docs/en/observability/synthetics-configuration.asciidoc
+++ b/docs/en/observability/synthetics-configuration.asciidoc
@@ -227,4 +227,7 @@ Then the monitor will resume running according to the defined schedule.
 Using `retestOnFailure` can reduce noise related to transient problems.
 // end::monitor-config-options[]
 
-For information on configuring monitors individually, refer to <<synthetics-monitor-use>>.
+For information on configuring monitors individually, refer to:
+
+* <<synthetics-monitor-use>> for browser monitors 
+* <<synthetics-lightweight>> for lightweight monitors
diff --git a/docs/en/observability/synthetics-reference/lightweight-config/common.asciidoc b/docs/en/observability/synthetics-reference/lightweight-config/common.asciidoc
index b27352540c..9a0477454a 100644
--- a/docs/en/observability/synthetics-reference/lightweight-config/common.asciidoc
+++ b/docs/en/observability/synthetics-reference/lightweight-config/common.asciidoc
@@ -234,6 +234,78 @@ By default, monitors are automatically retested if the monitor goes from "up" to
 retest_on_failure: false
 ----
 
+////////////////////////
+locations
+////////////////////////
+| [[monitor-locations]] *`locations`*
+(list of https://github.com/elastic/synthetics/blob/{synthetics_version}/src/locations/public-locations.ts#L28-L37[`SyntheticsLocationsType`])
+a| Where to deploy the monitor. You can deploy monitors in multiple locations to detect differences in availability and response times across those locations.
+
+To list available locations you can:
+
+* Run the <<elastic-synthetics-locations-command,`elastic-synthetics locations` command>>.
+* Go to *Synthetics* -> *Management* and click *Create monitor*. Locations will be listed in _Locations_.
+
+*Examples*:
+
+[source,yaml]
+----
+locations: ["japan", "india"]
+----
+
+[source,yaml]
+----
+locations:
+  - japan
+  - india
+----
+
+[NOTE]
+====
+This can also be set using
+<<synthetics-configuration-monitor,`monitor.locations` in the project configuration file>>
+or via the CLI using the <<elastic-synthetics-push-command,`--location` flag on `push`>>.
+
+The value defined via the CLI takes precedence over the value defined in the lightweight monitor configuration,
+and the value defined in the lightweight monitor configuration takes precedence over the value defined in _project_ configuration file.
+====
+
+////////////////////////
+private_locations
+////////////////////////
+| [[monitor-private_locations]] *`private_locations`*
+(list of <<synthetics-lightweight-data-string,string>>s)
+a| The <<synthetics-private-location,{private-location}s>> to which the monitors will be deployed. These {private-location}s refer to locations hosted and managed by you, whereas  `locations` are hosted by Elastic. You can specify a {private-location} using the location's name.
+
+To list available {private-location}s you can:
+
+* Run the <<elastic-synthetics-locations-command,`elastic-synthetics locations` command>> and specify the {kib} URL of the deployment. This will fetch all available private locations associated with the deployment.
+* Go to *Synthetics* -> *Management* and click *Create monitor*. {private-location}s will be listed in _Locations_.
+
+*Examples*:
+
+[source,yaml]
+----
+private_locations: ["Private Location 1", "Private Location 2"]
+----
+
+[source,yaml]
+----
+private_locations:
+  - Private Location 1
+  - Private Location 2
+----
+
+[NOTE]
+====
+This can also be set using
+<<synthetics-configuration-monitor,`monitor.privateLocations` in the project configuration file>>
+or via the CLI using the <<elastic-synthetics-push-command,`--privateLocations` flag on `push`>>.
+
+The value defined via the CLI takes precedence over the value defined in the lightweight monitor configuration,
+and the value defined in the lightweight monitor configuration takes precedence over the value defined in _project_ configuration file.
+====
+
 |===
 
 :!hardbreaks-option: