From 380e4dc847ff82323084fad7e1ba3f1328ad4952 Mon Sep 17 00:00:00 2001 From: James Rasell Date: Thu, 27 Nov 2025 08:57:55 +0000 Subject: [PATCH 1/2] nomad: Add client documentation for new fingerprint block. --- .../content/docs/configuration/client.mdx | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/content/nomad/v1.11.x/content/docs/configuration/client.mdx b/content/nomad/v1.11.x/content/docs/configuration/client.mdx index 74274bc9bb..1c86ed3015 100644 --- a/content/nomad/v1.11.x/content/docs/configuration/client.mdx +++ b/content/nomad/v1.11.x/content/docs/configuration/client.mdx @@ -227,6 +227,11 @@ client { `data-dir`][top_level_data_dir] suffixed with `common_plugins`, like `"/opt/nomad/common_plugins"`. This must be an absolute path. +- `fingerprint` ([Fingerprint](#fingerprint-parameters): nil) - + Provides configuration for fingerprinters used by the client and applies to + `"env_aws"`, `"env_azure"`, `"env_digitalocean"`, and `"env_gce"` + fingerprinters. + - `host_volume` ([host_volume](#host_volume-block): nil) - Exposes paths from the host as volumes that can be mounted into jobs. @@ -520,6 +525,39 @@ refer to the [drivers documentation](/nomad/docs/job-declare/task-driver). the Nomad client's environment. By default a minimal environment is set including a `PATH` appropriate for the operating system. +### `fingerprint` Parameters + +- `name` `(string: "")` - The name of the fingerprinter the configuration + applies to. This field is required and is provided as part of the block label. + It supports `"env_aws"`, `"env_azure"`, `"env_digitalocean"`, and `"env_gce"`. + +- `retry_attempts` `(int: 0)` - Specifies the maximum number of retry attempts + to make before giving up. This field supports `-1` for unlimited retries, but + use is not recommended as this may cause the client to hang indefinitely on + startup if the fingerprinting source is unavailable. The default value of `0` + means no retries are made. + +- `retry_interval` `(string: "2s")` - Specifies the amount of time to wait + between retry attempts. + +- `exit_on_failure` `(bool: false)` - Specifies whether the client should exit + if fingerprinter fails to probe the envrionment endpoint service. + + Nomad tries to identify if its running within the named environment on startup + by probing the environment's metadata endpoint. If the endpoint is + unreachable, Nomad will by default skip fingerprinting for that environment + and continue startup. Setting this option to `true` will cause Nomad to exit + in this situation. This is useful for operators who want to ensure that Nomad + only starts when it can successfully fingerprint the environment. + +```hcl +fingerprinter "env_aws" { + retry_attempts = "5" + retry_interval = "1s" + exit_on_failure = true +} +``` + ### `template` Parameters - `function_denylist` `([]string: ["plugin", "executeTemplate", From 1ff00de21f624b0f138997d33da8b37d63a7a0d0 Mon Sep 17 00:00:00 2001 From: James Rasell Date: Tue, 2 Dec 2025 14:29:36 +0000 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Aimee Ukasick --- .../v1.11.x/content/docs/configuration/client.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/configuration/client.mdx b/content/nomad/v1.11.x/content/docs/configuration/client.mdx index 1c86ed3015..1d8e0e7b6a 100644 --- a/content/nomad/v1.11.x/content/docs/configuration/client.mdx +++ b/content/nomad/v1.11.x/content/docs/configuration/client.mdx @@ -528,12 +528,12 @@ refer to the [drivers documentation](/nomad/docs/job-declare/task-driver). ### `fingerprint` Parameters - `name` `(string: "")` - The name of the fingerprinter the configuration - applies to. This field is required and is provided as part of the block label. + applies to. This field is required and is part of the block label. It supports `"env_aws"`, `"env_azure"`, `"env_digitalocean"`, and `"env_gce"`. - `retry_attempts` `(int: 0)` - Specifies the maximum number of retry attempts to make before giving up. This field supports `-1` for unlimited retries, but - use is not recommended as this may cause the client to hang indefinitely on + we do not recommend `-1` as this may cause the client to hang indefinitely on startup if the fingerprinting source is unavailable. The default value of `0` means no retries are made. @@ -545,9 +545,9 @@ refer to the [drivers documentation](/nomad/docs/job-declare/task-driver). Nomad tries to identify if its running within the named environment on startup by probing the environment's metadata endpoint. If the endpoint is - unreachable, Nomad will by default skip fingerprinting for that environment - and continue startup. Setting this option to `true` will cause Nomad to exit - in this situation. This is useful for operators who want to ensure that Nomad + unreachable, Nomad by default skips fingerprinting for that environment + and continue startup. Setting this option to `true` causes Nomad to exit + in this situation. This is useful if you want to ensure that Nomad only starts when it can successfully fingerprint the environment. ```hcl