hashicorp · aimeeu · Dec 26, 2024
@@ -1,7 +1,7 @@
 ---
 layout: docs
 page_title: Access Control List (ACL)
-description: Learn about Nomad's ACL subsystem
+description: Learn how Nomad's Access Control List (ACL) feature uses tokens, policies, roles, and capabilities to control access.
 ---
 
 # Access Control List (ACL)
@@ -15,7 +15,7 @@ Single Sign-On (SSO) ACL capabilities.
 The Nomad [access control tutorials][] provide detailed information and
 guidance on Nomad ACL system.
 
-### Policy
+## Policy
 
 Policies consist of a set of rules defining the capabilities or actions to be
 granted. For example, a `readonly` policy might only grant the ability to list
@@ -27,13 +27,13 @@ Nomad ACL token for accessing the objects in a Nomad cluster, objects like
 namespaces, node, agent, operator, quota, etc. For more information on writing
 policies, see the [ACL policy reference doc][].
 
-### Role
+## Role
 
 Roles group one or more ACL policies into a container which can then be used to
 generate ACL tokens for authorisation. This abstraction allows easier control
 and updating of ACL permissions, particularly in larger, more diverse clusters.
 
-### Token
+## Token
 
 Requests to Nomad are authenticated using a bearer token. Each ACL token has a
 public Accessor ID which is used to name a token and a Secret ID which is used
@@ -49,22 +49,22 @@ other regions. Otherwise, tokens are created locally in the region the request
 was made and not replicated. `Local` tokens cannot be used for cross-region
 requests since they are not replicated between regions.
 
-### Workload Identity
+## Workload Identity
 
 Nomad allocations can receive workload identities in the form of a
 [JSON Web Token (JWT)][jwt]. The
 [Workload Identity concept page][workload identity] has more information on
 this topic.
 
-### Auth Method
+## Auth Method
 
 Authentication methods dictate how Nomad should talk to SSO providers when a
 user requests to authenticate using one. Currently, Nomad supports the [OpenID
 Connect (OIDC)][oidc] SSO workflow which allows users to log in to Nomad via
 applications such as [Auth0][auth0], [Okta][okta], and [Vault][vault], and
 non-interactive login via externally-issued [JSON Web Tokens (JWT)][jwt].
 
-### Binding Rule
+## Binding Rule
 
 Binding rules provide a mapping between a Nomad user's SSO authorisation claims
 and internal Nomad objects such as ACL Roles and ACL Policies. A binding rule

@@ -2,28 +2,29 @@
 layout: docs
 page_title: Federation
 description: |-
-  Nomad federation is a multi-cluster orchestration and management feature that allows multiple
-  Nomad clusters, defined as a region, to work together seamlessly.
+  Learn how Nomad federation enables multiple Nomad clusters, defined as a region, to work together seamlessly.
 ---
 
 # Federation
 
-Nomad federation is a multi-cluster orchestration and management feature that allows multiple Nomad
-clusters, defined as a region, to work together seamlessly. By federating clusters, you benefit
-from improved scalability, fault tolerance, and centralized management of workloads across various
-data centers or geographical locations.
+Nomad federation is a multi-cluster orchestration and management feature that
+enables multiple Nomad clusters, defined as a region, to work together
+seamlessly. By federating clusters, you benefit from improved scalability, fault
+tolerance, and centralized management of workloads across various data centers
+or geographical locations.
 
 ## Cross-Region request forwarding
 
-API calls can include a `region` query parameter that defines the Nomad region the query is
-specified for. If this is not the local region, Nomad transparently forwards the request to a
-server in the requested region. When you omit the query parameter, Nomad uses the region of the
-server that is processing the request.
+API calls can include a `region` query parameter that defines the Nomad region
+the query is specified for. If this is not the local region, Nomad transparently
+forwards the request to a server in the requested region. When you omit the
+query parameter, Nomad uses the region of the server that is processing the
+request.
 
 ## Replication
 
