From 88ff0624790a42de5228882b1025c4512bf9e448 Mon Sep 17 00:00:00 2001 From: Roberto Seldner Date: Tue, 18 Nov 2025 08:26:23 -0700 Subject: [PATCH 1/6] Document usage of environment variables in Synthetics run from Private Locations Added instructions for using environment variables in synthetics run from Private Locations --- .../synthetics/work-with-params-secrets.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/solutions/observability/synthetics/work-with-params-secrets.md b/solutions/observability/synthetics/work-with-params-secrets.md index 39ca87ab09..99f4bb27d1 100644 --- a/solutions/observability/synthetics/work-with-params-secrets.md +++ b/solutions/observability/synthetics/work-with-params-secrets.md @@ -137,6 +137,8 @@ Params are viewable in plain-text by administrators and other users with `all` p :::: +### Use environment variables in Synthetics Projects + If you are managing monitors with a Synthetics project, you can use environment variables in your `synthetics.config.ts` or `synthetics.config.js` file. The example below uses `process.env.MY_URL` to reference a variable named `MY_URL` defined in the environment and assigns its value to a param. That param can then be used in both lightweight and browser monitors that are managed in the Synthetics project: @@ -148,3 +150,39 @@ export default { } }; ``` + +### Use environment variables with Private Locations + +If you are using Kibana-managed monitors and running them on a Private Location, you can inject environment variables directly into the agent's runtime environment. + +This method allows you to keep sensitive values out of the Kibana UI. It requires access to the infrastructure hosting the Elastic Agent. + +#### 1. Pass variables to the Private Location +When starting your Private Location (Elastic Agent) using Docker, use the `--env` flag to pass your variables. + +::::{warning} +Note, these variables will be accessible to **all** monitors running on this specific Private Location. + +:::: + +```bash +docker run \ + --env FLEET_ENROLL=1 \ + --env FLEET_URL= \ + --env FLEET_ENROLLMENT_TOKEN= \ + --env MY_URL= \ + --cap-add=NET_RAW \ + --cap-add=SETUID \ + -d --restart=unless-stopped \ +docker.elastic.co/elastic-agent/elastic-agent-complete:X.X.X +``` + +#### 2. Reference variables in the inline script +In the Synthetics Monitor editor in Kibana, you can now access these variables using `process.env`. + +```js +step('navigate to secure url', async () => { + // The script reads the environment variable from the container + await page.goto(process.env.MY_URL); +}); +``` From 8a95899a4da93dbac532af6db3173da34c10b9bb Mon Sep 17 00:00:00 2001 From: Roberto Seldner Date: Tue, 18 Nov 2025 08:29:16 -0700 Subject: [PATCH 2/6] Update warning about variable accessibility scope Clarified the scope of variable accessibility in Private Location. --- solutions/observability/synthetics/work-with-params-secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/observability/synthetics/work-with-params-secrets.md b/solutions/observability/synthetics/work-with-params-secrets.md index 99f4bb27d1..dc02927071 100644 --- a/solutions/observability/synthetics/work-with-params-secrets.md +++ b/solutions/observability/synthetics/work-with-params-secrets.md @@ -161,7 +161,7 @@ This method allows you to keep sensitive values out of the Kibana UI. It require When starting your Private Location (Elastic Agent) using Docker, use the `--env` flag to pass your variables. ::::{warning} -Note, these variables will be accessible to **all** monitors running on this specific Private Location. +These variables will be accessible to **all** monitors running on **this specific** Private Location. :::: From 079fe3056066c82847e811211672778cd90e75d2 Mon Sep 17 00:00:00 2001 From: Roberto Seldner Date: Tue, 18 Nov 2025 08:32:54 -0700 Subject: [PATCH 3/6] Update comment to specify private location of variable Clarified the source of the environment variable in the script. --- solutions/observability/synthetics/work-with-params-secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/observability/synthetics/work-with-params-secrets.md b/solutions/observability/synthetics/work-with-params-secrets.md index dc02927071..929de4a0b6 100644 --- a/solutions/observability/synthetics/work-with-params-secrets.md +++ b/solutions/observability/synthetics/work-with-params-secrets.md @@ -182,7 +182,7 @@ In the Synthetics Monitor editor in Kibana, you can now access these variables u ```js step('navigate to secure url', async () => { - // The script reads the environment variable from the container + // The script reads the environment variable from the private location elastic agent container await page.goto(process.env.MY_URL); }); ``` From 60686d01e29d6acaa1743e1de3cda97d00d547a8 Mon Sep 17 00:00:00 2001 From: Roberto Seldner Date: Tue, 18 Nov 2025 08:38:11 -0700 Subject: [PATCH 4/6] Update environment variable placeholders in documentation Matching the syntax in this example: https://www.elastic.co/docs/solutions/observability/synthetics/monitor-resources-on-private-networks#synthetics-private-location-connect --- .../observability/synthetics/work-with-params-secrets.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/solutions/observability/synthetics/work-with-params-secrets.md b/solutions/observability/synthetics/work-with-params-secrets.md index 929de4a0b6..d24801606d 100644 --- a/solutions/observability/synthetics/work-with-params-secrets.md +++ b/solutions/observability/synthetics/work-with-params-secrets.md @@ -168,9 +168,9 @@ These variables will be accessible to **all** monitors running on **this specifi ```bash docker run \ --env FLEET_ENROLL=1 \ - --env FLEET_URL= \ - --env FLEET_ENROLLMENT_TOKEN= \ - --env MY_URL= \ + --env FLEET_URL={fleet_server_host_url} \ + --env FLEET_ENROLLMENT_TOKEN={enrollment_token} \ + --env MY_URL={secret_value} \ --cap-add=NET_RAW \ --cap-add=SETUID \ -d --restart=unless-stopped \ From 432f647cb74e67c7ea510ae2c8fecd086af16cc6 Mon Sep 17 00:00:00 2001 From: Roberto Seldner Date: Tue, 18 Nov 2025 08:42:42 -0700 Subject: [PATCH 5/6] Update documentation for environment variables usage Clarified the use of environment variables with Private Locations and moved warning above the example. --- .../synthetics/work-with-params-secrets.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/solutions/observability/synthetics/work-with-params-secrets.md b/solutions/observability/synthetics/work-with-params-secrets.md index d24801606d..076bf051e0 100644 --- a/solutions/observability/synthetics/work-with-params-secrets.md +++ b/solutions/observability/synthetics/work-with-params-secrets.md @@ -154,16 +154,17 @@ export default { ### Use environment variables with Private Locations If you are using Kibana-managed monitors and running them on a Private Location, you can inject environment variables directly into the agent's runtime environment. +This method allows you to keep sensitive values out of the Kibana UI. Instead, it requires access to the infrastructure hosting the Elastic Agent. -This method allows you to keep sensitive values out of the Kibana UI. It requires access to the infrastructure hosting the Elastic Agent. +::::{warning} +These variables will be accessible to **all** monitors running on **this specific** Private Location. + +:::: #### 1. Pass variables to the Private Location When starting your Private Location (Elastic Agent) using Docker, use the `--env` flag to pass your variables. -::::{warning} -These variables will be accessible to **all** monitors running on **this specific** Private Location. -:::: ```bash docker run \ @@ -174,7 +175,7 @@ docker run \ --cap-add=NET_RAW \ --cap-add=SETUID \ -d --restart=unless-stopped \ -docker.elastic.co/elastic-agent/elastic-agent-complete:X.X.X + docker.elastic.co/elastic-agent/elastic-agent-complete:X.X.X ``` #### 2. Reference variables in the inline script From 64618d113520f2412d430313a612d26ad723e1b1 Mon Sep 17 00:00:00 2001 From: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com> Date: Tue, 25 Nov 2025 09:32:35 -0600 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .../observability/synthetics/work-with-params-secrets.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/solutions/observability/synthetics/work-with-params-secrets.md b/solutions/observability/synthetics/work-with-params-secrets.md index 076bf051e0..88257bf14c 100644 --- a/solutions/observability/synthetics/work-with-params-secrets.md +++ b/solutions/observability/synthetics/work-with-params-secrets.md @@ -154,15 +154,15 @@ export default { ### Use environment variables with Private Locations If you are using Kibana-managed monitors and running them on a Private Location, you can inject environment variables directly into the agent's runtime environment. -This method allows you to keep sensitive values out of the Kibana UI. Instead, it requires access to the infrastructure hosting the Elastic Agent. +This method allows you to keep sensitive values out of the {{kib}} UI. Instead, it stores those values on the infrastructure hosting the {{agent}}. ::::{warning} -These variables will be accessible to **all** monitors running on **this specific** Private Location. +These variables are accessible to all monitors running on this specific Private Location. :::: #### 1. Pass variables to the Private Location -When starting your Private Location (Elastic Agent) using Docker, use the `--env` flag to pass your variables. +When starting your Private Location ({{agent}}) using Docker, use the `--env` flag to pass your variables. @@ -179,7 +179,7 @@ docker run \ ``` #### 2. Reference variables in the inline script -In the Synthetics Monitor editor in Kibana, you can now access these variables using `process.env`. +In the Synthetics **Monitors** editor in {{kib}}, you can now access these variables using `process.env`. ```js step('navigate to secure url', async () => {