From f184d60f964ed0d833c45bf8fdb2827d01c7b67d Mon Sep 17 00:00:00 2001 From: Brian Fjeldstad Date: Thu, 27 Aug 2026 23:40:50 +0000 Subject: [PATCH 1/5] docs: add Host Configuration landing page Add docs/Reference/Host-Configuration/Host-Configuration.md as an overview/landing page for the Host Configuration reference section, and switch the section's _category_.json link from generated-index to a doc link (matching Development/Contributing). Overview covers document structure, validation via `trident validate`, and how install/update servicing types are selected, with links into the Explanation docs for deeper detail. --- .../Host-Configuration/Host-Configuration.md | 89 +++++++++++++++++++ .../Host-Configuration/_category_.json | 6 +- 2 files changed, 92 insertions(+), 3 deletions(-) create mode 100644 docs/Reference/Host-Configuration/Host-Configuration.md diff --git a/docs/Reference/Host-Configuration/Host-Configuration.md b/docs/Reference/Host-Configuration/Host-Configuration.md new file mode 100644 index 0000000000..a21c89f01c --- /dev/null +++ b/docs/Reference/Host-Configuration/Host-Configuration.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 0 +--- + +# Host Configuration + +Host Configuration is the primary interface for describing the desired state +of a host to Trident. It is a single YAML document that captures everything +Trident needs to know to provision or update a machine: disk layout, +partitioning, filesystems, RAID, encryption, A/B update volumes, OS image +sourcing, users, services, and more. + +Trident is declarative: rather than issuing a sequence of imperative +commands, you describe the state you want the host to end up in, and Trident +computes and performs the steps required to get there. + +## Where to start + +- **[API Reference](./API-Reference/HostConfiguration.md)** — the full, + auto-generated reference for every field in the Host Configuration schema, + starting from the top-level `HostConfiguration` type. +- **[Sample Host Configuration](./Sample-Host-Configuration.md)** — a + complete, annotated example showing RAID, encryption, and A/B update + configured together. +- **[Storage Configuration Rules](./Storage-Rules.md)** — the validation + rules Trident applies to the `storage` section, such as reference + validity, homogeneity requirements, and allowed partition types. + +## Structure at a glance + +A Host Configuration document is organized into a handful of top-level +sections: + +| Section | Purpose | +| -------------- | --------------------------------------------------------------| +| `storage` | Disks, partitions, RAID, encryption, filesystems, mount points | +| `os` | Target OS configuration (users, services, SELinux, etc.) | +| `image` | Sourcing and integrity information for the OS image | +| `managementOs` | OS configuration used only during clean install servicing | +| `scripts` | Scripts to run after Trident servicing stages | +| `health` | Health checks for the target OS | + +See the [API Reference](./API-Reference/HostConfiguration.md) for the +authoritative, complete list of fields and their types. + +## Validation + +Trident validates a Host Configuration against a JSON Schema before using +it, and reports any errors it finds. You can check a document's syntax and +structure ahead of time, without applying it to a host, using the `validate` +verb: + +```bash +trident validate /path/to/host-configuration.yaml +``` + +This only validates the file itself. When Trident actually runs an install +or update, it performs additional validation against the target host's +hardware and current state — see [Host Configuration +Validation](../../Explanation/Host-Configuration-Validation.md) for details. + +## How Trident uses it + +The same Host Configuration document is used for both of Trident's main +verbs: + +- **`trident install`** — performs a clean install of the target OS image + described by `image` onto the storage described in `storage`, using + `managementOs` for the provisioning environment. +- **`trident update`** — compares the new Host Configuration against the + host's current state and automatically selects the least disruptive + servicing type that can apply the change: a + [runtime update](../../Reference/Glossary.md#runtime-update) (no reboot), + an [A/B update](../../Reference/Glossary.md#ab-update) (switches to the + other root partition and reboots), or reports that a clean install is + required if the change can't be applied in place. + +See [How Trident Knows What to +Do](../../Explanation/How-Trident-Knows-What-to-Do.md) and [A/B +Update](../../Explanation/AB-Update.md) for a deeper explanation of this +decision process. + +## Related topics + +- [Host Configuration Validation](../../Explanation/Host-Configuration-Validation.md) +- [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) +- [A/B Update](../../Explanation/AB-Update.md) +- [Partition Sizes](../../Explanation/Partition-Sizes.md) +- [Script Hooks](../../Explanation/Script-Hooks.md) diff --git a/docs/Reference/Host-Configuration/_category_.json b/docs/Reference/Host-Configuration/_category_.json index 772a395170..47aea0418a 100644 --- a/docs/Reference/Host-Configuration/_category_.json +++ b/docs/Reference/Host-Configuration/_category_.json @@ -2,7 +2,7 @@ "label": "Host Configuration", "position": 1, "link": { - "type": "generated-index", - "description": "Host Configuration reference for Trident." + "type": "doc", + "id": "Reference/Host-Configuration/Host-Configuration" } -} \ No newline at end of file +} From 7de31773f60ba347e9d51f1edb21830e457f472b Mon Sep 17 00:00:00 2001 From: bfjelds Date: Thu, 27 Aug 2026 17:25:02 -0700 Subject: [PATCH 2/5] fix line endings Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../Host-Configuration/Host-Configuration.md | 176 +++++++++--------- 1 file changed, 88 insertions(+), 88 deletions(-) diff --git a/docs/Reference/Host-Configuration/Host-Configuration.md b/docs/Reference/Host-Configuration/Host-Configuration.md index a21c89f01c..2c05df42e2 100644 --- a/docs/Reference/Host-Configuration/Host-Configuration.md +++ b/docs/Reference/Host-Configuration/Host-Configuration.md @@ -1,89 +1,89 @@ ---- -sidebar_position: 0 ---- - -# Host Configuration - -Host Configuration is the primary interface for describing the desired state -of a host to Trident. It is a single YAML document that captures everything -Trident needs to know to provision or update a machine: disk layout, -partitioning, filesystems, RAID, encryption, A/B update volumes, OS image -sourcing, users, services, and more. - -Trident is declarative: rather than issuing a sequence of imperative -commands, you describe the state you want the host to end up in, and Trident -computes and performs the steps required to get there. - -## Where to start - -- **[API Reference](./API-Reference/HostConfiguration.md)** — the full, - auto-generated reference for every field in the Host Configuration schema, - starting from the top-level `HostConfiguration` type. -- **[Sample Host Configuration](./Sample-Host-Configuration.md)** — a - complete, annotated example showing RAID, encryption, and A/B update - configured together. -- **[Storage Configuration Rules](./Storage-Rules.md)** — the validation - rules Trident applies to the `storage` section, such as reference - validity, homogeneity requirements, and allowed partition types. - -## Structure at a glance - -A Host Configuration document is organized into a handful of top-level -sections: - -| Section | Purpose | -| -------------- | --------------------------------------------------------------| -| `storage` | Disks, partitions, RAID, encryption, filesystems, mount points | -| `os` | Target OS configuration (users, services, SELinux, etc.) | -| `image` | Sourcing and integrity information for the OS image | -| `managementOs` | OS configuration used only during clean install servicing | -| `scripts` | Scripts to run after Trident servicing stages | -| `health` | Health checks for the target OS | - -See the [API Reference](./API-Reference/HostConfiguration.md) for the -authoritative, complete list of fields and their types. - -## Validation - -Trident validates a Host Configuration against a JSON Schema before using -it, and reports any errors it finds. You can check a document's syntax and -structure ahead of time, without applying it to a host, using the `validate` -verb: - -```bash -trident validate /path/to/host-configuration.yaml -``` - -This only validates the file itself. When Trident actually runs an install -or update, it performs additional validation against the target host's -hardware and current state — see [Host Configuration -Validation](../../Explanation/Host-Configuration-Validation.md) for details. - -## How Trident uses it - -The same Host Configuration document is used for both of Trident's main -verbs: - -- **`trident install`** — performs a clean install of the target OS image - described by `image` onto the storage described in `storage`, using - `managementOs` for the provisioning environment. -- **`trident update`** — compares the new Host Configuration against the - host's current state and automatically selects the least disruptive - servicing type that can apply the change: a - [runtime update](../../Reference/Glossary.md#runtime-update) (no reboot), - an [A/B update](../../Reference/Glossary.md#ab-update) (switches to the - other root partition and reboots), or reports that a clean install is - required if the change can't be applied in place. - -See [How Trident Knows What to -Do](../../Explanation/How-Trident-Knows-What-to-Do.md) and [A/B -Update](../../Explanation/AB-Update.md) for a deeper explanation of this -decision process. - -## Related topics - -- [Host Configuration Validation](../../Explanation/Host-Configuration-Validation.md) -- [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) -- [A/B Update](../../Explanation/AB-Update.md) -- [Partition Sizes](../../Explanation/Partition-Sizes.md) +--- +sidebar_position: 0 +--- + +# Host Configuration + +Host Configuration is the primary interface for describing the desired state +of a host to Trident. It is a single YAML document that captures everything +Trident needs to know to provision or update a machine: disk layout, +partitioning, filesystems, RAID, encryption, A/B update volumes, OS image +sourcing, users, services, and more. + +Trident is declarative: rather than issuing a sequence of imperative +commands, you describe the state you want the host to end up in, and Trident +computes and performs the steps required to get there. + +## Where to start + +- **[API Reference](./API-Reference/HostConfiguration.md)** — the full, + auto-generated reference for every field in the Host Configuration schema, + starting from the top-level `HostConfiguration` type. +- **[Sample Host Configuration](./Sample-Host-Configuration.md)** — a + complete, annotated example showing RAID, encryption, and A/B update + configured together. +- **[Storage Configuration Rules](./Storage-Rules.md)** — the validation + rules Trident applies to the `storage` section, such as reference + validity, homogeneity requirements, and allowed partition types. + +## Structure at a glance + +A Host Configuration document is organized into a handful of top-level +sections: + +| Section | Purpose | +| -------------- | --------------------------------------------------------------| +| `storage` | Disks, partitions, RAID, encryption, filesystems, mount points | +| `os` | Target OS configuration (users, services, SELinux, etc.) | +| `image` | Sourcing and integrity information for the OS image | +| `managementOs` | OS configuration used only during clean install servicing | +| `scripts` | Scripts to run after Trident servicing stages | +| `health` | Health checks for the target OS | + +See the [API Reference](./API-Reference/HostConfiguration.md) for the +authoritative, complete list of fields and their types. + +## Validation + +Trident validates a Host Configuration against a JSON Schema before using +it, and reports any errors it finds. You can check a document's syntax and +structure ahead of time, without applying it to a host, using the `validate` +verb: + +```bash +trident validate /path/to/host-configuration.yaml +``` + +This only validates the file itself. When Trident actually runs an install +or update, it performs additional validation against the target host's +hardware and current state — see [Host Configuration +Validation](../../Explanation/Host-Configuration-Validation.md) for details. + +## How Trident uses it + +The same Host Configuration document is used for both of Trident's main +verbs: + +- **`trident install`** — performs a clean install of the target OS image + described by `image` onto the storage described in `storage`, using + `managementOs` for the provisioning environment. +- **`trident update`** — compares the new Host Configuration against the + host's current state and automatically selects the least disruptive + servicing type that can apply the change: a + [runtime update](../../Reference/Glossary.md#runtime-update) (no reboot), + an [A/B update](../../Reference/Glossary.md#ab-update) (switches to the + other root partition and reboots), or reports that a clean install is + required if the change can't be applied in place. + +See [How Trident Knows What to +Do](../../Explanation/How-Trident-Knows-What-to-Do.md) and [A/B +Update](../../Explanation/AB-Update.md) for a deeper explanation of this +decision process. + +## Related topics + +- [Host Configuration Validation](../../Explanation/Host-Configuration-Validation.md) +- [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) +- [A/B Update](../../Explanation/AB-Update.md) +- [Partition Sizes](../../Explanation/Partition-Sizes.md) - [Script Hooks](../../Explanation/Script-Hooks.md) From ac2ddc92222f2fa4094641042fb1855d76b0ebe3 Mon Sep 17 00:00:00 2001 From: bfjelds Date: Thu, 27 Aug 2026 17:25:37 -0700 Subject: [PATCH 3/5] fix line endings Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/Reference/Host-Configuration/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/Reference/Host-Configuration/_category_.json b/docs/Reference/Host-Configuration/_category_.json index 47aea0418a..4242f27f34 100644 --- a/docs/Reference/Host-Configuration/_category_.json +++ b/docs/Reference/Host-Configuration/_category_.json @@ -1,8 +1,8 @@ -{ - "label": "Host Configuration", - "position": 1, - "link": { - "type": "doc", - "id": "Reference/Host-Configuration/Host-Configuration" - } +{ + "label": "Host Configuration", + "position": 1, + "link": { + "type": "doc", + "id": "Reference/Host-Configuration/Host-Configuration" + } } From 48a12ecf204de8c8c4ee485b9620ba30a8355fb6 Mon Sep 17 00:00:00 2001 From: Brian Fjeldstad Date: Fri, 28 Aug 2026 00:39:10 +0000 Subject: [PATCH 4/5] fix --- .../Host-Configuration/Host-Configuration.md | 175 +++++++++--------- .../Host-Configuration/_category_.json | 16 +- 2 files changed, 95 insertions(+), 96 deletions(-) diff --git a/docs/Reference/Host-Configuration/Host-Configuration.md b/docs/Reference/Host-Configuration/Host-Configuration.md index 2c05df42e2..a86c151ea1 100644 --- a/docs/Reference/Host-Configuration/Host-Configuration.md +++ b/docs/Reference/Host-Configuration/Host-Configuration.md @@ -1,89 +1,88 @@ ---- -sidebar_position: 0 ---- - -# Host Configuration - -Host Configuration is the primary interface for describing the desired state -of a host to Trident. It is a single YAML document that captures everything -Trident needs to know to provision or update a machine: disk layout, -partitioning, filesystems, RAID, encryption, A/B update volumes, OS image -sourcing, users, services, and more. - -Trident is declarative: rather than issuing a sequence of imperative -commands, you describe the state you want the host to end up in, and Trident -computes and performs the steps required to get there. - -## Where to start - -- **[API Reference](./API-Reference/HostConfiguration.md)** — the full, - auto-generated reference for every field in the Host Configuration schema, - starting from the top-level `HostConfiguration` type. -- **[Sample Host Configuration](./Sample-Host-Configuration.md)** — a - complete, annotated example showing RAID, encryption, and A/B update - configured together. -- **[Storage Configuration Rules](./Storage-Rules.md)** — the validation - rules Trident applies to the `storage` section, such as reference - validity, homogeneity requirements, and allowed partition types. - -## Structure at a glance - -A Host Configuration document is organized into a handful of top-level -sections: - -| Section | Purpose | -| -------------- | --------------------------------------------------------------| -| `storage` | Disks, partitions, RAID, encryption, filesystems, mount points | -| `os` | Target OS configuration (users, services, SELinux, etc.) | -| `image` | Sourcing and integrity information for the OS image | -| `managementOs` | OS configuration used only during clean install servicing | -| `scripts` | Scripts to run after Trident servicing stages | -| `health` | Health checks for the target OS | - -See the [API Reference](./API-Reference/HostConfiguration.md) for the -authoritative, complete list of fields and their types. - -## Validation - -Trident validates a Host Configuration against a JSON Schema before using -it, and reports any errors it finds. You can check a document's syntax and -structure ahead of time, without applying it to a host, using the `validate` -verb: - -```bash -trident validate /path/to/host-configuration.yaml -``` - -This only validates the file itself. When Trident actually runs an install -or update, it performs additional validation against the target host's -hardware and current state — see [Host Configuration -Validation](../../Explanation/Host-Configuration-Validation.md) for details. - -## How Trident uses it - -The same Host Configuration document is used for both of Trident's main -verbs: - -- **`trident install`** — performs a clean install of the target OS image - described by `image` onto the storage described in `storage`, using - `managementOs` for the provisioning environment. -- **`trident update`** — compares the new Host Configuration against the - host's current state and automatically selects the least disruptive - servicing type that can apply the change: a - [runtime update](../../Reference/Glossary.md#runtime-update) (no reboot), - an [A/B update](../../Reference/Glossary.md#ab-update) (switches to the - other root partition and reboots), or reports that a clean install is - required if the change can't be applied in place. - -See [How Trident Knows What to -Do](../../Explanation/How-Trident-Knows-What-to-Do.md) and [A/B -Update](../../Explanation/AB-Update.md) for a deeper explanation of this -decision process. - -## Related topics - -- [Host Configuration Validation](../../Explanation/Host-Configuration-Validation.md) -- [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) -- [A/B Update](../../Explanation/AB-Update.md) -- [Partition Sizes](../../Explanation/Partition-Sizes.md) +--- +sidebar_position: 0 +--- + +# Host Configuration + +Host Configuration is the primary interface for describing the desired state +of a host to Trident. It is a single YAML document that captures everything +Trident needs to know to provision or update a machine: disk layout, +partitioning, filesystems, RAID, encryption, A/B update volumes, OS image +sourcing, users, services, and more. + +Trident is declarative: rather than issuing a sequence of imperative +commands, you describe the state you want the host to end up in, and Trident +computes and performs the steps required to get there. + +## Where to start + +- **[API Reference](./API-Reference/HostConfiguration.md)** — the full, + auto-generated reference for every field in the Host Configuration schema, + starting from the top-level `HostConfiguration` type. +- **[Sample Host Configuration](./Sample-Host-Configuration.md)** — a + complete, annotated example showing RAID, encryption, and A/B update + configured together. +- **[Storage Configuration Rules](./Storage-Rules.md)** — the validation + rules Trident applies to the `storage` section, such as reference + validity, homogeneity requirements, and allowed partition types. + +## Structure at a glance + +A Host Configuration document is organized into a handful of top-level +sections: + +| Section | Purpose | +| -------------- | -------------------------------------------------------------- | +| `storage` | Disks, partitions, RAID, encryption, filesystems, mount points | +| `os` | Target OS configuration (users, services, SELinux, etc.) | +| `image` | Sourcing and integrity information for the OS image | +| `managementOs` | OS configuration used only during clean install servicing | +| `scripts` | Scripts to run after Trident servicing stages | +| `health` | Health checks for the target OS | + +See the [API Reference](./API-Reference/HostConfiguration.md) for the +authoritative, complete list of fields and their types. + +## Validation + +Trident validates a Host Configuration against a JSON Schema before using +it, and reports any errors it finds. You can check a document's syntax and +structure ahead of time, without applying it to a host, using the `validate` +verb: + +```bash +trident validate /path/to/host-configuration.yaml +``` + +This only validates the file itself. When Trident actually runs an install +or update, it performs additional validation against the target host's +hardware and current state — see [Host Configuration +Validation](../../Explanation/Host-Configuration-Validation.md) for details. + +## How Trident uses it + +The same Host Configuration document is used for both of Trident's main +verbs: + +- **`trident install`** — performs a clean install of the target OS image + described by `image` onto the storage described in `storage`, using + `managementOs` for the provisioning environment. +- **`trident update`** — compares the new Host Configuration against the + host's current state and automatically selects the least disruptive + servicing type that can apply the change: a + [runtime update](../../Reference/Glossary.md#runtime-update) (no reboot), + an [A/B update](../../Reference/Glossary.md#ab-update) (switches to the + other root partition and reboots), or reports that a clean install is + required if the change can't be applied in place. + +See [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) and +[A/B Update](../../Explanation/AB-Update.md) for a deeper explanation of this +decision process. + +## Related topics + +- [Host Configuration Validation](../../Explanation/Host-Configuration-Validation.md) +- [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) +- [A/B Update](../../Explanation/AB-Update.md) +- [Partition Sizes](../../Explanation/Partition-Sizes.md) - [Script Hooks](../../Explanation/Script-Hooks.md) diff --git a/docs/Reference/Host-Configuration/_category_.json b/docs/Reference/Host-Configuration/_category_.json index 4242f27f34..977b8db6ac 100644 --- a/docs/Reference/Host-Configuration/_category_.json +++ b/docs/Reference/Host-Configuration/_category_.json @@ -1,8 +1,8 @@ -{ - "label": "Host Configuration", - "position": 1, - "link": { - "type": "doc", - "id": "Reference/Host-Configuration/Host-Configuration" - } -} +{ + "label": "Host Configuration", + "position": 1, + "link": { + "type": "doc", + "id": "Reference/Host-Configuration/Host-Configuration" + } +} \ No newline at end of file From 0e30ae42da58b0a917af7b8ceb684a5b178e4b6c Mon Sep 17 00:00:00 2001 From: Brian Fjeldstad Date: Fri, 28 Aug 2026 00:47:40 +0000 Subject: [PATCH 5/5] fix --- docs/Reference/Host-Configuration/Host-Configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Reference/Host-Configuration/Host-Configuration.md b/docs/Reference/Host-Configuration/Host-Configuration.md index a86c151ea1..f5c3e0087f 100644 --- a/docs/Reference/Host-Configuration/Host-Configuration.md +++ b/docs/Reference/Host-Configuration/Host-Configuration.md @@ -75,7 +75,7 @@ verbs: other root partition and reboots), or reports that a clean install is required if the change can't be applied in place. -See [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) and +See [How Trident Knows What to Do](../../Explanation/How-Trident-Knows-What-to-Do.md) and [A/B Update](../../Explanation/AB-Update.md) for a deeper explanation of this decision process.