-Nomad writes the following objects in the authoritative region and replicates them to all federated
-regions:
+Nomad writes the following objects in the authoritative region and replicates
+them to all federated regions:
 
 - ACL [policies][acl_policy], [roles][acl_role], [auth methods][acl_auth_method],
   [binding rules][acl_binding_rule], and [global tokens][acl_token]
@@ -32,25 +33,25 @@ regions:
 - [Quota specifications][quota]
 - [Sentinel policies][sentinel_policies]
 
-When creating, updating, or deleting these objects, Nomad always sends the request to the
-authoritative region using RPC forwarding.
+When creating, updating, or deleting these objects, Nomad always sends the
+request to the authoritative region using RPC forwarding.
 
-Nomad starts replication routines on each federated cluster's leader server in a hub and spoke
-design. The routines then use blocking queries to receive updates from the authoritative region to
-mirror in their own state store. These routines also implement rate limiting, so that busy clusters
-do not degrade due to overly aggressive replication processes.
+Nomad starts replication routines on each federated cluster's leader server in a
+hub and spoke design. The routines then use blocking queries to receive updates
+from the authoritative region to mirror in their own state store. These routines
+also implement rate limiting, so that busy clusters do not degrade due to overly
+aggressive replication processes.
 
-<Note>
-Nomad writes ACL local tokens in the region where you make the request and  does not replicate
-those local tokens.
-</Note>
+<Note> Nomad writes ACL local tokens in the region where you make the request
+and  does not replicate those local tokens. </Note>
 
 ## Multi-Region job deployments <EnterpriseAlert inline />
 
-Nomad job deployments can use the [`multiregion`][] block when running in federated mode.
-Multiregion configuration instructs Nomad to register and run the job on all the specified regions,
-removing the need for multiple job specification copies and registration on each region.
-Multiregion jobs do not provide regional failover in the event of failure.
+Nomad job deployments can use the [`multiregion`][] block when running in
+federated mode. Multiregion configuration instructs Nomad to register and run
+the job on all the specified regions, removing the need for multiple job
+specification copies and registration on each region. Multiregion jobs do not
+provide regional failover in the event of failure.
 
 [acl_policy]: /nomad/docs/concepts/acl#policy
 [acl_role]: /nomad/docs/concepts/acl#role

@@ -1,7 +1,8 @@
 ---
 layout: docs
 page_title: Architecture
-description: Learn about the internal architecture of Nomad.
+description: |-
+  Learn how Nomad's system architecture implements a run any workload anywhere approach to scheduling and orchestration.
 ---
 
 # Architecture

@@ -2,16 +2,13 @@
 layout: docs
 page_title: Consensus Protocol
 description: |-
