[Synthetics] Document how to disable Elastic managed locations (#3305)

* first attempt

* more context

* clean up

* address feedback

docs/en/observability/synthetics-command-reference.asciidoc

@@ -232,3 +232,9 @@ The {kib} URL for the deployment from which to fetch all available public and {p
 
 `--auth <string>`::
 API key used for {kibana-ref}/api-keys.html[{kib} authentication].
+
+NOTE: If an administrator has disabled Elastic managed locations for the role you are assigned
+and you do _not_ include `--url` and `--auth`, all global locations managed by Elastic will be listed.
+However, you will not be able to push to these locations with your API key and will see an error:
+_You don't have permission to use Elastic managed global locations_. For more details, refer to the
+<<synthetics-troubleshooting-public-locations-disabled,troubleshooting docs>>.

docs/en/observability/synthetics-get-started-project.asciidoc

@@ -60,7 +60,7 @@ For more details, refer to <<synthetics-traffic-filters>>.
 [[synthetics-get-started-project-init]]
 = Create a project
 
-Start by creating your first project. Run the command below to create a new 
+Start by creating your first project. Run the command below to create a new
 project named `projects-test` in the current directory.
 
 [source,sh]
@@ -78,14 +78,26 @@ for authentication with your {stack}:
 .. Switch to the **Project API Keys** tab.
 .. Click **Generate Project API key**.
 +
-IMPORTANT: To generate a Project API key, you must be logged in as a user with the privileges
+[IMPORTANT]
+====
+To generate a Project API key, you must be logged in as a user with the privileges
 described in <<synthetics-role-write>>.
+====
 +
 [role="screenshot"]
 image::images/synthetics-monitor-management-api-key.png[Project API Keys tab in Synthetics settings]
++
+[NOTE]
+====
+To use an API key to push to Elastic's global managed testing infrastructure,
+the _Elastic managed locations enabled_ toggle must be on when generating the API key.
+If the _Elastic managed locations enabled_ toggle is disabled, an administrator has restricted
+access to Elastic's global managed testing infrastructure.
+Read more in the <<disable-managed-locations,writer role documentation>>.
+====
 
 . Set the `SYNTHETICS_API_KEY` environment variable in your terminal.
-  You will most likely want to set this permanently. 
+  You will most likely want to set this permanently.
   This is done differently in https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2#saving-changes-to-environment-variables[Powershell] and https://unix.stackexchange.com/a/117470[Bash].
 
 NOTE: If you are pushing to a <<synthetics-private-location,{private-location}>>, you must use an API key generated in 8.4 or higher.
@@ -95,13 +107,23 @@ Then, take a look at key files and directories inside your project:
 * `journeys` is where you'll add `.ts` and `.js` files defining your browser monitors. When you create a new project, this directory will contain files defining sample monitors.
 * `lightweight` is where you'll add `.yaml` files defining your lightweight monitors.  When you create a new project, this directory will contain a file defining sample monitors.
 * `synthetics.config.ts` contains settings for your project. When you create a new project, it will contain some basic configuration options that you can customize later.
++
+[NOTE]
+====
+The `synthetics.config.ts` in the sample project uses a location on Elastic's global managed testing infrastructure.
+Administrators can restrict access to Elastic's global managed testing infrastructure.
+When you attempt to <<synthetics-get-started-project-push,`push` the sample monitors>>,
+if you see an error stating that you don't have permission to use Elastic managed global locations,
+refer to the <<synthetics-troubleshooting-no-locations,troubleshooting guide>> for guidance.
+====
+
 * `package.json` contains NPM settings for your project. Learn more in the https://docs.npmjs.com/about-packages-and-modules[NPM documentation].
 * `.github` contains sample workflow files to use with GitHub Actions.
 
 [discrete]
 = Examine sample monitors
 
-Inside the `lightweight` directory you'll find sample lightweight monitors. 
+Inside the `lightweight` directory you'll find sample lightweight monitors.
 Here's an example of a YAML file defining a lightweight monitor:
 
 [source,yml]
@@ -118,8 +140,7 @@ heartbeat.monitors:
 For more details on lightweight monitor configuration options,
 refer to <<synthetics-lightweight>>.
 
-
-Inside the `journeys` directory you'll find sample browser monitors. 
+Inside the `journeys` directory you'll find sample browser monitors.
 Here's an example of a TypeScript file defining a browser monitor:
 
 [source,ts]
@@ -147,6 +168,7 @@ For more details on writing journeys and configuring browser monitors,
 refer to <<synthetics-journeys>>.
 
 [discrete]
+[[synthetics-get-started-project-push]]
 = Test and connect to the {stack}
 
 While inside the project directory you can do two things with the `npx @elastic/synthetics` command:
@@ -181,7 +203,6 @@ with the {kib} URL for the deployment from which to fetch available locations.
 [discrete]
 = View in {kib}
 
-
 [NOTE]
 ====
 When a monitor is created or updated, the first run might not occur immediately, but the time it takes for the first run to occur will be less than the monitor's configured frequency. For example, if you create a monitor and configure it to run every 10 minutes, the first run will occur within 10 minutes of being created. After the first run, the monitor will begin running regularly based on the configured frequency. You can run a manual test if you want to see the results more quickly.

docs/en/observability/synthetics-get-started-ui.asciidoc

@@ -53,6 +53,13 @@ To use the {synthetics-app} to add a lightweight monitor:
 . Click **Create monitor**.
 . Set the monitor type to *HTTP Ping*, *TCP Ping*, or *ICMP Ping*.
 . In _Locations_, select one or more locations.
++
+[NOTE]
+====
+If you don't see any locations listed, refer to the
+<<synthetics-troubleshooting-no-locations,troubleshooting guide>> for guidance.
+====
+
 . Set the _Frequency_, and configure the monitor as needed.
 . Click *Advanced options* to see more ways to configure your monitor.
 . (Optional) Click *Run test* to verify that the test is valid.
@@ -90,6 +97,13 @@ To use the {synthetics-app} to add a browser monitor:
 . Click **Create monitor**.
 . Set the monitor type to *Multistep*.
 . In _Locations_, select one or more locations.
++
+[NOTE]
+====
+If you don't see any locations listed, refer to the
+<<synthetics-troubleshooting-no-locations,troubleshooting guide>> for guidance.
+====
+
 . Set the _Frequency_.
 . Add steps to the *Script editor* code block directly.
 The `journey` keyword isn't required, and variables like `page` and `params` will be part of your script's scope.

docs/en/observability/synthetics-role-read.asciidoc

@@ -39,7 +39,7 @@ and grant the following privileges:
 | Read-only access to synthetics alert indices.
 
 | {kibana-ref}/kibana-privileges.html[Kibana]
-| `Uptime/Synthetics`: `All`
+| `Synthetics and Uptime`: `All`
 | Access to the {synthetics-app} in {kib}.
 
 |====

docs/en/observability/synthetics-role-write.asciidoc

@@ -1,5 +1,5 @@
 [[synthetics-role-write]]
-=  Writer role
+= Writer role
 
 IMPORTANT: To minimize the privileges required by the writer role, use the
 <<synthetics-role-setup,setup role>> to enable Monitor Management.
@@ -73,14 +73,25 @@ and start by granting the following privileges:
 | Read-only access to synthetics alert indices.
 
 | {kibana-ref}/kibana-privileges.html[Kibana]
-| `Uptime/Synthetics`: `All`
+| `Synthetics and Uptime`: `All`
 | Access to the {synthetics-app} in {kib}.
 
 |====
 
 Additional privileges will depend on the factors below.
 
 [discrete]
+[[disable-managed-locations]]
+== To restrict using Elastic's global managed infrastructure
+
+To restrict users assigned this role from using monitors hosted on Elastic's global managed infrastructure:
+
+. Expand `Synthetics and Uptime` in the list of {kibana-ref}/kibana-privileges.html[Kibana] privileges.
+. Toggle _Customize sub-feature privileges_.
+. Uncheck _Elastic managed locations enabled_.
+
+[discrete]
+[[synthetics-role-write-private-locations]]
 == If using Private Locations
 
 The user who initially sets up a new Private Location needs additional privileges. Users who create or update monitors hosted on that Private Location do not need any additional permissions.

docs/en/observability/synthetics-roles.asciidoc

@@ -22,8 +22,3 @@ In general, these are types of privileges you'll work with:
 * **{es} cluster privileges**: Manage the actions a user can perform against your cluster.
 * **{es} index privileges**: Control access to the data in specific indices your cluster.
 * **{kib} space privileges**: Grant users write or read access to features and apps within {kib}.
-
-
-
-
-

docs/en/observability/synthetics-troubleshooting.asciidoc

@@ -100,9 +100,38 @@ If the duration is _less than_ the scheduled frequency or the suggestion above d
 
 To fix this issue, you can either:
 
-* Increase the number of concurrent browser monitors allowed (as described in <<synthetics-private-location-scaling,Scaling Private Locations>>), paying attention to the scaling and hardware requirements documented).
+* Increase the number of concurrent browser monitors allowed (as described in <<synthetics-private-location-scaling,Scaling Private Locations>>), paying attention to the scaling and hardware requirements documented.
 * Create multiple {private-location}s and spread your browser monitors across them more evenly (effectively horizontally scaling your {private-location}s).
 
+[discrete]
+[[synthetics-troubleshooting-no-locations]]
+== No locations are available
+
+When using {ecloud}, if there are no options available in the _Locations_ dropdown when you
+try to create a monitor in the {synthetics-app} _or_ if no locations are listed when using the
+<<elastic-synthetics-locations-command,`location` command>>, it might be because you do not have permission to
+use Elastic managed locations _and_ there are no <<monitor-via-private-agent,Private Locations>>
+available yet.
+
+There are a few ways to fix this:
+
+* If you have <<synthetics-role-write,write access>> including the privileges for <<synthetics-role-write-private-locations,creating new Private Locations>>, you can <<monitor-via-private-agent,create a new Private Location>>. Then try creating the monitor again.
+* If you do _not_ have the right privileges to create a Private Location, you can ask someone with the <<synthetics-role-write-private-locations,necessary privileges>> to create a Private Location or ask an administrator with a <<synthetics-role-setup,setup role>> to give you the necessary privileges and <<monitor-via-private-agent,create a new Private Location>>. Then try creating the monitor again.
+* If you want to create a monitor to run on Elastic's global managed infrastructure, ask an administrator with a <<synthetics-role-setup,setup role>> to update <<disable-managed-locations,`Synthetics and Uptime` sub-feature privileges>> for the role you're currently assigned. Then try creating the monitor again.
+
+[discrete]
+[[synthetics-troubleshooting-public-locations-disabled]]
+== You do not have permission to use Elastic managed locations
+
+If you try to create or edit a monitor hosted on Elastic's global managed infrastructure but see a note that you do not have permission to use Elastic managed locations, an administrator has restricted the use of public locations.
+
+To fix this you can either:
+
+* Ask an administrator with a <<synthetics-role-setup,setup role>> to update
+<<disable-managed-locations,`Synthetics and Uptime` sub-feature privileges>> for the role you're
+currently assigned or assign you a role that allows using Elastic's global managed infrastructure.
+* Use a <<monitor-via-private-agent,Private Location>>.
+
 [discrete]
 [[synthetics-troubleshooting-get-help]]
 = Get help