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

* 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 <[email protected]> --------- Co-authored-by: Jeff Boruszak <[email protected]>
hashicorp · Jan 10, 2025 · dce9537 · dce9537
1 parent 45283c4
commit dce9537
Show file tree

Hide file tree

Showing 22 changed files with 353 additions and 256 deletions.
diff --git 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
 
 <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

diff --git 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
 
 <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
 {

diff --git 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
 
 <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.
diff --git 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
 
 <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 {
@@ -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
@@ -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 "" {

diff --git 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.
 </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