diff --git a/docs/en/observability/images/synthetics-monitor-management-api-key.png b/docs/en/observability/images/synthetics-monitor-management-api-key.png index bdaac7d67c..63828e99dc 100644 Binary files a/docs/en/observability/images/synthetics-monitor-management-api-key.png and b/docs/en/observability/images/synthetics-monitor-management-api-key.png differ diff --git a/docs/en/observability/synthetics-command-reference.asciidoc b/docs/en/observability/synthetics-command-reference.asciidoc index 0a7f596987..04fefe0187 100644 --- a/docs/en/observability/synthetics-command-reference.asciidoc +++ b/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 `:: 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 +<>. diff --git a/docs/en/observability/synthetics-get-started-project.asciidoc b/docs/en/observability/synthetics-get-started-project.asciidoc index 97e9fe4062..f88f06fa14 100644 --- a/docs/en/observability/synthetics-get-started-project.asciidoc +++ b/docs/en/observability/synthetics-get-started-project.asciidoc @@ -60,7 +60,7 @@ For more details, refer to <>. [[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 <>. +==== + [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 <>. +==== . 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 <>, 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 <>, +if you see an error stating that you don't have permission to use Elastic managed global locations, +refer to the <> 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 <>. - -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 <>. [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. diff --git a/docs/en/observability/synthetics-get-started-ui.asciidoc b/docs/en/observability/synthetics-get-started-ui.asciidoc index e95c000863..771ec94624 100644 --- a/docs/en/observability/synthetics-get-started-ui.asciidoc +++ b/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 +<> 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 +<> 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. diff --git a/docs/en/observability/synthetics-role-read.asciidoc b/docs/en/observability/synthetics-role-read.asciidoc index 07bd875aa6..a68b8926a7 100644 --- a/docs/en/observability/synthetics-role-read.asciidoc +++ b/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}. |==== diff --git a/docs/en/observability/synthetics-role-write.asciidoc b/docs/en/observability/synthetics-role-write.asciidoc index eb4cb26879..0614bedfae 100644 --- a/docs/en/observability/synthetics-role-write.asciidoc +++ b/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 <> to enable Monitor Management. @@ -73,7 +73,7 @@ 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}. |==== @@ -81,6 +81,17 @@ and start by granting the following privileges: 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. diff --git a/docs/en/observability/synthetics-roles.asciidoc b/docs/en/observability/synthetics-roles.asciidoc index 90eb88388c..ca53beb9be 100644 --- a/docs/en/observability/synthetics-roles.asciidoc +++ b/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}. - - - - - diff --git a/docs/en/observability/synthetics-troubleshooting.asciidoc b/docs/en/observability/synthetics-troubleshooting.asciidoc index c57c9ca58a..0f6356e09e 100644 --- a/docs/en/observability/synthetics-troubleshooting.asciidoc +++ b/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 <>), paying attention to the scaling and hardware requirements documented). +* Increase the number of concurrent browser monitors allowed (as described in <>), 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 +<>, it might be because you do not have permission to +use Elastic managed locations _and_ there are no <> +available yet. + +There are a few ways to fix this: + +* If you have <> including the privileges for <>, you can <>. 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 <> to create a Private Location or ask an administrator with a <> to give you the necessary privileges and <>. 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 <> to update <> 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 <> to update +<> for the role you're +currently assigned or assign you a role that allows using Elastic's global managed infrastructure. +* Use a <>. + [discrete] [[synthetics-troubleshooting-get-help]] = Get help