Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions solutions/observability/synthetics/work-with-params-secrets.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,8 @@ Params are viewable in plain-text by administrators and other users with `all` p

::::

### Use environment variables in Synthetics Projects
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Use environment variables in Synthetics Projects
### Use environment variables in synthetics projects

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this suggestion is correct. The rest of the page is consistent in the usage of "Synthetics project"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, Synthetics project seems to be consistent through the docs.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I was writing Synthetics docs, I would use Synthetics when referring to the Elastic Synthetics product and synthetic when using it as an adjective like synthetic monitors. In this case, I would say it makes more sense to use "Synthetics project" because a "project" is an Elastic-specific concept unlike "monitor", which is generic concept in the world of synthetic monitoring.


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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mdbirnstiehl is there a good reason to use param here instead of parameter?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I now see the whole page uses params. Not saying it needs to change. Just curious about it.

Copy link
Contributor

@mdbirnstiehl mdbirnstiehl Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think so, the setting in Kibana is Global parameters, but you pass --params CLI argument, so I think it would make sense to say either.

Expand All @@ -148,3 +150,40 @@ 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Contributor

@benironside benironside Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Comment on lines +164 to +165
Copy link
Contributor

@benironside benironside Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### 1. Pass variables to the Private Location
When starting your Private Location (Elastic Agent) using Docker, use the `--env` flag to pass your variables.
#### 1. Pass variables to the Private Location
When starting your Private Location ({{agent}}) using Docker, use the `--env` flag to pass your variables.




```bash
docker run \
--env FLEET_ENROLL=1 \
--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 \
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`.
Copy link
Contributor

@benironside benironside Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 () => {
// The script reads the environment variable from the private location elastic agent container
await page.goto(process.env.MY_URL);
});
```
Loading