From 48ccdbab135b0d3071db60e2194ffb89872831f4 Mon Sep 17 00:00:00 2001
From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Date: Mon, 4 May 2026 18:51:54 -0400
Subject: [PATCH] Reference docs: Multi-platform names for `macos_setup` and
`macos_settings` (#43565)
Update reference docs for the following story:
- https://github.com/fleetdm/fleet/issues/40488
---
articles/setup-experience.md | 2 +-
.../Contributing/guides/cli/fleetctl-apply.md | 4 +-
.../reference/api-for-contributors.md | 14 +-
docs/REST API/rest-api.md | 153 ++++++++++++++++--
4 files changed, 147 insertions(+), 26 deletions(-)
diff --git a/articles/setup-experience.md b/articles/setup-experience.md
index a5856fdf0f..ffce64a73c 100644
--- a/articles/setup-experience.md
+++ b/articles/setup-experience.md
@@ -259,7 +259,7 @@ Fleet also provides a REST API for managing setup experience software and script
## Configuring via GitOps
-To manage setup experience software and script using Fleet's best practice GitOps, check out the `macos_setup` key in the [GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#macos-setup)
+To manage setup experience software and script using Fleet's best practice GitOps, check out the `setup_experience` key in the [GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#setup-experience)
## Advanced
diff --git a/docs/Contributing/guides/cli/fleetctl-apply.md b/docs/Contributing/guides/cli/fleetctl-apply.md
index d9f66cf813..6b93aefee2 100644
--- a/docs/Contributing/guides/cli/fleetctl-apply.md
+++ b/docs/Contributing/guides/cli/fleetctl-apply.md
@@ -190,9 +190,9 @@ spec:
setup_experience:
macos_bootstrap_package: ""
enable_end_user_authentication: true
- enable_release_device_manually: false
+ apple_enable_release_device_manually: false
apple_setup_assistant: ""
- manual_agent_install: false
+ macos_manual_agent_install: false
require_all_software_macos: false
script: ""
software: []
diff --git a/docs/Contributing/reference/api-for-contributors.md b/docs/Contributing/reference/api-for-contributors.md
index c8171667d0..747b585707 100644
--- a/docs/Contributing/reference/api-for-contributors.md
+++ b/docs/Contributing/reference/api-for-contributors.md
@@ -2069,10 +2069,10 @@ If the `name` is not already associated with an existing team, this API route cr
| mdm.macos_updates | object | body | The OS updates macOS configuration options for Nudge. |
| mdm.macos_updates.minimum_version | string | body | The required minimum operating system version. |
| mdm.macos_updates.deadline | string | body | The required installation date for Nudge to enforce the operating system version. |
-| mdm.macos_settings | object | body | The macOS-specific MDM settings. |
-| mdm.macos_settings.custom_settings | array | body | The list of objects consists of a `path` to .mobileconfig or JSON file and `labels_include_all`, `labels_include_any`, or `labels_exclude_any` list of label names. |
+| mdm.apple_settings | object | body | The Apple-specific MDM settings. |
+| mdm.apple_settings.configuration_profiles | array | body | The list of objects consists of a `path` to .mobileconfig or JSON file and `labels_include_all`, `labels_include_any`, or `labels_exclude_any` list of label names. |
| mdm.windows_settings | object | body | The Windows-specific MDM settings. |
-| mdm.windows_settings.custom_settings | array | body | The list of objects consists of a `path` to XML files and `labels_include_all`, `labels_include_any`, or `labels_exclude_any` list of label names. |
+| mdm.windows_settings.configuration_profiles | array | body | The list of objects consists of a `path` to XML files and `labels_include_all`, `labels_include_any`, or `labels_exclude_any` list of label names. |
| scripts | array | body | A list of script files to add to this team so they can be executed at a later time. |
| software | object | body | The team's software that will be available for install. |
| software.app_store_apps | array | body | An array of objects with values below. |
@@ -2089,7 +2089,7 @@ If the `name` is not already associated with an existing team, this API route cr
| software.packages.self_service | boolean | body | If `true` lists software in the self-service. |
| software.packages.labels_include_any | array | body | Target hosts that have any label in the array. Only one of `labels_include_any` or `labels_exclude_any` can be included. If neither are included, all hosts are targeted. |
| software.packages.labels_exclude_any | array | body | Target hosts that don't have any label in the array. Only one of `labels_include_any` or `labels_exclude_any` can be included. If neither are included, all hosts are targeted. |
-| mdm.macos_settings.enable_disk_encryption | bool | body | Whether disk encryption should be enabled for hosts that belong to this team. |
+| mdm.apple_settings.enable_disk_encryption | bool | body | Whether disk encryption should be enabled for hosts that belong to this team. |
| force | bool | query | Force apply the spec even if there are (ignorable) validation errors. Those are unknown keys and agent options-related validations. |
| dry_run | bool | query | Validate the provided JSON for unknown keys and invalid value types and return any validation errors, but do not apply the changes. |
@@ -2146,8 +2146,8 @@ If the `name` is not already associated with an existing team, this API route cr
"minimum_version": "12.3.1",
"deadline": "2023-12-01"
},
- "macos_settings": {
- "custom_settings": [
+ "apple_settings": {
+ "configuration_profiles": [
{
"path": "path/to/profile1.mobileconfig"
"labels_include_all": ["Label 1", "Label 2"]
@@ -2160,7 +2160,7 @@ If the `name` is not already associated with an existing team, this API route cr
"enable_disk_encryption": true
},
"windows_settings": {
- "custom_settings": [
+ "configuration_profiles": [
{
"path": "path/to/profile3.xml"
"labels_include_all": ["Label 1", "Label 2"]
diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md
index 8aed13efbf..880831def5 100644
--- a/docs/REST API/rest-api.md
+++ b/docs/REST API/rest-api.md
@@ -1461,7 +1461,7 @@ Returns all information about the Fleet's configuration.
The `agent_options`, `sso_settings` and `smtp_settings` fields are only returned for admin and GitOps users with global access (see the [Role-based access guide](https://fleetdm.com/guides/role-based-access)).
-`mdm.macos_settings.custom_settings`, `mdm.windows_settings.custom_settings`, `mdm.macos_setup`, `mdm.volume_purchasing_program`, and `scripts` only include the settings applied using [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To list the settings added in the UI or API, use the [List configuration profiles](https://fleetdm.com/docs/rest-api/rest-api#list-custom-os-settings-configuration-profiles), GET endpoints from [Setup experience](https://fleetdm.com/docs/rest-api/rest-api#setup-experience), [List Volume Purchasing Program (VPP) tokens](https://fleetdm.com/docs/rest-api/rest-api#list-volume-purchasing-program-vpp-tokens), or [List scripts](https://fleetdm.com/docs/rest-api/rest-api#list-scripts) instead.
+`mdm.apple_settings.configuration_profiles`, `mdm.windows_settings.configuration_profiles`, `mdm.setup_experience`, `mdm.volume_purchasing_program`, and `scripts` only include the settings applied using [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To list the settings added in the UI or API, use the [List configuration profiles](https://fleetdm.com/docs/rest-api/rest-api#list-custom-os-settings-configuration-profiles), GET endpoints from [Setup experience](https://fleetdm.com/docs/rest-api/rest-api#setup-experience), [List Volume Purchasing Program (VPP) tokens](https://fleetdm.com/docs/rest-api/rest-api#list-volume-purchasing-program-vpp-tokens), or [List scripts](https://fleetdm.com/docs/rest-api/rest-api#list-scripts) instead.
`GET /api/v1/fleet/config`
@@ -1577,6 +1577,14 @@ None.
}
]
},
+ "apple_settings": {
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile1.mobileconfig",
+ "labels": ["Label 1", "Label 2"]
+ }
+ ]
+ },
"windows_settings": {
"custom_settings": [
{
@@ -1584,6 +1592,12 @@ None.
"labels": ["Label 3", "Label 4"]
}
],
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile2.xml",
+ "labels": ["Label 3", "Label 4"]
+ }
+ ],
},
"scripts": ["path/to/script.sh"],
"end_user_authentication": {
@@ -1604,6 +1618,13 @@ None.
"enable_release_device_manually": false,
"manual_agent_install": false
},
+ "setup_experience": {
+ "bootstrap_package": "",
+ "enable_end_user_authentication": false,
+ "apple_setup_assistant": "path/to/config.json",
+ "enable_release_device_manually": false,
+ "manual_agent_install": false
+ },
"client_url": "https://instance.fleet.com"
},
"agent_options": {
@@ -1907,12 +1928,34 @@ Modifies the Fleet's configuration with the supplied information.
},
]
},
+ "apple_settings": {
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile1.mobileconfig",
+ "labels_exclude_any": ["Label 1", "Label 2"]
+ },
+ {
+ "path": "path/to/profile2.json",
+ "labels_include_all": ["Label 3", "Label 4"]
+ },
+ {
+ "path": "path/to/profile3.json",
+ "labels_include_any": ["Label 5", "Label 6"]
+ },
+ ]
+ },
"windows_settings": {
"custom_settings": [
{
"path": "path/to/profile3.xml",
"labels_exclude_any": ["Label 1", "Label 2"]
}
+ ],
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile3.xml",
+ "labels_exclude_any": ["Label 1", "Label 2"]
+ }
]
},
"end_user_authentication": {
@@ -1932,6 +1975,12 @@ Modifies the Fleet's configuration with the supplied information.
"lock_end_user_info": true,
"macos_setup_assistant": "path/to/config.json"
},
+ "setup_experience": {
+ "bootstrap_package": "",
+ "enable_end_user_authentication": false,
+ "lock_end_user_info": true,
+ "apple_setup_assistant": "path/to/config.json"
+ },
"apple_server_url": "https://instance.fleet.com"
},
"agent_options": {
@@ -2470,7 +2519,7 @@ When updating conditional access config, all `conditional_access` fields must ei
| ipados_updates | object | See [`mdm.ipados_updates`](#mdm-ipados-updates). |
| windows_updates | object | See [`mdm.window_updates`](#mdm-windows-updates). |
| macos_migration | object | See [`mdm.macos_migration`](#mdm-macos-migration). |
-| macos_setup | object | See [`mdm.macos_setup`](#mdm-macos-setup). |
+| setup_experience | object | See [`mdm.setup_experience`](#mdm-setup-experience). |
| macos_settings | object | See [`mdm.macos_settings`](#mdm-macos-settings). |
| windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings). |
| apple_server_url | string | Update this URL if you're self-hosting Fleet and you want your hosts to talk to this URL for MDM features. (If not configured, hosts will use the base URL of the Fleet instance.) |
@@ -2548,11 +2597,11 @@ _Available in Fleet Premium._
-##### mdm.macos_setup
+##### mdm.setup_experience
_Available in Fleet Premium._
-`mdm.macos_setup` is an object with the following structure:
+`mdm.setup_experience` is an object with the following structure:
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -2614,8 +2663,8 @@ _Available in Fleet Premium._
"deadline_days": 5,
"grace_period_days": 1
},
- "macos_settings": {
- "custom_settings": [
+ "apple_settings": {
+ "configuration_profiles": [
{
"path": "path/to/profile1.mobileconfig",
"labels": ["Label 1", "Label 2"]
@@ -2627,7 +2676,7 @@ _Available in Fleet Premium._
]
},
"windows_settings": {
- "custom_settings": [
+ "configuration_profiles": [
{
"path": "path/to/profile3.xml",
"labels": ["Label 1", "Label 2"]
@@ -2645,11 +2694,11 @@ _Available in Fleet Premium._
"mode": "voluntary",
"webhook_url": "https://webhook.example.com"
},
- "macos_setup": {
+ "setup_experience": {
"bootstrap_package": "",
"enable_end_user_authentication": false,
"lock_end_user_info": true,
- "macos_setup_assistant": "path/to/config.json"
+ "apple_setup_assistant": "path/to/config.json"
}
}
}
@@ -3738,11 +3787,20 @@ Returns the information of the specified host.
"disk_encryption": "verified",
"action_required": null
},
+ "apple_settings": {
+ "disk_encryption": "verified",
+ "action_required": null
+ },
"macos_setup": {
"bootstrap_package_status": "installed",
"detail": "",
"bootstrap_package_name": "test.pkg"
},
+ "setup_experience": {
+ "bootstrap_package_status": "installed",
+ "detail": "",
+ "bootstrap_package_name": "test.pkg"
+ },
"os_settings": {
"disk_encryption": {
"status": "verified",
@@ -3979,10 +4037,18 @@ If `hostname` is specified when there is more than one host with the same hostna
"disk_encryption": null,
"action_required": null
},
+ "apple_settings": {
+ "disk_encryption": null,
+ "action_required": null
+ },
"macos_setup": {
"bootstrap_package_status": "installed",
"detail": ""
},
+ "setup_experience": {
+ "bootstrap_package_status": "installed",
+ "detail": ""
+ },
"os_settings": {
"disk_encryption": {
"status": null,
@@ -4197,11 +4263,20 @@ X-Client-Cert-Serial:
"disk_encryption": "verified",
"action_required": null
},
+ "apple_settings": {
+ "disk_encryption": "verified",
+ "action_required": null
+ },
"macos_setup": {
"bootstrap_package_status": "installed",
"detail": "",
"bootstrap_package_name": "test.pkg"
},
+ "setup_experience": {
+ "bootstrap_package_status": "installed",
+ "detail": "",
+ "bootstrap_package_name": "test.pkg"
+ },
"os_settings": {
"disk_encryption": {
"status": "verified",
@@ -12269,7 +12344,7 @@ _Available in Fleet Premium_
`GET /api/v1/fleet/fleets/:id`
-`mdm.macos_settings.custom_settings`, `mdm.windows_settings.custom_settings`, `scripts`, and `mdm.macos_setup` only include the configuration profiles, scripts, and setup experience settings applied using [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To list profiles, scripts, or setup experience settings added in the UI or API, use the [List configuration profiles](https://fleetdm.com/docs/rest-api/rest-api#list-configuration-profiles), [List scripts](https://fleetdm.com/docs/rest-api/rest-api#list-scripts), or GET endpoints from [Setup experience](https://fleetdm.com/docs/rest-api/rest-api#setup-experience) instead.
+`mdm.apple_settings.configuration_profiles`, `mdm.windows_settings.configuration_profiles`, `scripts`, and `mdm.setup_experience` only include the configuration profiles, scripts, and setup experience settings applied using [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To list profiles, scripts, or setup experience settings added in the UI or API, use the [List configuration profiles](https://fleetdm.com/docs/rest-api/rest-api#list-custom-os-settings-configuration-profiles), [List scripts](https://fleetdm.com/docs/rest-api/rest-api#list-scripts), or GET endpoints from [Setup experience](https://fleetdm.com/docs/rest-api/rest-api#setup-experience) instead.
"Unassigned" (id 0) will only return `id`, `name`, `webhook_settings.failing_policies_webhook`, `integrations.jira`, and `integrations.zendesk` fields.
@@ -12349,6 +12424,14 @@ _Available in Fleet Premium_
}
]
},
+ "apple_settings": {
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile1.mobileconfig",
+ "labels": ["Label 1", "Label 2"]
+ }
+ ]
+ },
"windows_settings": {
"custom_settings": [
{
@@ -12356,6 +12439,12 @@ _Available in Fleet Premium_
"labels": ["Label 3", "Label 4"]
}
],
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile2.xml",
+ "labels": ["Label 3", "Label 4"]
+ }
+ ]
},
"macos_setup": {
"bootstrap_package": "",
@@ -12363,6 +12452,13 @@ _Available in Fleet Premium_
"macos_setup_assistant": "path/to/config.json",
"enable_release_device_manually": false,
"manual_agent_install": false
+ },
+ "setup_experience": {
+ "bootstrap_package": "",
+ "enable_end_user_authentication": false,
+ "apple_setup_assistant": "path/to/config.json",
+ "enable_release_device_manually": false,
+ "manual_agent_install": false
}
}
}
@@ -12688,7 +12784,7 @@ Returned when the requested name only differs from another fleet's name by lette
| windows_updates | object | See [`mdm.windows_updates`](#mdm-windows-updates2). |
| macos_settings | object | See [`mdm.macos_settings`](#mdm-macos-settings2). |
| windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings2). |
-| macos_setup | object | See [`mdm.macos_setup`](#mdm-macos-setup2). |
+| setup_experience | object | See [`mdm.setup_experience`](#mdm-setup-experience2). |
@@ -12762,10 +12858,10 @@ Returned when the requested name only differs from another fleet's name by lette
-##### mdm.macos_setup
+##### mdm.setup_experience
-`mdm.macos_setup` is an object with the following structure:
+`mdm.setup_experience` is an object with the following structure:
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -12795,8 +12891,8 @@ Returned when the requested name only differs from another fleet's name by lette
"deadline_days": 5,
"grace_period_days": 1
},
- "macos_settings": {
- "custom_settings": [
+ "apple_settings": {
+ "configuration_profiles": [
{
"path": "path/to/profile1.mobileconfig",
"labels": ["Label 1", "Label 2"]
@@ -12813,9 +12909,15 @@ Returned when the requested name only differs from another fleet's name by lette
"path": "path/to/profile3.xml",
"labels": ["Label 1", "Label 2"]
}
+ ],
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile3.xml",
+ "labels": ["Label 1", "Label 2"]
+ }
]
},
- "macos_setup": {
+ "setup_experience": {
"enable_end_user_authentication": false
}
}
@@ -12939,6 +13041,14 @@ _Available in Fleet Premium_
}
]
},
+ "apple_settings": {
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile1.mobileconfig",
+ "labels": ["Label 1", "Label 2"]
+ }
+ ]
+ },
"windows_settings": {
"custom_settings": [
{
@@ -12946,11 +13056,22 @@ _Available in Fleet Premium_
"labels": ["Label 3", "Label 4"]
}
],
+ "configuration_profiles": [
+ {
+ "path": "path/to/profile2.xml",
+ "labels": ["Label 3", "Label 4"]
+ }
+ ]
},
"macos_setup": {
"bootstrap_package": "",
"enable_end_user_authentication": false,
"macos_setup_assistant": "path/to/config.json"
+ },
+ "setup_experience": {
+ "bootstrap_package": "",
+ "enable_end_user_authentication": false,
+ "apple_setup_assistant": "path/to/config.json"
}
},
"users": [