From dbea332e5bb676902542a0a2c8fce7dae2f4c2d1 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Fri, 17 Jan 2025 16:32:13 -0600 Subject: [PATCH 1/9] Update rest-api.md --- docs/REST API/rest-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 5fd111065a11..561228d475e8 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -837,6 +837,7 @@ None. "features": { "enable_host_users": true, "enable_software_inventory": true, + "enable_gitops_mode": false, "additional_queries": null }, "mdm": { @@ -1130,6 +1131,7 @@ Modifies the Fleet's configuration with the supplied information. "features": { "enable_host_users": true, "enable_software_inventory": true, + "enable_gitops_mode": false, "additional_queries": null }, "license": { @@ -1866,6 +1868,7 @@ _Available in Fleet Premium._ | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_host_users | boolean | Whether to enable the users feature in Fleet. (Default: `true`) | | enable_software_inventory | boolean | Whether to enable the software inventory feature in Fleet. (Default: `true`) | +| enable_gitops_mode | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | | additional_queries | boolean | Whether to enable additional queries on hosts. (Default: `null`) |
@@ -1877,6 +1880,7 @@ _Available in Fleet Premium._ "features": { "enable_host_users": true, "enable_software_inventory": true, + "enable_gitops_mode": false, "additional_queries": null } } From 6226d95be67f86ec19981d8afa3e1e52790c3ee7 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Thu, 23 Jan 2025 13:33:18 -0600 Subject: [PATCH 2/9] Update rest-api.md --- docs/REST API/rest-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 561228d475e8..742efaeead5f 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -838,6 +838,7 @@ None. "enable_host_users": true, "enable_software_inventory": true, "enable_gitops_mode": false, + "gitops_repo_url": "", "additional_queries": null }, "mdm": { @@ -1132,6 +1133,7 @@ Modifies the Fleet's configuration with the supplied information. "enable_host_users": true, "enable_software_inventory": true, "enable_gitops_mode": false, + "gitops_repo_url": "", "additional_queries": null }, "license": { @@ -1869,6 +1871,7 @@ _Available in Fleet Premium._ | enable_host_users | boolean | Whether to enable the users feature in Fleet. (Default: `true`) | | enable_software_inventory | boolean | Whether to enable the software inventory feature in Fleet. (Default: `true`) | | enable_gitops_mode | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | +| gitops_repo_url | string | The URL for the repository where changes are managed, for Fleet instances using GitOps. Users will be sent here when GitOps mode is enabled. | | additional_queries | boolean | Whether to enable additional queries on hosts. (Default: `null`) |
@@ -1881,6 +1884,7 @@ _Available in Fleet Premium._ "enable_host_users": true, "enable_software_inventory": true, "enable_gitops_mode": false, + "gitops_repo_url": "", "additional_queries": null } } From 1c557bd57efd5be7dc2c26ac05d1dafc8a78acd7 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Thu, 23 Jan 2025 17:54:09 -0600 Subject: [PATCH 3/9] API design: Move GitOps settings into their own config object --- docs/REST API/rest-api.md | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 742efaeead5f..6dd47bbea53c 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -834,11 +834,13 @@ None. "activity_expiry_enabled": false, "activity_expiry_window": 0 }, + "gitops_settings": { + "gitops_mode_enabled": false, + "repository_url": "", + }, "features": { "enable_host_users": true, "enable_software_inventory": true, - "enable_gitops_mode": false, - "gitops_repo_url": "", "additional_queries": null }, "mdm": { @@ -1053,6 +1055,7 @@ Modifies the Fleet's configuration with the supplied information. | sso_settings | object | body | See [sso_settings](#sso-settings). | | host_expiry_settings | object | body | See [host_expiry_settings](#host-expiry-settings). | | activity_expiry_settings | object | body | See [activity_expiry_settings](#activity-expiry-settings). | +| gitops_settings | object | body | See [gitops_settings](#gitops-settings). | | agent_options | objects | body | The agent_options spec that is applied to all hosts. In Fleet 4.0.0 the `api/v1/fleet/spec/osquery_options` endpoints were removed. | | fleet_desktop | object | body | See [fleet_desktop](#fleet-desktop). | | webhook_settings | object | body | See [webhook_settings](#webhook-settings). | @@ -1129,11 +1132,13 @@ Modifies the Fleet's configuration with the supplied information. "activity_expiry_enabled": false, "activity_expiry_window": 0 }, + "gitops_settings": { + "gitops_mode_enabled": false, + "repository_url": "", + }, "features": { "enable_host_users": true, "enable_software_inventory": true, - "enable_gitops_mode": false, - "gitops_repo_url": "", "additional_queries": null }, "license": { @@ -1462,6 +1467,26 @@ Modifies the Fleet's configuration with the supplied information. } ``` +#### gitops_settings + +| Name | Type | Description | +| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| gitops_mode_enabled | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | +| repository_url | string | The URL for the repository where changes are managed, for Fleet instances using GitOps. Users will be sent here when GitOps mode is enabled. | + +
+ +##### Example request body + +```json +{ + "gitops_settings": { + "gitops_mode_enabled": true, + "repository_url": "https://github.com/fleetdm/fleet/tree/main/it-and-security" + } +} +``` + #### fleet_desktop _Available in Fleet Premium._ @@ -1870,8 +1895,6 @@ _Available in Fleet Premium._ | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_host_users | boolean | Whether to enable the users feature in Fleet. (Default: `true`) | | enable_software_inventory | boolean | Whether to enable the software inventory feature in Fleet. (Default: `true`) | -| enable_gitops_mode | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | -| gitops_repo_url | string | The URL for the repository where changes are managed, for Fleet instances using GitOps. Users will be sent here when GitOps mode is enabled. | | additional_queries | boolean | Whether to enable additional queries on hosts. (Default: `null`) |
From 864fca92b666cf1fba9ebc4b37326ca06ad09161 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Thu, 23 Jan 2025 17:56:45 -0600 Subject: [PATCH 4/9] Cleanup from previous GitOps mode API design --- docs/REST API/rest-api.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 6dd47bbea53c..a99b73a0e2f4 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -1906,8 +1906,6 @@ _Available in Fleet Premium._ "features": { "enable_host_users": true, "enable_software_inventory": true, - "enable_gitops_mode": false, - "gitops_repo_url": "", "additional_queries": null } } From c4c92c7a23fcd3d4017a8a422125845ebc09d4d9 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Mon, 27 Jan 2025 17:59:32 -0600 Subject: [PATCH 5/9] Update rest-api.md --- docs/REST API/rest-api.md | 50 ++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 29 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index a99b73a0e2f4..5c6c7251a771 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -834,10 +834,6 @@ None. "activity_expiry_enabled": false, "activity_expiry_window": 0 }, - "gitops_settings": { - "gitops_mode_enabled": false, - "repository_url": "", - }, "features": { "enable_host_users": true, "enable_software_inventory": true, @@ -999,6 +995,10 @@ None. "url": "https://example.com/certsrv/mscep/mscep.dll", "username": "Administrator@example.com" }, + "change_management": { + "gitops_mode_enabled": false, + "repository_url": "", + }, "zendesk": [] }, "logging": { @@ -1055,7 +1055,6 @@ Modifies the Fleet's configuration with the supplied information. | sso_settings | object | body | See [sso_settings](#sso-settings). | | host_expiry_settings | object | body | See [host_expiry_settings](#host-expiry-settings). | | activity_expiry_settings | object | body | See [activity_expiry_settings](#activity-expiry-settings). | -| gitops_settings | object | body | See [gitops_settings](#gitops-settings). | | agent_options | objects | body | The agent_options spec that is applied to all hosts. In Fleet 4.0.0 the `api/v1/fleet/spec/osquery_options` endpoints were removed. | | fleet_desktop | object | body | See [fleet_desktop](#fleet-desktop). | | webhook_settings | object | body | See [webhook_settings](#webhook-settings). | @@ -1132,10 +1131,6 @@ Modifies the Fleet's configuration with the supplied information. "activity_expiry_enabled": false, "activity_expiry_window": 0 }, - "gitops_settings": { - "gitops_mode_enabled": false, - "repository_url": "", - }, "features": { "enable_host_users": true, "enable_software_inventory": true, @@ -1275,6 +1270,10 @@ Modifies the Fleet's configuration with the supplied information. } ], "ndes_scep_proxy": null, + "change_management": { + "gitops_mode_enabled": false, + "repository_url": "", + }, "zendesk": [] }, "logging": { @@ -1467,26 +1466,6 @@ Modifies the Fleet's configuration with the supplied information. } ``` -#### gitops_settings - -| Name | Type | Description | -| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | -| gitops_mode_enabled | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | -| repository_url | string | The URL for the repository where changes are managed, for Fleet instances using GitOps. Users will be sent here when GitOps mode is enabled. | - -
- -##### Example request body - -```json -{ - "gitops_settings": { - "gitops_mode_enabled": true, - "repository_url": "https://github.com/fleetdm/fleet/tree/main/it-and-security" - } -} -``` - #### fleet_desktop _Available in Fleet Premium._ @@ -1619,6 +1598,7 @@ _Available in Fleet Premium._ | zendesk | array | See [`integrations.zendesk`](#integrations-zendesk). | | google_calendar | array | See [`integrations.google_calendar`](#integrations-google-calendar). | | ndes_scep_proxy | object | See [`integrations.ndes_scep_proxy`](#integrations-ndes-scep-proxy). | +| change_management | object | See [`integrations.change_management`](#integrations-change_management). |
@@ -1682,6 +1662,14 @@ _Available in Fleet Premium._ Setting `integrations.ndes_scep_proxy` to `null` will clear existing settings. Not specifying `integrations.ndes_scep_proxy` in the payload will not change the existing settings. +##### integrations.change_management + +| Name | Type | Description | +| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| gitops_mode_enabled | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | +| repository_url | string | The URL for the repository where changes are managed, for Fleet instances using GitOps. Users will be sent here when GitOps mode is enabled. | + + ##### Example request body @@ -1710,6 +1698,10 @@ Setting `integrations.ndes_scep_proxy` to `null` will clear existing settings. N "password": "abc123", "url": "https://example.com/certsrv/mscep/mscep.dll", "username": "Administrator@example.com" + }, + "change_management": { + "gitops_mode_enabled": true, + "repository_url": "https://github.com/fleetdm/fleet/tree/main/it-and-security" } } } From 54b0fbba823cc4f422b6ac801ce84e29b3bcff2e Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Mon, 27 Jan 2025 18:00:11 -0600 Subject: [PATCH 6/9] Update docs/REST API/rest-api.md --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 5c6c7251a771..c17decdb7c66 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -1598,7 +1598,7 @@ _Available in Fleet Premium._ | zendesk | array | See [`integrations.zendesk`](#integrations-zendesk). | | google_calendar | array | See [`integrations.google_calendar`](#integrations-google-calendar). | | ndes_scep_proxy | object | See [`integrations.ndes_scep_proxy`](#integrations-ndes-scep-proxy). | -| change_management | object | See [`integrations.change_management`](#integrations-change_management). | +| change_management | object | See [`integrations.change_management`](#integrations-change-management). |
From aec178bae2c83d9706ea8d14d5909e17a33990fb Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Tue, 11 Feb 2025 12:41:43 -0600 Subject: [PATCH 7/9] Configuration API: Move `change_management` out of `integrations` --- docs/REST API/rest-api.md | 53 +++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index c17decdb7c66..d4f06bfd2f42 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -946,6 +946,10 @@ None. "vulnerability_settings": { "databases_path": "" }, + "change_management": { + "gitops_mode_enabled": false, + "repository_url": "", + }, "webhook_settings": { "host_status_webhook": { "enable_host_status_webhook": true, @@ -995,10 +999,6 @@ None. "url": "https://example.com/certsrv/mscep/mscep.dll", "username": "Administrator@example.com" }, - "change_management": { - "gitops_mode_enabled": false, - "repository_url": "", - }, "zendesk": [] }, "logging": { @@ -1058,6 +1058,7 @@ Modifies the Fleet's configuration with the supplied information. | agent_options | objects | body | The agent_options spec that is applied to all hosts. In Fleet 4.0.0 the `api/v1/fleet/spec/osquery_options` endpoints were removed. | | fleet_desktop | object | body | See [fleet_desktop](#fleet-desktop). | | webhook_settings | object | body | See [webhook_settings](#webhook-settings). | +| change_management | object | body | See [change_management](#change-management). | | integrations | object | body | Includes `ndes_scep_proxy` object and `jira`, `zendesk`, and `google_calendar` arrays. See [integrations](#integrations) for details. | | mdm | object | body | See [mdm](#mdm). | | features | object | body | See [features](#features). | @@ -1230,6 +1231,10 @@ Modifies the Fleet's configuration with the supplied information. "fleet_desktop": { "transparency_url": "https://fleetdm.com/better" }, + "change_management": { + "gitops_mode_enabled": false, + "repository_url": "", + }, "webhook_settings": { "host_status_webhook": { "enable_host_status_webhook": true, @@ -1270,10 +1275,6 @@ Modifies the Fleet's configuration with the supplied information. } ], "ndes_scep_proxy": null, - "change_management": { - "gitops_mode_enabled": false, - "repository_url": "", - }, "zendesk": [] }, "logging": { @@ -1486,6 +1487,28 @@ _Available in Fleet Premium._ } ``` +#### change_management + +_Available in Fleet Premium._ + +| Name | Type | Description | +| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| gitops_mode_enabled | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | +| repository_url | string | The URL for the repository where changes are managed, for Fleet instances using GitOps. Users will be sent here when GitOps mode is enabled. | + +
+ +##### Example request body + +```json +{ + "change_management": { + "gitops_mode_enabled": true, + "repository_url": "https://github.com/exampleorg/it-and-security" + } +} +``` + #### webhook_settings