-  Nomad uses a consensus protocol to provide Consistency as defined by CAP.
-  The consensus protocol is based on Raft: In search of an Understandable
-  Consensus Algorithm. For a visual explanation of Raft, see The Secret Lives of
-  Data.
+  Learn how Nomad uses a consensus protocol based on Raft to manage cluster node state.
 ---
 
 # Consensus Protocol
 
 Nomad uses a [consensus protocol](<https://en.wikipedia.org/wiki/Consensus_(computer_science)>)
-to provide [Consistency (as defined by CAP)](https://en.wikipedia.org/wiki/CAP_theorem).
+to provide [Consistency as defined by CAP](https://en.wikipedia.org/wiki/CAP_theorem).
 The consensus protocol is based on
 ["Raft: In search of an Understandable Consensus Algorithm"](https://raft.github.io/raft.pdf).
 For a visual explanation of Raft, see [The Secret Lives of Data](http://thesecretlivesofdata.com/raft).
@@ -182,7 +179,7 @@ failure scenario.
       <td>2</td>
       <td>0</td>
     </tr>
-    <tr class="warning">
+    <tr>
       <td>3</td>
       <td>2</td>
       <td>1</td>
@@ -192,7 +189,7 @@ failure scenario.
       <td>3</td>
       <td>1</td>
     </tr>
-    <tr class="warning">
+    <tr>
       <td>5</td>
       <td>3</td>
       <td>2</td>

@@ -1,7 +1,7 @@
 ---
 layout: docs
 page_title: CPU
-description: Learn about how Nomad manages CPU resources.
+description: Learn how Nomad manages CPU resources.
 ---
 
 # Modern processors

@@ -2,11 +2,10 @@
 layout: docs
 page_title: Filesystem
 description: |-
-  Nomad creates an allocation working directory for every allocation. Learn what
-  goes into the working directory and how it interacts with Nomad task drivers.
+  Learn how Nomad uses allocation working directories to store task artifacts and logs.
 ---
 
-# Filesystem
+# Allocation Filesystems
 
 Nomad creates a working directory for each allocation on a client. This
 directory can be found in the Nomad [`data_dir`] at

@@ -2,8 +2,7 @@
 layout: docs
 page_title: Gossip Protocol
 description: |-
-  Nomad uses a gossip protocol to manage membership. All of this is provided
-  through the use of the Serf library.
+  Learn how Nomad uses a gossip protocol to manage membership. 
 ---
 
 # Gossip Protocol

@@ -2,8 +2,7 @@
 layout: docs
 page_title: Concepts
 description: >-
-  This section covers the core concepts of Nomad and explains technical details of
-  Nomads operation.
+  Learn about Nomad's architecture, core concepts, and behavior.
 ---
 
 # Nomad Concepts

@@ -2,7 +2,7 @@
 layout: docs
 page_title: Job
 description: |-
-  Learn about Nomad's job feature, which is how you deploy your apps, maintenance scripts, cron jobs, and similar tasks.
+  Learn how a Nomad job deploys your apps, maintenance scripts, cron jobs, and similar tasks.
 ---
 
 # Job

@@ -1,7 +1,7 @@
 ---
 layout: docs
 page_title: Node Pools
-description: Learn about the internal architecture of Nomad.
+description: Learn about Nomad's node pools group clients and segment infrastructure into logical units for allocation placement.
 ---
 
 # Node Pools

@@ -1,7 +1,8 @@
 ---
 layout: docs
 page_title: Base Plugin
-description: Learn about how to author a Nomad plugin.
+description:  |-
+  Learn how to create a Nomad plugin so you can extend Nomad's functionality.
 ---
 
 # Base Plugin

@@ -1,7 +1,8 @@
 ---
 layout: docs
 page_title: Network Plugins
-description: Learn how Nomad manages custom user-specified network configurations.
+description:  |-
+  Learn how Nomad's network plugin support enables scheduling tasks with custom network configurations.
 ---
 
 # Network plugins

@@ -1,7 +1,8 @@
 ---
 layout: docs
 page_title: Storage Plugins
-description: Learn how Nomad manages dynamic storage plugins.
+description: |-
+  Learn how Nomad's storage plugin support enables scheduling tasks with external storage volumes.
 ---
 
 # Storage Plugins

@@ -1,7 +1,8 @@
 ---
 layout: docs
 page_title: Device Plugins
-description: Learn how to author a Nomad device plugin.
+description: |-
+  Learn how to create a Nomad device plugin so you can schedule tasks with other devices, such as GPUs.
 ---
 
 # Devices

@@ -1,12 +1,12 @@
 ---
 layout: docs
 page_title: Plugins
-description: Learn about how external plugins work in Nomad.
+description: Learn how external plugins let you extend Nomad's functionality.
 ---
 
 # Plugins
 
-Nomad implements a plugin framework which allows users to extend the
+Nomad implements a plugin framework which lets you extend the
 functionality of some components within Nomad. The design of the plugin system
 is inspired by the lessons learned from plugin systems implemented in other
 HashiCorp products such as Terraform and Vault.
@@ -16,7 +16,7 @@ The following components are currently pluggable within Nomad:
 - [Task Drivers](/nomad/docs/concepts/plugins/task-drivers)
 - [Devices](/nomad/docs/concepts/plugins/devices)
 
-# Architecture
+## Architecture
 
 The Nomad plugin framework uses the [go-plugin][goplugin] project to expose
 a language independent plugin interface. Plugins implement a set of gRPC

@@ -1,7 +1,7 @@
 ---
 layout: docs
 page_title: Task Driver Plugins
-description: Learn how to author a Nomad task driver plugin.
+description: Learn how to create a Nomad task driver plugin to extend Nomad's workload execution functionality.
 ---
 
 # Task Drivers

@@ -1,12 +1,12 @@
 ---
 layout: docs
 page_title: Scheduling
-description: Learn about how scheduling works in Nomad.
+description: Learn how Nomad's scheduling component assigns jobs to client machines.
 ---
 
-# Scheduling
+# Scheduling workloads
 
-Scheduling is a core function of Nomad. It is the process of assigning tasks
+Scheduling workloads is a core function of Nomad. It is the process of assigning tasks
 from jobs to client machines. The design is heavily inspired by Google's work on
 both [Omega: flexible, scalable schedulers for large compute clusters][omega] and
 [Large-scale cluster management at Google with Borg][borg]. See the links below

@@ -1,10 +1,10 @@
 ---
 layout: docs
 page_title: Placement
-description: Learn about how placements are computed in Nomad.
+description: Learn how Nomad schedules jobs to run on clients.
 ---
 
-# Placement
+# Allocation Placement
 
 When the Nomad scheduler receives a job registration request, it needs to
 determine which clients will run allocations for the job.

@@ -1,7 +1,7 @@
 ---
 layout: docs
 page_title: Preemption
-description: Learn about how preemption works in Nomad.
+description: Learn how Nomad uses preemption to evict existing allocations in order to place allocations for a higher priority job.
 ---
 
 # Preemption
@@ -12,7 +12,7 @@ run high priority jobs even under resource contention across the cluster.
 
 ~> **Advanced Topic!** This page covers technical details of Nomad. You do not need to understand these details to effectively use Nomad. The details are documented here for those who wish to learn about them without having to go spelunking through the source code.
 
-# Preemption in Nomad
+## Preemption in Nomad
 
 Every job in Nomad has a priority associated with it. Priorities impact scheduling at the evaluation and planning
 stages by sorting the respective queues accordingly (higher priority jobs get moved ahead in the queues).
@@ -21,7 +21,7 @@ Nomad has preemption capabilities for service, batch, and system jobs. The Nomad
 to free up capacity for new allocations resulting from relatively higher priority jobs, sending evicted allocations back
 into the plan queue.
 
-# Details
+## Details
 
 Preemption is enabled by default for system jobs. Operators can use the [scheduler config](/nomad/api-docs/operator#update-scheduler-configuration) API endpoint to disable preemption.
 
@@ -45,7 +45,7 @@ Allocations are selected starting from the lowest priority, and scored according
 to how closely they fit the job's required capacity. For example, if the `75` priority job needs 1GB disk and 2GB memory, Nomad will preempt
 allocations `a1`, `a2` and `a4` to satisfy those requirements.
 
-# Preemption Visibility
+## Preemption Visibility
 
 Operators can use the [allocation API](/nomad/api-docs/allocations#read-allocation) or the `alloc status` command to get visibility into
 whether an allocation has been preempted. Preempted allocations will have their DesiredStatus set to “evict”. The `Allocation` object
@@ -57,7 +57,7 @@ in the API also has two additional fields related to preemption.
 - `PreemptedByAllocID` - This field is set on allocations that were preempted by the scheduler. It contains the allocation ID of the allocation
   that preempted it. In the above example, allocations `a1`, `a2` and `a4` will have this field set to the ID of the allocation from the job `webapp`.
 
-# Integration with Nomad plan
+## Integration with Nomad plan
 
 `nomad plan` allows operators to dry run the scheduler. If the scheduler determines that
 preemption is necessary to place the job, it shows additional information in the CLI output for