From db28ebed741145179fc5ab409d4ddc5978973fda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emilio=20Alvarez=20Pi=C3=B1eiro?= <95703246+emilioalvap@users.noreply.github.com> Date: Tue, 15 Oct 2024 10:48:05 +0200 Subject: [PATCH] [Synthetics] Add client certificate reference to docs (#4351) * [Synthetics] Add client certificate reference to docs --------- Co-authored-by: Colleen McGinnis (cherry picked from commit 9410c588fbd35486564f0b8844e89e7a0eb66ea0) # Conflicts: # docs/en/serverless/synthetics/synthetics-configuration.mdx --- .../synthetics-configuration.asciidoc | 46 +++- .../synthetics/synthetics-configuration.mdx | 217 ++++++++++++++++++ 2 files changed, 262 insertions(+), 1 deletion(-) create mode 100644 docs/en/serverless/synthetics/synthetics-configuration.mdx diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc index 51dbbdce81..1889ba306c 100644 --- a/docs/en/observability/synthetics-configuration.asciidoc +++ b/docs/en/observability/synthetics-configuration.asciidoc @@ -82,7 +82,51 @@ For all available options, refer to the https://playwright.dev/docs/test-configu Do not attempt to run in headful mode (using `headless:false`) when running through Elastic's global managed testing infrastructure or Private Locations as this is not supported. ==== -Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including timeouts, timezones, and device emulation. +Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including TLS client authentication, timeouts, timezones, and device emulation. + +[discrete] +[[synthetics-configuration-playwright-options-client-certificates]] +== TLS client authentication +To enable TLS client authentication, set the https://playwright.dev/docs/api/class-testoptions#test-options-client-certificates[`clientCertificates`] option in the configuration file: + +[NOTE] +===== +Path-based options `{certPath, keyPath, pfxPath}` are only supported on Private Locations, defer to in-memory alternatives `{cert, key, pfx}` when running on locations hosted by Elastic. +===== + +[source,js] +---- +playwrightOptions: { + clientCertificates: [ + { + origin: 'https://example.com', + certPath: './cert.pem', + keyPath: './key.pem', + passphrase: 'mysecretpassword', + }, + { + origin: 'https://example.com', + cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."), + key: Buffer.from("-----BEGIN RSA PRIVATE KEY-----\n..."), + passphrase: 'mysecretpassword', + } + ], +} +---- + +[TIP] +===== +When using Synthetics monitor UI, `cert`, `key` and `pfx` can simply be specified using a string literal: +[source,js] +---- +clientCertificates: [ + { + cert: "-----BEGIN CERTIFICATE-----\n...", + // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."), + } +], +---- +===== [discrete] [[synthetics-configuration-playwright-options-timeouts]] diff --git a/docs/en/serverless/synthetics/synthetics-configuration.mdx b/docs/en/serverless/synthetics/synthetics-configuration.mdx new file mode 100644 index 0000000000..5d487c27b2 --- /dev/null +++ b/docs/en/serverless/synthetics/synthetics-configuration.mdx @@ -0,0 +1,217 @@ +--- +slug: /serverless/observability/synthetics-configuration +title: Configure a Synthetics project +# description: Description to be written +tags: [] +--- + +

+ +import Snippet1 from '../transclusion/synthetics/configuration/monitor-config-options.mdx' + +
+ +Synthetic tests support the configuration of dynamic parameters that can be +used in Synthetics projects. In addition, the Synthetics agent, which is built on top +of Playwright, supports configuring browser and context options that are available +in Playwright-specific methods, for example, `ignoreHTTPSErrors`, `extraHTTPHeaders`, and `viewport`. + +
+ +Create a `synthetics.config.js` or `synthetics.config.ts` file in the root of the +Synthetics project and specify the options. For example: + +```ts +import type { SyntheticsConfig } from '@elastic/synthetics'; + +export default env => { + const config: SyntheticsConfig = { + params: { + url: 'https://www.elastic.co', + }, + playwrightOptions: { + ignoreHTTPSErrors: false, + }, + /** + * Configure global monitor settings + */ + monitor: { + schedule: 10, + locations: [ 'us_east' ], + }, + /** + * Synthetic project monitors settings + */ + project: { + id: 'my-synthetics-project', + url: 'https://abc123', + }, + }; + if (env !== 'development') { + /** + * Override configuration specific to environment + * For example, config.params.url = "" + */ + } + return config; +}; +``` + + + `env` in the example above is the environment you are pushing from + _not_ the environment where monitors will run. In other words, `env` + corresponds to the configured `NODE_ENV`. + + +The configuration file can either export an object, or a function that when +called should return the generated configuration. To know more about configuring +the tests based on environments, look at the dynamic configuration documentation. + +
+ +## `params` + +A JSON object that defines any variables your tests require. +Read more in Work with params and secrets. + +
+ +## `playwrightOptions` + +For all available options, refer to the [Playwright documentation](https://playwright.dev/docs/test-configuration). + + + Do not attempt to run in headful mode (using `headless:false`) when running through Elastic's global managed testing infrastructure or Private Locations as this is not supported. + + +Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including TLS client authentication, timeouts, timezones, and device emulation. + +
+ +### TLS client authentication +To enable TLS client authentication, set the [`clientCertificates`](https://playwright.dev/docs/api/class-testoptions#test-options-client-certificates) option in the configuration file: + + + Path-based options `{certPath, keyPath, pfxPath}` are only supported on Private Locations, defer to in-memory alternatives `{cert, key, pfx}` when running on locations hosted by Elastic. + + +```js +playwrightOptions: { + clientCertificates: [ + { + origin: 'https://example.com', + certPath: './cert.pem', + keyPath: './key.pem', + passphrase: 'mysecretpassword', + }, + { + origin: 'https://example.com', + cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."), + key: Buffer.from("-----BEGIN RSA PRIVATE KEY-----\n..."), + passphrase: 'mysecretpassword', + } + ], +} +``` + + + When using Synthetics monitor UI, `cert`, `key` and `pfx` can simply be specified using a string literal: + ```js + clientCertificates: [ + { + cert: "-----BEGIN CERTIFICATE-----\n...", + // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."), + } + ], + ``` + + +
+ +### Timeouts + +Playwright has two types of timeouts that are used in Elastic Synthetics: +[action and navigation timeouts](https://playwright.dev/docs/test-timeouts#action-and-navigation-timeouts). + +Elastic Synthetics uses a default action and navigation timeout of 50 seconds. +You can override this default using [`actionTimeout`](https://playwright.dev/docs/api/class-testoptions#test-options-action-timeout) and [`navigationTimeout`](https://playwright.dev/docs/api/class-testoptions#test-options-navigation-timeout) +in `playwrightOptions`. + +
+ +### Timezones and locales + +The Elastic global managed testing infrastructure does not currently set the timezone. +For ((private-location))s, the monitors will use the timezone of the host machine running +the ((agent)). This is not always desirable if you want to test how a web application +behaves across different timezones. To specify what timezone to use when the monitor runs, +you can use `playwrightOptions` on a per monitor or global basis. + +To use a timezone and/or locale for all monitors in the Synthetics project, set +[`locale` and/or `timezoneId`](https://playwright.dev/docs/emulation#locale%2D%2Dtimezone) +in the configuration file: + +```js +playwrightOptions: { + locale: 'en-AU', + timezoneId: 'Australia/Brisbane', +} +``` + +To use a timezone and/or locale for a _specific_ monitor, add these options to a +journey using `monitor.use`. + +
+ +### Device emulation + +Users can emulate a mobile device using the configuration file. +The example configuration below runs tests in "Pixel 5" emulation mode. + +```js +import { SyntheticsConfig } from "@elastic/synthetics" +import { devices } from "playwright-chromium" + +const config: SyntheticsConfig = { + playwrightOptions: { + ...devices['Pixel 5'] + } +} + +export default config; +``` + +
+ +## `project` + +Information about the Synthetics project. + + + `id` (`string`) + + A unique id associated with your Synthetics project. + It will be used for logically grouping monitors. + + If you used `init` to create a Synthetics project, this is the `` you specified. + + + `url` (`string`) + + The URL for the Observability project to which you want to upload the monitors. + + + +
+ +## `monitor` + +Default values to be applied to _all_ monitors when using the `@elastic/synthetics` `push` command. + + + +For information on configuring monitors individually, refer to: + +* Configure individual browser monitors for browser monitors +* Configure lightweight monitors for lightweight monitors +