kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-04 09:25:46 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs SEO: Update Configuration section to improve search (#24759)

Browse Source 
* 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>

---------

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
This commit is contained in:
Aimee Ukasick
2025-01-10 11:05:23 -06:00
committed by GitHub
parent a7b5970d49
commit ffb34319d5
22 changed files with 353 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
website/content/docs/configuration/acl.mdx
View File

@@ -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
<Placement groups={['acl']} />
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

24
website/content/docs/configuration/audit.mdx
View File

@@ -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
<Placement groups={['audit']} />
<EnterpriseAlert product="nomad"/>
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
{

25
website/content/docs/configuration/autopilot.mdx
View File

@@ -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
<Placement groups={['autopilot']} />
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)` - <EnterpriseAlert product="nomad" inline/> 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)` - <EnterpriseAlert product="nomad" inline/> 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)` - <EnterpriseAlert product="nomad" inline/> 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.

61
website/content/docs/configuration/client.mdx
View File

@@ -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
<Placement groups={['client']} />
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` <code>([server_join][server-join]: nil)</code> - 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 {
@@ -321,10 +326,10 @@ see the [drivers documentation](/nomad/docs/drivers).
GOOGLE_OAUTH_ACCESS_TOKEN
```
- `"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 {
@@ -341,10 +346,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 {
@@ -421,9 +426,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.
@@ -775,7 +780,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 {

40
website/content/docs/configuration/consul.mdx
View File

@@ -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
<Placement groups={['consul']} />
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 "" {

35
website/content/docs/configuration/index.mdx
View File

@@ -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.
</EnterpriseAlert>
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

16
website/content/docs/configuration/keyring/awskms.mdx
View File

@@ -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" {

23
website/content/docs/configuration/keyring/azurekeyvault.mdx
View File

@@ -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: <required>)`: 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.

16
website/content/docs/configuration/keyring/gcpckms.mdx
View File

@@ -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: <required>)`: The GCP region/location where the key ring
lives. Alternately specify via the `GOOGLE_REGION` environment variable.
- `key_ring` `(string: <required>)`: The GCP CKMS key ring to use.
- `key_ring` `(string: <required>)`: The GCP KMS key ring to use.
- `crypto_key` `(string: <required>)`: The GCP CKMS crypto key to use for
- `crypto_key` `(string: <required>)`: The GCP KMS crypto key to use for
encryption and decryption.
## Authentication &amp; permissions

15
website/content/docs/configuration/keyring/index.mdx
View File

@@ -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
<Placement groups={['keyring']} />
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
<EnterpriseAlert>
This functionality only exists in Nomad Enterprise.
</EnterpriseAlert>
<EnterpriseAlert product="nomad"/>
Keyring high availability provides the means to configure multiple active
`keyring` blocks, in order to have resilience against an outage of an external

23
website/content/docs/configuration/keyring/transit.mdx
View File

@@ -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

13
website/content/docs/configuration/plugin.mdx
View File

@@ -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
<Placement groups={['plugin']} />
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" {

21
website/content/docs/configuration/reporting.mdx
View File

@@ -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
<Placement groups={['reporting']} />
<EnterpriseAlert product="nomad"/>
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 {

13
website/content/docs/configuration/search.mdx
View File

@@ -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
<Placement
groups={[
@@ -15,8 +14,10 @@ description: >-
]}
/>
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 {

27
website/content/docs/configuration/sentinel.mdx
View File

@@ -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
<Placement groups={['sentinel']} />
<EnterpriseAlert product="nomad"/>
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<string>: [])` - 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)

78
website/content/docs/configuration/server.mdx
View File

@@ -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
<Placement groups={['server']} />
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` <code>([scheduler_configuration][update-scheduler-config]:
nil)</code> - 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`
<code>([scheduler_configuration][update-scheduler-config]: nil)</code> -
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` <code>([server_join][server-join]: nil)</code> - 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` <code>([search][search]: nil)</code> - 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<string>: [])` - 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

35
website/content/docs/configuration/server_join.mdx
View File

@@ -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
<Placement
groups={[
@@ -15,8 +14,10 @@ description: >-
]}
/>
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 &amp; 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 &amp; 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.

40
website/content/docs/configuration/telemetry.mdx
View File

@@ -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
<Placement groups={['telemetry']} />
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
@@ -102,8 +103,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.
@@ -116,8 +116,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.
@@ -130,8 +129,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.
@@ -149,15 +147,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.
@@ -216,3 +213,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/

24
website/content/docs/configuration/tls.mdx
View File

@@ -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
<Placement groups={['tls']} />
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

14
website/content/docs/configuration/ui.mdx
View File

@@ -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
<Placement groups={['ui']} />
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.

44
website/content/docs/configuration/vault.mdx
View File

@@ -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
<Placement groups={['vault']} />
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 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"

8
website/data/docs-nav-data.json
View File

@@ -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"