From 54f493823735aa21498e3707cc5f0c02839b13f6 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Fri, 10 Jan 2025 11:30:55 -0600 Subject: [PATCH] Docs SEO: Update Configuration section to improve search (#24759) (#24835) * Docs SEO: Update Configuration section to improve search engine opt CE-775 * Add enterprise only back to audit * Update descriptions and add intro paragraph * Fix typo * replace "below" and "see" * Apply suggestions from code review --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- website/content/docs/configuration/acl.mdx | 14 ++-- website/content/docs/configuration/audit.mdx | 24 +++--- .../content/docs/configuration/autopilot.mdx | 25 +++--- website/content/docs/configuration/client.mdx | 61 ++++++++------- website/content/docs/configuration/consul.mdx | 40 ++++++---- website/content/docs/configuration/index.mdx | 35 +++++---- .../docs/configuration/keyring/awskms.mdx | 16 ++-- .../configuration/keyring/azurekeyvault.mdx | 23 +++--- .../docs/configuration/keyring/gcpckms.mdx | 16 ++-- .../docs/configuration/keyring/index.mdx | 15 ++-- .../docs/configuration/keyring/transit.mdx | 23 +++--- website/content/docs/configuration/plugin.mdx | 13 +++- .../content/docs/configuration/reporting.mdx | 21 ++--- website/content/docs/configuration/search.mdx | 13 ++-- .../content/docs/configuration/sentinel.mdx | 27 +++++-- website/content/docs/configuration/server.mdx | 78 ++++++++++--------- .../docs/configuration/server_join.mdx | 35 +++++---- .../content/docs/configuration/telemetry.mdx | 40 +++++----- website/content/docs/configuration/tls.mdx | 24 +++--- website/content/docs/configuration/ui.mdx | 14 ++-- website/content/docs/configuration/vault.mdx | 44 ++++++----- website/data/docs-nav-data.json | 8 +- 22 files changed, 353 insertions(+), 256 deletions(-) diff --git a/website/content/docs/configuration/acl.mdx b/website/content/docs/configuration/acl.mdx index 07c6437783f..8dcce0d4d9f 100644 --- a/website/content/docs/configuration/acl.mdx +++ b/website/content/docs/configuration/acl.mdx @@ -1,17 +1,17 @@ --- layout: docs -page_title: acl Block - Agent Configuration +page_title: acl Block in Agent Configuration description: >- - The "acl" block configures the Nomad agent to enable ACLs and tune various - parameters. + Configure Nomad's Access Control List (ACL) system behavior in the `acl` block of a Nomad agent configuration. Enable ACL enforcement, change token replication and expiration values, and tune the cache for token, role, and policy TTLs. --- -# `acl` Block +# acl Block in Agent Configuration -The `acl` block configures the Nomad agent to enable ACLs and tunes various -ACL parameters. Learn more about configuring Nomad's ACL system in the [Secure +This page provides reference information for configuring Nomad's Access Control List (ACL) system behavior in the `acl` block of a Nomad agent configuration. Enable ACL enforcement, change token replication and expiration values, and tune the cache for token, role, and policy TTLs. + +Learn more about configuring Nomad's ACL system in the [Secure Nomad with Access Control guide][secure-guide]. ```hcl @@ -55,7 +55,7 @@ acl { non-authoritative region to mirror the policies and tokens into the local region from the [`authoritative_region`][authoritative-region]. Setting `replication_token` requires that ACLs have been bootstrapped in the - authoritative region. See [Configure for multiple regions][] in the ACLs + authoritative region. Refer to [Configure for multiple regions][] in the ACLs tutorial. - `token_min_expiration_ttl` `(string: "1m")` - Specifies the lowest acceptable diff --git a/website/content/docs/configuration/audit.mdx b/website/content/docs/configuration/audit.mdx index 1839d935236..4ed021b9687 100644 --- a/website/content/docs/configuration/audit.mdx +++ b/website/content/docs/configuration/audit.mdx @@ -1,17 +1,19 @@ --- layout: docs -page_title: audit Block - Agent Configuration +page_title: audit Block in Agent Configuration description: >- - The "audit" block configures the Nomad agent to configure Audit Logging - behavior. This is an Enterprise-only feature. + Configure audit logging behavior in the `audit` block of a Nomad agent configuration. Enable audit logs, define a sink to stream audit logs to, and change filter rules to exclude events from the audit log. Review example audit logs. --- -# `audit` Block +# `audit` Block in Agent Configuration + -The `audit` block configures the Nomad agent to configure Audit logging behavior. -Audit logging is an Enterprise-only feature. +This page provides reference information for configuring audit logging behavior +in the `audit` block of a Nomad agent configuration. Enable audit logs, define a +sink to stream audit logs to, and change filter rules to exclude events from the +audit log. ```hcl audit { @@ -177,12 +179,12 @@ audit { apply the filter to for a matching endpoint. For HTTPEvent types this corresponds to an HTTP verb (GET, PUT, POST, DELETE...). -## Audit Log Format +## Example audit logs -Below are two audit log entries for a request made to `/v1/job/web/summary`. The -first entry is for the `OperationReceived` stage. The second entry is for the -`OperationComplete` stage and includes the contents of the `OperationReceived` -stage plus a `response` key. +The following audit log entries are for a request made to `/v1/job/web/summary`. +The first entry is for the `OperationReceived` stage. The second entry is for +the `OperationComplete` stage and includes the contents of the +`OperationReceived` stage plus a `response` key. ```json { diff --git a/website/content/docs/configuration/autopilot.mdx b/website/content/docs/configuration/autopilot.mdx index 53cb78c19dc..350d75ef068 100644 --- a/website/content/docs/configuration/autopilot.mdx +++ b/website/content/docs/configuration/autopilot.mdx @@ -1,17 +1,21 @@ --- layout: docs -page_title: autopilot Block - Agent Configuration +page_title: autopilot Block in Agent Configuration description: >- - The "autopilot" block configures the Nomad agent to configure Autopilot - behavior. + Configure settings for Nomad Autopilot features in the `autopilot` block of a Nomad agent configuration. Enable dead server cleanup, redundancy zones, and custom upgrades. Disable upgrade migration. Tune Raft settings for stable server introduction. --- -# `autopilot` Block +# `autopilot` Block in Agent Configuration -The `autopilot` block configures the Nomad agent to configure Autopilot behavior. -For more information about Autopilot, see the [Autopilot Guide](/nomad/tutorials/manage-clusters/autopilot). +This page provides reference information for configuring settings for Nomad +Autopilot features in the `autopilot` block of a Nomad agent configuration. +Enable dead server cleanup, redundancy zones, and custom upgrades. Disable +upgrade migration. Tune Raft settings for stable server introduction. + +Refer to the [Autopilot Guide](/nomad/tutorials/manage-clusters/autopilot) for +how to configure and use Autopilot. ```hcl autopilot { @@ -42,16 +46,17 @@ autopilot { cluster. Only takes effect if all servers are running Raft protocol version 3 or higher. Must be a duration value such as `30s`. -- `enable_redundancy_zones` `(bool: false)` - (Enterprise-only) Controls whether +- `enable_redundancy_zones` `(bool: false)` - Controls whether Autopilot separates servers into zones for redundancy, in conjunction with the [redundancy_zone](/nomad/docs/configuration/server#redundancy_zone) parameter. Only one server in each zone can be a voting member at one time. -- `disable_upgrade_migration` `(bool: false)` - (Enterprise-only) Disables Autopilot's +- `disable_upgrade_migration` `(bool: false)` - Disables Autopilot's upgrade migration strategy in Nomad Enterprise of waiting until enough newer-versioned servers have been added to the cluster before promoting any of them to voters. -- `enable_custom_upgrades` `(bool: false)` - (Enterprise-only) Specifies whether to +- `enable_custom_upgrades` `(bool: false)` - Specifies whether to enable using custom upgrade versions when performing migrations, in conjunction with - the [upgrade_version](/nomad/docs/configuration/server#upgrade_version) parameter. + the [upgrade_version](/nomad/docs/configuration/server#upgrade_version) + parameter. diff --git a/website/content/docs/configuration/client.mdx b/website/content/docs/configuration/client.mdx index bf4ef73f769..99f9baf83c0 100644 --- a/website/content/docs/configuration/client.mdx +++ b/website/content/docs/configuration/client.mdx @@ -1,17 +1,23 @@ --- layout: docs -page_title: client Block - Agent Configuration +page_title: client Block in Agent Configuration description: |- - The "client" block configures the Nomad agent to accept jobs as assigned by - the Nomad server, join the cluster, and specify driver-specific configuration. + Configure a Nomad client in the `client` block of a Nomad agent configuration. Enable a client, configure allocation directories, artifact and template behavior, networking, node pools, servers to join, garbage collection, workload behavior, client resources, chroot, host volumes, host network, and driver-specific behavior. --- -# `client` Block +# `client` Block in Agent Configuration -The `client` block configures the Nomad agent to accept jobs as assigned by -the Nomad server, join the cluster, and specify driver-specific configuration. +This page provides reference information for configuring a Nomad client in the +`client` block of a Nomad agent configuration. Enable a client, configure +allocation directories, artifact and template behavior, networking, node pools, +servers to join, garbage collection, workload behavior, client resources, +chroot, host volumes, host network, and driver-specific behavior. + +Refer to the [Set Server and Client Nodes](/nomad/docs/operations/nomad-agent) +and [Nomad Agent](/nomad/docs/commands/agent) pages to learn about the Nomad +agent process and how to configure the server and client nodes in your cluster. ```hcl client { @@ -130,8 +136,7 @@ client { - `server_join` ([server_join][server-join]: nil) - Specifies how the Nomad client will connect to Nomad servers. The `start_join` field is not supported on the client. The retry_join fields may directly specify - the server address or use go-discover syntax for auto-discovery. See the - documentation for more detail. + the server address or use go-discover syntax for auto-discovery. - `state_dir` `(string: "")` - Specifies the directory to use to store client state. When this parameter is empty, Nomad will generate the path using the @@ -254,11 +259,11 @@ Nomad never attempts to embed the `alloc_dir` in the chroot as doing so would ca ### `options` Parameters ~> Note: In Nomad 0.9 client configuration options for drivers were deprecated. -See the [plugin block][plugin-block] documentation for more information. +Refer to the [plugin block][plugin-block] documentation for more information. The following is not an exhaustive list of options for only the Nomad -client. To find the options supported by each individual Nomad driver, please -see the [drivers documentation](/nomad/docs/drivers). +client. To find the options supported by each individual Nomad driver, +refer to the [drivers documentation](/nomad/docs/drivers). - `"driver.allowlist"` `(string: "")` - Specifies a comma-separated list of allowlisted drivers. If specified, drivers not in the allowlist will be @@ -285,11 +290,11 @@ see the [drivers documentation](/nomad/docs/drivers). } ``` -- `"env.denylist"` `(string: see below)` - Specifies a comma-separated list of - environment variable keys not to pass to these tasks. Nomad passes the host - environment variables to `exec`, `raw_exec` and `java` tasks. If specified, - the defaults are overridden. If a value is provided, **all** defaults are - overridden (they are not merged). +- `"env.denylist"` `(string: refer to explanation)` - Specifies a + comma-separated list of environment variable keys not to pass to these tasks. + Nomad passes the host environment variables to `exec`, `raw_exec` and `java` + tasks. If specified, the defaults are overridden. If a value is provided, + **all** defaults are overridden (they are not merged). ```hcl client { @@ -312,10 +317,10 @@ see the [drivers documentation](/nomad/docs/drivers). GOOGLE_APPLICATION_CREDENTIALS ``` -- `"user.denylist"` `(string: see below)` - Specifies a comma-separated - denylist of usernames for which a task is not allowed to run. This only - applies if the driver is included in `"user.checked_drivers"`. If a value is - provided, **all** defaults are overridden (they are not merged). +- `"user.denylist"` `(string: refer to explanation)` - Specifies a + comma-separated denylist of usernames for which a task is not allowed to run. + This only applies if the driver is included in `"user.checked_drivers"`. If a + value is provided, **all** defaults are overridden (they are not merged). ```hcl client { @@ -332,10 +337,10 @@ see the [drivers documentation](/nomad/docs/drivers). Administrator ``` -- `"user.checked_drivers"` `(string: see below)` - Specifies a comma-separated - list of drivers for which to enforce the `"user.denylist"`. For drivers using - containers, this enforcement is usually unnecessary. If a value is provided, - **all** defaults are overridden (they are not merged). +- `"user.checked_drivers"` `(string: refer to explanation)` - Specifies a + comma-separated list of drivers for which to enforce the `"user.denylist"`. + For drivers using containers, this enforcement is usually unnecessary. If a + value is provided, **all** defaults are overridden (they are not merged). ```hcl client { @@ -412,9 +417,9 @@ see the [drivers documentation](/nomad/docs/drivers). - `disk` `(int: 0)` - Specifies the amount of disk to reserve, in MB. -- `reserved_ports` `(string: "")` - Specifies a comma-separated list of ports - to reserve on all fingerprinted network devices. Ranges can be specified by - using a hyphen separating the two inclusive ends. See also +- `reserved_ports` `(string: "")` - Specifies a comma-separated list of ports to + reserve on all fingerprinted network devices. Ranges can be specified by using + a hyphen separating the two inclusive ends. Refer to [`host_network`](#host_network-block) for reserving ports on specific host networks. @@ -766,7 +771,7 @@ client { This example shows a client configuration which customizes the metadata and node class. The scheduler can use this information while processing [constraints][metadata_constraint]. The metadata is completely user configurable; -the values below are for illustrative purposes only. +the values in the example are for illustrative purposes only. ```hcl client { diff --git a/website/content/docs/configuration/consul.mdx b/website/content/docs/configuration/consul.mdx index d375eb80b11..2735e5226ca 100644 --- a/website/content/docs/configuration/consul.mdx +++ b/website/content/docs/configuration/consul.mdx @@ -1,21 +1,27 @@ --- layout: docs -page_title: consul Block - Agent Configuration +page_title: consul Block in Agent Configuration description: |- - The "consul" block configures the Nomad agent's communication with - Consul for service discovery and key-value integration. When - configured, tasks can register themselves with Consul, and the Nomad cluster - can automatically bootstrap itself. + Configure Nomad server and client integration with Consul in the `consul` block of a Nomad agent configuration for service discovery and key-value integration. Configure cluster name, the Consul namespace, whether Nomad should advertize its services, certificates, tokens, security, health checks, auto join, and workload service and task identity. --- -# `consul` Block +# `consul` Block in Agent Configuration -The `consul` block configures the Nomad agent's communication with -[Consul][consul] for service discovery and key-value integration. When -configured, tasks can register themselves with Consul, and the Nomad cluster can -[automatically bootstrap][bootstrap] itself. +This page provides reference information for configuring Nomad server and client +integration with [Consul][consul] in the `consul` block of a Nomad agent +configuration for service discovery and key-value integration. Configure cluster +name, the Consul namespace, whether Nomad should advertize its services, +certificates, tokens, security, health checks, auto join, and workload service +and task identity. + +When configured, tasks can register themselves with Consul, and the Nomad +cluster can [automatically bootstrap][bootstrap] itself. + +Refer to the [Service Discovery on Nomad +tutorial](/nomad/tutorials/service-discovery) for how to use Consul's service +discovery. ```hcl consul { @@ -162,7 +168,7 @@ agents with [`client.enabled`][] set to `true`. Consul does not support incoming TLS verification of Envoy sidecars. You should set `tls.grpc.verify_incoming = false` in your - Consul configuration when using Connect. See + Consul configuration when using Connect. Refer to [Consul/#13088](https://github.com/hashicorp/consul/issues/13088) for more details. @@ -241,9 +247,10 @@ jobs to use Workload Identity without modifying the job specification and resubmitting them. The recommended configuration for `service_identity` and `task_identity` is as -follows. See [Migrating to Using Workload Identity with Consul][] for details on -how to configure Consul to accept these identities. Note that the `ttl` field -here refers to the TTL of the Nomad identity and not the Consul token. +follows. Refer to [Migrating to Using Workload Identity with Consul][] for +details on how to configure Consul to accept these identities. Note that the +`ttl` field here refers to the TTL of the Nomad identity and not the Consul +token. ```hcl consul { @@ -394,8 +401,9 @@ permissions. Nomad requires `agent:read` permissions. In order to use the `consul_namespace` feature, Nomad will need a token generated in Consul's default namespace. That token should be created with `agent:read` as well as a `namespace` block with the other relevant permissions for running Nomad -in the intended namespace. The Consul policy below shows an example policy -configuration for a Nomad server: +in the intended namespace. + +This Consul policy shows an example policy configuration for a Nomad server. ```hcl agent_prefix "" { diff --git a/website/content/docs/configuration/index.mdx b/website/content/docs/configuration/index.mdx index 3c70ce061a5..9de3ecefdce 100644 --- a/website/content/docs/configuration/index.mdx +++ b/website/content/docs/configuration/index.mdx @@ -1,17 +1,24 @@ --- layout: docs -page_title: Agent Configuration -description: Learn about the configuration options available for the Nomad agent. +page_title: Nomad Agent Configuration +description: This section contains reference information for configuring Nomad agents. Learn how Nomad loads and merges multiple configuration files. Configure networking and advertise addresses, Nomad regions and datacenters, data directories, Consul integration, handshake limits, connections per client, logging, plugins, Sentinel policies, security, update check behavior, and Vault integration. Enable debugging, write to syslog, leave on interrupt or terminate, and cross-origin resource sharing (CORS). --- -# Nomad Configuration +# Nomad Agent Configuration -Nomad agents have a variety of parameters that can be specified via -configuration files or command-line flags. Configuration files are written in -[HCL][hcl]. Nomad can read and combine parameters from multiple configuration -files or directories to configure the Nomad agent. +This page provides an overview of reference information for configuring Nomad +agents. Learn how Nomad loads and merges multiple configuration files. Configure +networking and advertise addresses, Nomad regions and data centers, data +directories, Consul integration, handshake limits, connections per client, +logging, plugins, Sentinel policies, security, update check behavior, and Vault +integration. Enable debugging, writing to syslog, leave on interrupt or +terminate, and cross-origin resource sharing (CORS). -## Load Order and Merging +Write configuration files in [HCL][hcl] or specify parameters as command-line +flags. Nomad can read and combine parameters from multiple configuration files +or directories to configure the Nomad agent. + +## Configuration File Load Order and Merging The Nomad agent supports multiple configuration files, which can be provided using the `-config` CLI flag. The flag can accept either a file or folder. In @@ -81,11 +88,11 @@ testing. - `acl` `(`[`ACL`]`: nil)` - Specifies configuration which is specific to ACLs. -- `addresses` `(Addresses: see below)` - Specifies the bind address for +- `addresses` `(Addresses: refer to explanation)` - Specifies the bind address for individual network services. Any values configured in this block take precedence over the default [bind_addr](#bind_addr). These values should be specified in IP format without a port (ex. `"0.0.0.0"`). To set the port, - see the [`ports`](#ports) field. The values support [go-sockaddr/template + refer to the [`ports`](#ports) field. The values support [go-sockaddr/template format][go-sockaddr/template]. - `http` - The address the HTTP server is bound to. This is the most @@ -99,7 +106,7 @@ testing. listener will be exposed on this address. Should be exposed only to other cluster members if possible. -- `advertise` `(Advertise: see below)` - Specifies the advertise address for +- `advertise` `(Advertise: refer to explanation)` - Specifies the advertise address for individual network services. This can be used to advertise a different address to the peers of a server or a client node to support more complex network configurations such as NAT. This configuration is optional, and defaults to @@ -286,8 +293,8 @@ testing. configured. The key of the block is the plugin's executable name relative to the [plugin_dir](#plugin_dir). -- `ports` `(Port: see below)` - Specifies the network ports used for different - services required by the Nomad agent. +- `ports` `(Port: refer to explanation)` - Specifies the network ports used for + different services required by the Nomad agent. - `http` - The port used to run the HTTP server. @@ -357,7 +364,7 @@ license will be reloaded from the file on a configuration reload. If the Nomad agent receives a `SIGHUP` during initialization, it may crash -(see [GH-3885]). Ensure that the Nomad agent is able to receive RPC traffic +(refer to [GH-3885]). Ensure that the Nomad agent is able to receive RPC traffic before attempting to reload its configuration. ## Examples diff --git a/website/content/docs/configuration/keyring/awskms.mdx b/website/content/docs/configuration/keyring/awskms.mdx index 621a41c5f03..70bfa1cd6bd 100644 --- a/website/content/docs/configuration/keyring/awskms.mdx +++ b/website/content/docs/configuration/keyring/awskms.mdx @@ -1,16 +1,20 @@ --- layout: docs -page_title: AWS KMS - Keyring - Configuration +page_title: AWS Key Management Service (KMS) Keyring Configuration description: |- - The AWS KMS keyring configures Nomad to use AWS KMS as the key material - wrapping mechanism. + Configure an AWS Key Management Service (KMS) keyring in the `keyring "awskms"` block of a Nomad agent configuration. Configure AWS region, KMS API endpoint, KMA key ID, and AWS authentication. Learn how Nomad supports KMS root key rotation. --- -# `awskms` keyring +# AWS Key Management Service (KMS) Keyring Configuration + +This page provides reference information for configuring an AWS Key Management +Service (KMS) keyring in the `keyring "awskms"` block of a Nomad agent +configuration. Configure AWS region, KMS API endpoint, KMA key ID, and AWS +authentication. Learn how Nomad supports KMS root key rotation. The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This -example shows configuring AWS KMS keyring through the Nomad configuration file -by providing all the required values. +example shows configuring an AWS KMS keyring through the Nomad configuration +file by providing all the required values. ```hcl keyring "awskms" { diff --git a/website/content/docs/configuration/keyring/azurekeyvault.mdx b/website/content/docs/configuration/keyring/azurekeyvault.mdx index 7addbf2b1de..7819d1e1968 100644 --- a/website/content/docs/configuration/keyring/azurekeyvault.mdx +++ b/website/content/docs/configuration/keyring/azurekeyvault.mdx @@ -1,19 +1,24 @@ --- layout: docs -page_title: Azure Key Vault - Keyring - Configuration +page_title: Azure Key Vault Keyring Configuration description: >- - The Azure Key Vault keyring configures Nomad to use Azure Key Vault as the key material - wrapping mechanism. + Configure an Azure Key Vault keyring in the `keyring "azurekeyvault"` block of a Nomad agent configuration. Configure the Key Vault resource's DNS, Azure Cloud environment variables and API endpoints, and vault and key names. Learn how Nomad supports rotating keys defined in Azure Key Vault. --- -# `azurekeyvault` keyring +# Azure Key Vault Keyring Configuration -The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This -example shows configuring Azure Key Vault keyring through the Nomad -configuration file by providing all the required values. +This page provides reference information for configuring an Azure Key Vault +keyring in the `keyring "azurekeyvault"` block of a Nomad agent +configuration. Configure the Key Vault resource's DNS, Azure Cloud environment +API endpoints, vault and key names, tenant and client IDs, and the client secret. Learn how Nomad supports rotating keys defined in Azure Key +Vault. + +The Azure Key Vault keyring configures Nomad to use Azure Key Vault to wrap its +keyring. This example shows configuring Azure Key Vault keyring through the +Nomad configuration file by providing all the required values. ```hcl -seal "azurekeyvault" { +keyring "azurekeyvault" { active = true name = "example" @@ -52,7 +57,7 @@ These parameters apply to the `keyring` block in the Nomad configuration file: - `key_name` `(string: )`: The Key Vault key to use for encryption and decryption. -- `resource` `(string: "vault.azure.net")`: The AZ KeyVault resource's DNS +- `resource` `(string: "vault.azure.net")`: The Key Vault resource's DNS Suffix to connect to. Alternately specify via the `AZURE_AD_RESOURCE` environment variable. Needs to be changed to connect to Azure's Managed HSM KeyVault instance type. diff --git a/website/content/docs/configuration/keyring/gcpckms.mdx b/website/content/docs/configuration/keyring/gcpckms.mdx index 87ebf0734b1..00ad5ff9157 100644 --- a/website/content/docs/configuration/keyring/gcpckms.mdx +++ b/website/content/docs/configuration/keyring/gcpckms.mdx @@ -1,13 +1,17 @@ --- layout: docs -page_title: GCP Cloud KMS - Keyrings - Configuration +page_title: Google Cloud Platform Key Management Service Keyring Configuration description: >- - The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS as the keyring - wrapping mechanism. + Configure a Google Cloud Platform Key Management Service (GCP Cloud KMS) keyring in the `keyring "gcpckms"` block of a Nomad agent configuration. Configure GCP credentials, project, region, key ring, and crypto key. Learn how Nomad supports rotating keys defined in GCP Cloud KMS. --- -# `gcpckms` keyring +# Google Cloud Platform Key Management Service Keyring Configuration +This page provides reference information for configuring a Google Cloud Platform +Key Management Service (GCP Cloud KMS) keyring in the `keyring "gcpckms"` block +of a Nomad agent configuration. Configure GCP credentials, project, region, key +ring, and crypto key. Learn how Nomad supports rotating keys defined in GCP +Cloud KMS. The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS to wrap its keyring. This example shows configuring GCP Cloud KMS keyring through the Nomad @@ -41,9 +45,9 @@ These parameters apply to the `keyring` stanza in the Nomad configuration file: - `region` `(string: )`: The GCP region/location where the key ring lives. Alternately specify via the `GOOGLE_REGION` environment variable. -- `key_ring` `(string: )`: The GCP CKMS key ring to use. +- `key_ring` `(string: )`: The GCP KMS key ring to use. -- `crypto_key` `(string: )`: The GCP CKMS crypto key to use for +- `crypto_key` `(string: )`: The GCP KMS crypto key to use for encryption and decryption. ## Authentication & permissions diff --git a/website/content/docs/configuration/keyring/index.mdx b/website/content/docs/configuration/keyring/index.mdx index aefe410f27a..b2cdef9bd6f 100644 --- a/website/content/docs/configuration/keyring/index.mdx +++ b/website/content/docs/configuration/keyring/index.mdx @@ -1,14 +1,19 @@ --- layout: docs -page_title: keyring Block - Agent Configuration +page_title: keyring Block in Agent Configuration description: >- - The "keyring" block configures the Nomad servers keyring decryption behavior. + Configure keyring protection behavior in the `keyring` block of a Nomad agent configuration. Enable a keyring and configure a name. Learn how to configure keyring high availability (HA) and migrate keyrings. --- -# `keyring` Block +# `keyring` Block in Agent Configuration +This page provides reference information for configuring keyring protection +behavior in the `keyring` block of a Nomad agent configuration. Enable a keyring +and configure a name. Learn how to configure keyring high availability (HA) and +migrate keyrings. + The `keyring` block configures how the Nomad server protects the keyring used for encrypting [variables][] and signing [workload identities][]. By default, Nomad encrypts the key material with a unique key encryption key (KEK) that is @@ -68,9 +73,7 @@ keyring list`][keyring_list_cmd]. ## High Availability - - This functionality only exists in Nomad Enterprise. - + Keyring high availability provides the means to configure multiple active `keyring` blocks, in order to have resilience against an outage of an external diff --git a/website/content/docs/configuration/keyring/transit.mdx b/website/content/docs/configuration/keyring/transit.mdx index 05bb1a0a9ac..544ee23f9dd 100644 --- a/website/content/docs/configuration/keyring/transit.mdx +++ b/website/content/docs/configuration/keyring/transit.mdx @@ -1,15 +1,20 @@ --- layout: docs -page_title: Vault Transit - Keyring - Configuration +page_title: Vault Transit Keyring Configuration description: |- - The Transit keyring configures Nomad to use Vault's Transit Secret Engine as - the key material wrapping mechanism. + Configure a Vault transit secrets engine keyring in the `keyring "transit"` block of a Nomad agent configuration. Configure the address to the Vault cluster, key name, mount path, namespace, TLS authentication, and whether to disable Vault token automatic renewal. Learn how Nomad supports rotating keys defined in Vault's transit secrets engine. --- -# `transit` keyring +# Vault Transit Keyring Configuration -The Vault transit keyring configures Nomad to use Vault's Transit Secret Engine -to wrap its keyring. This example shows configuring Vault Transit through the +This page provides reference information for configuring a Vault transit secrets +engine keyring in the `keyring "transit"` block of a Nomad agent configuration. +Configure the address to the Vault cluster, key name, mount path, namespace, TLS +authentication, and whether to disable Vault token automatic renewal. Learn how +Nomad supports rotating keys defined in Vault's transit secrets engine. + +The Vault transit keyring configures Nomad to use Vault's transit secrets engine +to wrap its keyring. This example shows configuring Vault transit through the Nomad configuration file by providing all the required values. ```hcl @@ -119,9 +124,9 @@ Other considerations for the token used: ## Key rotation -This keyring supports key rotation using the Transit Secret Engine's key -rotation endpoints. Refer to [Vault docs][rotate_doc]. Old keys must not be -disabled or deleted and are used to decrypt older data. +This keyring supports key rotation using Vault's transit secrets engine's key +rotation endpoints. Refer to [Vault docs][rotate_doc] for details. Old keys must +not be disabled or deleted and are used to decrypt older data. [orphan token]: /vault/docs/concepts/tokens#token-hierarchies-and-orphan-tokens [periodic token]: /vault/docs/concepts/tokens#periodic-tokens diff --git a/website/content/docs/configuration/plugin.mdx b/website/content/docs/configuration/plugin.mdx index 92fa1842fbb..d3d5d4d4a8f 100644 --- a/website/content/docs/configuration/plugin.mdx +++ b/website/content/docs/configuration/plugin.mdx @@ -1,14 +1,19 @@ --- layout: docs -page_title: plugin Block - Agent Configuration -description: The "plugin" block is used to configure a Nomad plugin. +page_title: plugin Block in Agent Configuration +description: Configure task driver and device driver plugins in the `plugin` block of a Nomad agent configuration. Specify arguments to pass to the plugin. Configure values specific to the plugin. --- -# `plugin` Block +# `plugin` Block in Agent Configuration -The `plugin` block is used to configure plugins. +This page provides reference information for configuring task driver and device +driver plugins in the `plugin` block of a Nomad agent configuration. Specify +arguments to pass to the plugin. Configure values specific to the plugin. + +Refer to the [Nomad plugins guide](/nomad/plugins) for details on specific task +driver and device plugins. ```hcl plugin "example-plugin" { diff --git a/website/content/docs/configuration/reporting.mdx b/website/content/docs/configuration/reporting.mdx index f89c6013f54..d00fdaaa428 100644 --- a/website/content/docs/configuration/reporting.mdx +++ b/website/content/docs/configuration/reporting.mdx @@ -1,21 +1,24 @@ --- layout: docs -page_title: reporting Block - Agent Configuration +page_title: reporting Block in Agent Configuration description: >- - The "reporting" block configures the Nomad agents automated license - utilization reporting. + Enable automated license utilization reporting in the `reporting` block of a Nomad agent configuration. Configuration applies to agents running Nomad Enterprise with server mode enabled. --- -# `reporting` Block +# `reporting` Block in Agent Configuration + -The `reporting` block configures the Nomad agents automated license utilization -reporting. This is an Enterprise-only feature and the configuration applies to -agents running with [server mode enabled][server_mode_enabled]. +This page provides reference information for enabling automated license +utilization reporting in the `reporting` block of a Nomad agent configuration. -For more information about automated license utilization reporting, please see the -[guide][automated_license_utilization_reporting]. +Configuration applies to agents running with [server mode +enabled][server_mode_enabled]. + +Refer to the [Automated license utilization reporting +guide][automated_license_utilization_reporting] for which ports to open and what +data is shared. ```hcl reporting { diff --git a/website/content/docs/configuration/search.mdx b/website/content/docs/configuration/search.mdx index dacdf56c5fa..526e0d11c56 100644 --- a/website/content/docs/configuration/search.mdx +++ b/website/content/docs/configuration/search.mdx @@ -1,13 +1,12 @@ --- layout: docs -page_title: search Block - Agent Configuration +page_title: search Block in Agent Configuration sidebar_title: search description: >- - The "search" block specifies configuration for the search API provided - by the Nomad servers. + Configure the Nomad server search API in the `search` block of a Nomad agent configuration. Enable fuzzy searching. Configure the minimum size of the search term, the maximum number of Nomad objects to search through per context type, and the max number of matching results. --- -# `search` Block +# `search` Block in Agent Configuration - ]} /> -The `search` block specifies configuration for the search API provided by the -Nomad servers. +This page provides reference information for configuring the Nomad server search +API in the `search` block of a Nomad agent configuration. Enable fuzzy +searching. Configure the minimum size of the search term, the maximum number of +Nomad objects to search through per context type, and the max number of matching results. ```hcl server { diff --git a/website/content/docs/configuration/sentinel.mdx b/website/content/docs/configuration/sentinel.mdx index 85085ab869b..227d57fad14 100644 --- a/website/content/docs/configuration/sentinel.mdx +++ b/website/content/docs/configuration/sentinel.mdx @@ -1,16 +1,19 @@ --- layout: docs -page_title: sentinel Block - Agent Configuration +page_title: sentinel Block in Agent Configuration description: >- - The "sentinel" block configures the Nomad agent for Sentinel policies and - tune various parameters. + Configure Sentinel policy engine behavior in the "sentinel" block of a Nomad agent configuration. Configure the path to the plugin that Nomad uses to import Sentinel policies and specify arguments to pass to that plugin on startup. --- -# `sentinel` Block +# `sentinel` Block in Agent Configuration + -The `sentinel` block configures the Sentinel policy engine and tunes various parameters. +This page provides reference information for configuring the Sentinel policy +engine in the `sentinel` block of a Nomad agent configuration. Configure the +path to the plugin that Nomad uses to import Sentinel policies and specify +arguments to pass to that plugin on startup. ```hcl sentinel { @@ -32,3 +35,17 @@ sentinel { - `path` `(string: "")` - Specifies the path to the import plugin. Must be executable by Nomad. - `args` `(array: [])` - Specifies arguments to pass to the plugin when starting it. + +## Resources + +Refer to these resources for details on using Sentinel policies with +Nomad: + +- [Governance and policy on + Nomad](/nomad/tutorials/governance-and-policy/governance-and-policy) +- [Sentinel policies](/nomad/tutorials/governance-and-policy/sentinel) +- [Sentinel policy + reference](https://developer.hashicorp.com/nomad/docs/enterprise/sentinel) + + + diff --git a/website/content/docs/configuration/server.mdx b/website/content/docs/configuration/server.mdx index 8ec3b1caae9..afc69dd26f3 100644 --- a/website/content/docs/configuration/server.mdx +++ b/website/content/docs/configuration/server.mdx @@ -1,19 +1,22 @@ --- layout: docs -page_title: server Block - Agent Configuration +page_title: server Block in Agent Configuration description: |- - The "server" block configures the Nomad agent to operate in server mode to - participate in scheduling decisions, register with service discovery, handle - join failures, and more. + Configure Nomad agent server mode in the `server` block of a Nomad agent configuration. Server mode lets the agent participate in scheduling decisions, register with service discovery, and handle join failures. Configure bootstrapping, authoritative region, redundancy zone, data directory, Nomad cluster behavior, client heartbeat period, schedulers, garbage collection, Raft and Raft's BoltDB store, OIDC for workload identity, leader plan rejection, as well as job priority, job source content size, and tracked job versions. --- -# `server` Block +# `server` Block in Agent Configuration -The `server` block configures the Nomad agent to operate in server mode to -participate in scheduling decisions, register with service discovery, handle -join failures, and more. +This page provides reference information for configuring Nomad agent server mode +in the `server` block of a Nomad agent configuration. Server mode lets the agent +participate in scheduling decisions, register with service discovery, and handle +join failures. Configure bootstrapping, authoritative region, redundancy zone, +data directory, Nomad cluster behavior, client heartbeat period, schedulers, +garbage collection, Raft and Raft's BoltDB store, OIDC for workload identity, +and leader plan rejection, as well as job priority, job source content size, and +tracked job versions. ```hcl server { @@ -35,7 +38,7 @@ server { Non-authoritative regions will replicate from the authoritative to act as a mirror. By default, the local region is assumed to be authoritative. Setting `authoritative_region` assumes that ACLs have been bootstrapped in the - authoritative region. See [Configure for multiple regions][] in the ACLs + authoritative region. Refer to [Configure for multiple regions][] in the ACLs tutorial. - `bootstrap_expect` `(int: required)` - Specifies the number of server nodes to @@ -71,7 +74,7 @@ server { that to encrypt Nomad server's gossip protocol, this option only needs to be provided once on each agent's initial startup sequence. If it is provided after Nomad has been initialized with an encryption key, then the provided key - is ignored and a warning will be displayed. See the [encryption + is ignored and a warning will be displayed. Refer to the [encryption documentation][encryption] for more details on this option and its impact on the cluster. @@ -127,31 +130,33 @@ server { expired ACL token before it is eligible for garbage collection. This is specified using a label suffix like "30s" or "1h". -- `default_scheduler_config` ([scheduler_configuration][update-scheduler-config]: - nil) - Specifies the initial default scheduler config when - bootstrapping cluster. The parameter is ignored once the cluster is bootstrapped or - value is updated through the [API endpoint][update-scheduler-config]. See [the - example section](#configuring-scheduler-config) for more details +- `default_scheduler_config` + ([scheduler_configuration][update-scheduler-config]: nil) - + Specifies the initial default scheduler config when bootstrapping cluster. The + parameter is ignored once the cluster is bootstrapped or value is updated + through the [API endpoint][update-scheduler-config]. Refer to [the example + section](#configuring-scheduler-config) for more details - `heartbeat_grace` `(string: "10s")` - Specifies the additional time given beyond the heartbeat TTL of Clients to account for network and processing delays and clock skew. This is specified using a label suffix like "30s" or - "1h". See [Client Heartbeats](#client-heartbeats) below for details. + "1h". Refer to the [Client Heartbeats](#client-heartbeats) section for + details. - `min_heartbeat_ttl` `(string: "10s")` - Specifies the minimum time between Client heartbeats. This is used as a floor to prevent excessive updates. This - is specified using a label suffix like "30s" or "1h". See [Client - Heartbeats](#client-heartbeats) below for details. + is specified using a label suffix like "30s" or "1h". Refer to the [Client + Heartbeats](#client-heartbeats) section for details. -- `failover_heartbeat_ttl` `(string: "5m")` - The time by which all Clients - must heartbeat after a Server leader election. This is specified using a label - suffix like "30s" or "1h". See [Client Heartbeats](#client-heartbeats) below - for details. +- `failover_heartbeat_ttl` `(string: "5m")` - The time by which all Clients must + heartbeat after a Server leader election. This is specified using a label + suffix like "30s" or "1h". Refer to the [Client + Heartbeats](#client-heartbeats) section for details. - `max_heartbeats_per_second` `(float: 50.0)` - Specifies the maximum target rate of heartbeats being processed per second. This allows the TTL to be - increased to meet the target rate. See [Client Heartbeats](#client-heartbeats) - below for details. + increased to meet the target rate. Refer to the [Client + Heartbeats](#client-heartbeats) section for details. - `non_voting_server` `(bool: false)` - (Enterprise-only) Specifies whether this server will act as a non-voting member of the cluster to help provide @@ -188,11 +193,12 @@ server { - `raft_multiplier` `(int: 1)` - An integer multiplier used by Nomad servers to scale key Raft timing parameters. Omitting this value or setting it to 0 uses - default timing described below. Lower values are used to tighten timing and - increase sensitivity while higher values relax timings and reduce sensitivity. - Tuning this affects the time it takes Nomad to detect leader failures and to - perform leader elections, at the expense of requiring more network and CPU - resources for better performance. The maximum allowed value is 10. + default timing described in the following paragraph. Lower values are used to + tighten timing and increase sensitivity while higher values relax timings and + reduce sensitivity. Tuning this affects the time it takes Nomad to detect + leader failures and to perform leader elections, at the expense of requiring + more network and CPU resources for better performance. The maximum allowed + value is 10. By default, Nomad will use the highest-performance timing, currently equivalent to setting this to a value of 1. Increasing the timings makes leader election @@ -226,7 +232,7 @@ server { - `redundancy_zone` `(string: "")` - (Enterprise-only) Specifies the redundancy zone that this server will be a part of for Autopilot management. For more - information, see the [Autopilot Guide](/nomad/tutorials/manage-clusters/autopilot). + information, refer to the [Autopilot Guide](/nomad/tutorials/manage-clusters/autopilot). - `rejoin_after_leave` `(bool: false)` - Specifies if Nomad will ignore a previous leave and attempt to rejoin the cluster when starting. By default, @@ -251,11 +257,11 @@ server { - `server_join` ([server_join][server-join]: nil) - Specifies how the Nomad server will connect to other Nomad servers. The `retry_join` fields may directly specify the server address or use go-discover syntax for - auto-discovery. See the [server_join documentation][server-join] for more detail. + auto-discovery. Refer to the [server_join documentation][server-join] for more detail. - `upgrade_version` `(string: "")` - A custom version of the format X.Y.Z to use in place of the Nomad version when custom upgrades are enabled in Autopilot. - For more information, see the [Autopilot Guide](/nomad/tutorials/manage-clusters/autopilot). + For more information, refer to the [Autopilot Guide](/nomad/tutorials/manage-clusters/autopilot). - `search` ([search][search]: nil) - Specifies configuration parameters for the Nomad search API. @@ -292,7 +298,7 @@ server { succeeds. After one succeeds, no further addresses will be contacted. This is useful for cases where we know the address will become available eventually. Use `retry_join` with an array as a replacement for `start_join`, **do not use - both options**. See the [server_join][server-join] + both options**. Refer to the [server_join][server-join] section for more information on the format of the string. This field is deprecated in favor of the [server_join block][server-join]. @@ -307,7 +313,7 @@ server { - `start_join` `(array: [])` - Specifies a list of server addresses to join on startup. If Nomad is unable to join with any of the specified - addresses, agent startup will fail. See the [server address + addresses, agent startup will fail. Refer to the [server address format](/nomad/docs/configuration/server_join#server-address-format) section for more information on the format of the string. This field is deprecated in favor of the [server_join block][server-join]. @@ -370,7 +376,7 @@ server { ### Automatic Bootstrapping The Nomad servers can automatically bootstrap if Consul is configured. For a -more detailed explanation, please see the +more detailed explanation, refer to the [automatic Nomad bootstrapping documentation](/nomad/tutorials/manage-clusters/clustering). ### Restricting Schedulers @@ -479,7 +485,7 @@ simply adds the `heartbeat_grace` parameter to the TTL Clients are given. | 100 | 10s - 20s | 20s - 30s | yes | | 1000 | 20s - 40s | 30s - 50s | yes | | 5000 | 100s - 200s | 110s - 210s | yes | -| 10000 | 200s - 400s | 210s - 410s | NO (see below) | +| 10000 | 200s - 400s | 210s - 410s | NO | Regardless of size, all clients will have a Server TTL of `failover_heartbeat_ttl` after a leader election. It should always be larger diff --git a/website/content/docs/configuration/server_join.mdx b/website/content/docs/configuration/server_join.mdx index 74f4dbb2f25..f01165f4cbc 100644 --- a/website/content/docs/configuration/server_join.mdx +++ b/website/content/docs/configuration/server_join.mdx @@ -1,12 +1,11 @@ --- layout: docs -page_title: server_join Block - Agent Configuration +page_title: server_join Block in Agent Configuration description: >- - The "server_join" block specifies how the Nomad agent will discover and - connect to Nomad servers. + Configure how Nomad agents discover and connect to Nomad servers in Amazon, Microsoft, and Google clouds as well as on-prem. Use the`server_join` block to configure the list of servers to join, retry interval, and max rejoin attempts. --- -# `server_join` Block +# `server_join` Block in Agent Configuration - ]} /> -The `server_join` block specifies how the Nomad agent will discover and connect -to Nomad servers. +This page provides reference information for configuring how Nomad agents +discover and connect to Nomad servers in Amazon, Microsoft, and Google +clouds as well as on-prem. Use the`server_join` block to configure the list of +servers to join, retry interval, and max rejoin attempts. ```hcl server_join { @@ -74,7 +75,7 @@ server_join { } ``` - See [server address format](#server-address-format) for more information + Refer to [server address format](#server-address-format) for more information about expected server address formats and [Cloud Auto-join](#cloud-auto-join) for more information on expected Cloud Auto-join formats. @@ -141,7 +142,7 @@ nomad-01.company.local => nomad-01.company.local:4648 ### Via the go-discover interface `retry_join` accepts a unified interface using the [go-discover](https://github.com/hashicorp/go-discover) library for doing -automated cluster joining using cloud provider metadata. See [Cloud +automated cluster joining using cloud provider metadata. Refer to [Cloud Auto-join](#cloud-auto-join) for more information. ``` @@ -164,7 +165,8 @@ supported by `go-discover`, use `go-netaddrs`. `go-discover` configurations are prefixed with `provider=`. The following sections describe the Cloud Auto-join `retry_join` options that are specific -to a subset of supported cloud providers. For information on all providers, see further +to a subset of supported cloud providers. For information on all providers, +refer to further documentation in [go-discover](https://github.com/hashicorp/go-discover). #### Amazon EC2 @@ -183,10 +185,12 @@ region which have the given `tag_key` and `tag_value`. - `tag_value` (required) - the value of the tag to auto-join on. - `region` (optional) - the AWS region to authenticate in. - `addr_type` (optional) - the type of address to discover: `private_v4`, `public_v4`, `public_v6`. Default is `private_v4`. (>= 1.0) -- `access_key_id` (optional) - the AWS access key for authentication (see below for more information about authenticating). -- `secret_access_key` (optional) - the AWS secret access key for authentication (see below for more information about authenticating). +- `access_key_id` (optional) - the AWS access key for authentication. Refer to + the following Authentication and Precedence section for details. +- `secret_access_key` (optional) - the AWS secret access key for authentication. + Refer to the following Authentication and Precedence section for details. -##### Authentication & Precedence +##### Authentication and Precedence - Static credentials `access_key_id=... secret_access_key=...` - Environment variables (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) @@ -247,9 +251,10 @@ project which have the given `tag_value`. - `tag_value` (required) - the value of the tag to auto-join on. - `project_name` (optional) - the name of the project to auto-join on. Discovered if not set. - `zone_pattern` (optional) - the list of zones can be restricted through an RE2 compatible regular expression. If omitted, servers in all zones are returned. -- `credentials_file` (optional) - the credentials file for authentication. See below for more information. +- `credentials_file` (optional) - the credentials file for authentication. Refer + to the following Authentication and Precedence section for more information. -##### Authentication & Precedence +##### Authentication and Precedence - Use credentials from `credentials_file`, if provided. - Use JSON file from `GOOGLE_APPLICATION_CREDENTIALS` environment variable. @@ -273,7 +278,7 @@ Commands run by `go-netaddrs` must return a list of space-delimited IPv4 or IPv6 addresses and exit with code `0` on success and non-zero on failure. You can refer to the executable by its absolute file system path, or by -the executable's name if it can be found on the Nomad agent's PATH. See +the executable's name if it can be found on the Nomad agent's PATH. Refer to [executables in the current directory](https://pkg.go.dev/os/exec#hdr-Executables_in_the_current_directory) for more details on the lookup behavior. diff --git a/website/content/docs/configuration/telemetry.mdx b/website/content/docs/configuration/telemetry.mdx index 2899580b6ee..c065dcb8421 100644 --- a/website/content/docs/configuration/telemetry.mdx +++ b/website/content/docs/configuration/telemetry.mdx @@ -1,17 +1,18 @@ --- layout: docs -page_title: telemetry Block - Agent Configuration +page_title: telemetry Block in Agent Configuration description: |- - The "telemetry" block configures Nomad's publication of metrics and telemetry - to third-party systems. + Configure Nomad telemetry behavior in the `telemetry` block of a Nomad agent configuration. Configure Nomad's publication of metrics and telemetry to Statsite, StatsD, DataDog, Prometheus, and Apica (Circonus). --- -# `telemetry` Block +# `telemetry` Block in Agent Configuration -The `telemetry` block configures Nomad's publication of metrics and telemetry -to third-party systems. +This page provides reference information for configuring Nomad telemetry +behavior in the `telemetry` block of a Nomad agent configuration. Configure +Nomad's publication of metrics and telemetry to [Statsite], [StatsD], [DataDog], +[Prometheus], and [Apica (Circonus)][Apica]. ```hcl telemetry { @@ -20,9 +21,9 @@ telemetry { } ``` -This section of the documentation only covers the configuration options for +This section of the documentation only covers the configuration options for the `telemetry` block. To understand the architecture and metrics themselves, -please see the [Telemetry guide](/nomad/docs/operations/monitoring-nomad). +refer to the [Telemetry guide](/nomad/docs/operations/monitoring-nomad). ## `telemetry` Parameters @@ -99,8 +100,7 @@ The following options are available on all telemetry configurations. ### `statsite` -These `telemetry` parameters apply to -[statsite](https://github.com/armon/statsite). +These `telemetry` parameters apply to [Statsite]. - `statsite_address` `(string: "")` - Specifies the address of a statsite server to forward metrics data to. @@ -113,8 +113,7 @@ telemetry { ### `statsd` -These `telemetry` parameters apply to -[statsd](https://github.com/etsy/statsd). +These `telemetry` parameters apply to [StatsD]. - `statsd_address` `(string: "")` - Specifies the address of a statsd server to forward metrics to. @@ -127,8 +126,7 @@ telemetry { ### `datadog` -These `telemetry` parameters apply to -[DataDog statsd](https://github.com/DataDog/datadog-agent). +These `telemetry` parameters apply to [DataDog]. - `datadog_address` `(string: "")` - Specifies the address of a DataDog statsd server to forward metrics to. @@ -146,15 +144,14 @@ telemetry { ### `prometheus` -These `telemetry` parameters apply to [Prometheus](https://prometheus.io). +These `telemetry` parameters apply to [Prometheus]. - `prometheus_metrics` `(bool: false)` - Specifies whether the agent should make Prometheus formatted metrics available at `/v1/metrics?format=prometheus`. -### `circonus` +### `circonus` (Apica) -These `telemetry` parameters apply to -[Circonus](http://circonus.com/). +These `telemetry` parameters apply to [Apica], formerly Circonus. Apica acquired Circonus in 2024. - `circonus_api_token` `(string: "")` - Specifies a valid Circonus API Token used to create/manage check. If provided, metric management is enabled. @@ -213,3 +210,10 @@ These `telemetry` parameters apply to best use of this is to as a hint for which broker should be used based on _where_ this particular instance is running (e.g. a specific geographic location or datacenter, dc:sfo). + + +[Statsite]: https://github.com/armon/statsite +[StatsD]: https://github.com/etsy/statsd +[DataDog]: https://github.com/DataDog/datadog-agent +[Prometheus]: https://prometheus.io +[Apica]: https://www.apica.io/ diff --git a/website/content/docs/configuration/tls.mdx b/website/content/docs/configuration/tls.mdx index f9b808f8ae7..2ecd4257bf0 100644 --- a/website/content/docs/configuration/tls.mdx +++ b/website/content/docs/configuration/tls.mdx @@ -1,21 +1,22 @@ --- layout: docs -page_title: tls Block - Agent Configuration +page_title: tls Block in Agent Configuration description: |- - The "tls" block configures Nomad's TLS communication via HTTP and RPC to - enforce secure cluster communication between servers and clients. + Configure secure communication in the `tls` block of a Nomad agent configuration. Enable TLS on Raft traffic and RFC and HTTP endpoints. Add TLS cipher suites and paths to certificates and key files. Specify the TLS version. Require client certificates for all incoming HTTPS requests and the server name on all outgoing TLS connections. --- -# `tls` Block +# `tls` Block in Agent Configuration -The `tls` block configures Nomad's TLS communication via HTTP and RPC to enforce -secure cluster communication between servers, clients, and between. Note that in -most cases, this is mutual TLS (mTLS) where both ends of the connection -authenticate each other. The Nomad documentation will typically use "TLS" to -refer to this communication except when it is potentially ambiguous between TLS -and mTLS. +This page provides reference information for configuring secure communication in +the `tls` block of a Nomad agent configuration. Enable TLS on Raft traffic and +RFC and HTTP endpoints. Add TLS cipher suites and paths to certificates and key +files. Specify the TLS version. Require client certificates for all incoming +HTTPS requests and verifying the server name on all outgoing TLS connections. + +Note that he Nomad documentation uses "TLS" to refer to this communication +except when it is potentially ambiguous between TLS and mTLS. ```hcl tls { @@ -27,8 +28,7 @@ tls { ~> Incorrect configuration of the TLS configuration can result in failure to start the Nomad agent. -This section of the documentation only covers the configuration options for -`tls` block. To understand how to setup the certificates themselves, please see +This section of the documentation only covers the configuration options for the `tls` block. To understand how to setup the certificates themselves, refer to the [Enable TLS Encryption for Nomad Tutorial](/nomad/tutorials/transport-security/security-enable-tls). ## `tls` Parameters diff --git a/website/content/docs/configuration/ui.mdx b/website/content/docs/configuration/ui.mdx index a51c9125827..303e257097a 100644 --- a/website/content/docs/configuration/ui.mdx +++ b/website/content/docs/configuration/ui.mdx @@ -1,16 +1,18 @@ --- layout: docs -page_title: ui Block - Agent Configuration +page_title: ui Block in Agent Configuration description: |- - The "ui" block configures the Nomad agent's web UI. - + Configure Nomad's web UI in the `ui` block of a Nomad agent configuration. Provide Vault and Consul links, add custom text to Nomad's UI, and define the HTTP Content Security Policy response header. --- -# `ui` Block +# `ui` Block in Agent Configuration -The `ui` block configures the Nomad agent's [web UI]. +This page provides reference information for configuring Nomad's web UI in the +`ui` block of a Nomad agent configuration. Provide Vault and Consul links, +add custom text to display in Nomad's UI, and define the HTTP Content +Security Policy response header. ```hcl ui { @@ -106,7 +108,7 @@ header sent with the web UI response. - `text` `(string: "")` - Specifies the text of the label that will be displayed in the header of the Web UI. - `background_color` `(string: "")` - The background color of the label to - be displayed. The Web UI will default to a black background. HEX values + be displayed. The Web UI will default to a black background. HEX values may be used. - `text_color` `(string: "")` - The text color of the label to be displayed. The Web UI will default to white text. HEX values may be used. diff --git a/website/content/docs/configuration/vault.mdx b/website/content/docs/configuration/vault.mdx index 60a25739d01..4a768ea48e0 100644 --- a/website/content/docs/configuration/vault.mdx +++ b/website/content/docs/configuration/vault.mdx @@ -1,26 +1,32 @@ --- layout: docs -page_title: vault Block - Agent Configuration +page_title: vault Block in Agent Configuration description: |- - The "vault" block configures Nomad's integration with HashiCorp's Vault. - When configured, Nomad can create and distribute Vault tokens to tasks - automatically. + Configure Nomad server and client integration with HashiCorp Vault in the `vault` block of a Nomad agent configuration. Configure cluster name and the role for creating tokens. For Nomad clients, configure Vault's address, namespace, and certificate or TLS authentication. Specify the JWT authentication path. For Nomad servers, configure the server's default workload identity, which includes workload identity recipients, workload TTL, and key-value pairs for additional identity claims. + --- -# `vault` Block +# `vault` Block in Agent Configuration -The `vault` block configures Nomad's integration with [HashiCorp's -Vault][vault]. When configured, tasks can use [workload -identities][workload_id] to receive Vault ACL tokens automatically. +This page provides reference information for configuring Nomad server and client +integration with [HashiCorp Vault][vault] in the `vault` block of a Nomad agent +configuration. Configure cluster name and the role for creating tokens. For +Nomad clients, configure Vault's address, namespace, and certificate or TLS +authentication. Specify the JWT authentication path. For Nomad +servers, configure the server's default workload identity, which includes +workload identity recipients, workload TTL, and key-value pairs for additional +identity claims. + +When configured, job tasks can use [workload identities][workload_id] to receive +Vault ACL tokens automatically. Alternatively, Nomad servers may be configured with a high-privileged Vault token that is used to derive fine-grained tokens for tasks. Refer to -[Token-based Authentication](#token-based-authentication) for configuration -details. This workflow is deprecated and will be removed in a future version of -Nomad. Using using workload identities is strongly recommended as it is easier -to manage and more secure. +[Token-Based Authentication](#token-based-authentication) for configuration +details. However, we strongly recommend using workload identities since +token-based authentication is deprecated. Refer to the [Nomad and Vault Integration][nomad-vault] page for more information about the Vault integration. @@ -163,8 +169,8 @@ will be removed in a future release. - `token` `(string: "")` - Specifies the parent Vault token to use to derive child tokens for jobs requesting tokens. Only required on Nomad servers. Nomad client agents use the allocation's token when contacting Vault. - Visit the [Vault Integration Guide](/nomad/docs/integrations/vault-integration) - to see how to generate an appropriate token in Vault. + Refer to the [Vault Integration Guide](/nomad/docs/integrations/vault-integration) + for how to generate an appropriate token in Vault. !> It is **strongly discouraged** to place the token as a configuration parameter like this, since the token could be checked into source control @@ -213,14 +219,14 @@ will be removed in a future release. - `${vault.namespace}` - The Vault namespace. - `${vault.role}` - The Vault role. -### Token-based Authentication +### Token-Based Authentication ~> **Warning:** The token-based authentication flow is deprecated and will be removed in a future release. It is highly recommended to migrate and use the workload identity flow instead. -When using token-based authentication the `vault` block parameters should be -defined as below. +When using token-based authentication the `vault` block, define parameters as in +the following examples. #### Parameters for Nomad Clients and Servers @@ -261,7 +267,7 @@ server { vault { enabled = true - # Only needed in servers when transioning from the token-based flow to + # Only needed in servers when transitioning from the token-based flow to # workload identities. create_from_role = "nomad-cluster" @@ -291,7 +297,7 @@ vault { cert_file = "/var/certs/vault.crt" key_file = "/var/certs/vault.key" - # Address to communicate with Vault. The below is the default address if + # Address to communicate with Vault. The following is the default address if # unspecified. address = "https://vault.service.consul:8200" diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e8f2d97aa67..4235f5e11b7 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -290,14 +290,14 @@ "title": "reporting", "path": "configuration/reporting" }, - { - "title": "sentinel", - "path": "configuration/sentinel" - }, { "title": "search", "path": "configuration/search" }, + { + "title": "sentinel", + "path": "configuration/sentinel" + }, { "title": "server", "path": "configuration/server"