diff --git a/docs/content/admin/feature_flags/PRO__feature_flags.md b/docs/content/admin/feature_flags/PRO__feature_flags.md index 09cbfb45a5..512127c628 100644 --- a/docs/content/admin/feature_flags/PRO__feature_flags.md +++ b/docs/content/admin/feature_flags/PRO__feature_flags.md @@ -62,18 +62,20 @@ The tag is shown only while a restart is actually outstanding. Once the running **Organization / Asset Relabeling** renames "Product Type" to "Organization" and "Product" to "Asset". It is on by default and toggles from this page like any other feature, but it is worth knowing which parts of DefectDojo it governs: * The **Pro UI** follows this toggle. The new labels appear on your next page load. -* The **Classic UI** pages, their URLs, and generated reports take their naming from the `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` deployment setting (also on by default), which is read when DefectDojo starts. This toggle does not change them, and restarting does not make it change them. +* The **Classic UI** pages, their URLs, and generated reports take their naming when DefectDojo starts. They follow this toggle after the next restart, in either direction. You do not need to change a deployment setting: DefectDojo reads the stored toggle at start-up and applies it to those surfaces itself. -The stored toggle was seeded from that deployment setting, so the two agree until you change one of them. If you turn relabeling off here and you also use the Classic UI, set `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL=False` on your deployment and restart so both surfaces match. On [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), contact [DefectDojo Support](mailto:support@defectdojo.com) to have the deployment setting changed. +Until you restart, the Classic UI keeps the naming the process started with, so it can disagree with the Pro UI for a while. On [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), contact [DefectDojo Support](mailto:support@defectdojo.com) if you need a restart scheduled. The feature carries a **Restart Recommended** tag on the Feature Flags page for this reason: the naming used outside the Pro UI is fixed when the process starts. The tag shows only while a restart is still outstanding, and clears once you have restarted or toggled the flag back (see [Restart Recommended](#restart-recommended)). Relabeling is cosmetic either way. Database models, field names, and API endpoints are unchanged, so existing automation keeps working. See [Asset Hierarchy](/asset_modelling/pro_hierarchy/asset_hierarchy/). +The `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` deployment setting still exists, but only as the value the stored toggle was seeded from on upgrade and as a fallback when the database cannot be reached at start-up. Once the toggle has a stored value, the database owns it. + ### Locations **Locations** replaces the legacy Endpoints model: with it on, imports create Location records and the UI and API surface Locations; with it off, imports create Endpoints. It is off by default and is enabled from this page like any other feature, but a few things are worth knowing: * The **Pro UI** and the **import pipeline** follow this toggle. After you enable Locations, new imports create Locations and the Locations pages appear on your next page load, without a restart. -* The **Classic UI** pages and the `/api/v2` endpoint/location route wiring are decided from the `DD_V3_FEATURE_LOCATIONS` deployment setting when DefectDojo starts. This toggle does not change them, and restarting does not make it change them. If you use the Classic UI or depend on the `/api/v2` endpoint routes, set `DD_V3_FEATURE_LOCATIONS` to match and restart so every surface agrees. The stored toggle is seeded from that deployment setting on upgrade, so an instance that already ran with `DD_V3_FEATURE_LOCATIONS=True` comes up with the toggle already on (and locked), and the database owns the value from then on. +* The **Classic UI** pages and the `/api/v2` endpoint/location route wiring are decided when DefectDojo starts. They follow this toggle after the next restart: the `/api/v2/location/` routes (and the `/api/v3/` API) are mounted and listed in the API documentation, and `/api/v2/endpoints/` is served read-compatibly from Locations. You do not need to change a deployment setting. Until you restart, those routes stay as they were when the process started, so `/api/v2/location/` answers 404 in the meantime. The stored toggle is seeded from the `DD_V3_FEATURE_LOCATIONS` deployment setting on upgrade, so an instance that already ran with `DD_V3_FEATURE_LOCATIONS=True` comes up with the toggle already on (and locked); from then on the database owns the value and the setting is only a fallback for when the database cannot be reached at start-up. * Enabling existing history is not automatic. Your existing data stays as it is until you run the **data-migration suite** that appears under this row once Locations is on: three backfills (endpoints, dependencies, and source-code locations) followed by an identity rehash that unlocks once all three finish. Each is superuser-run, shows progress, is safe to re-run, and can be cancelled while running (it stops at the next batch boundary and can be resumed). Each item can also be **marked complete**, automatically when a run here finishes or by hand for a migration you ran another way, so the page stops prompting you to run it. See [Migrating from Endpoints](/asset_modelling/locations/pro__migrating_from_endpoints/). Enabling Locations is **self-service and one-way**: once it is on, the toggle locks (shown as **Cannot Be Disabled**), because turning it back off would require reversing the endpoint-to-location data migration, which is not yet supported. The feature carries a **Restart Recommended** tag for the Classic UI / API reason above; as with any such feature, the tag clears once the server has been restarted (see [Restart Recommended](#restart-recommended)). @@ -125,8 +127,8 @@ Most features are available on both installation types. The exceptions are: | Feature | Availability | How it is controlled | | --- | --- | --- | | Request a New Connector | [DefectDojo Pro (Cloud)](/get_started/pro/cloud/) only | Always on for Cloud instances, and not offered on-premise. No longer listed on the Feature Flags page. | -| Locations | Both | Feature Flags page for the Pro UI and import pipeline; the Classic UI and `/api/v2` route wiring follow the `DD_V3_FEATURE_LOCATIONS` deployment setting. Enabling is self-service and one-way — once on, it cannot be turned back off. See [above](#locations) and [Locations Overview](/asset_modelling/locations/pro__locations_overview/). | -| Organization / Asset Relabeling | Both | Feature Flags page for the Pro UI; the Classic UI, its URLs and generated reports follow the `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` deployment setting. See [above](#organization--asset-relabeling). | +| Locations | Both | Feature Flags page. The Pro UI and import pipeline follow it right away; the Classic UI and `/api/v2` route wiring follow it after a restart. Enabling is self-service and one-way: once on, it cannot be turned back off. See [above](#locations) and [Locations Overview](/asset_modelling/locations/pro__locations_overview/). | +| Organization / Asset Relabeling | Both | Feature Flags page. The Pro UI follows it right away; the Classic UI, its URLs and generated reports follow it after a restart. See [above](#organization--asset-relabeling). | Every other optional feature is toggled directly on the Feature Flags page on both Cloud and On-Premise instances. diff --git a/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.md b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.md index a3811915a8..21782456b0 100644 --- a/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.md +++ b/docs/content/asset_modelling/PRO_hierarchy/asset_hierarchy.md @@ -26,9 +26,9 @@ Asset Hierarchy is generally available and on for every instance, Cloud and On-P Label changes are on by default as of 3.0. There are two controls, covering different parts of the application: * **Pro UI** (the default UI): a superuser toggles "Organization / Asset Relabeling" at **Settings > Feature Flags**, on both Cloud and On-Premise instances. The new labels appear on the next page load. See [Feature Flags](/admin/feature_flags/pro__feature_flags/). -* **Classic UI pages and generated reports**: their labels and URLs come from the `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` deployment setting, which is read when DefectDojo starts. On-premise, set it and restart DefectDojo. On [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), email [support@defectdojo.com](mailto:support@defectdojo.com) with your instance URL. +* **Classic UI pages and generated reports**: their labels and URLs are decided when DefectDojo starts, so they follow the same toggle after the next restart. On-premise, restart DefectDojo after changing the toggle. On [DefectDojo Pro (Cloud)](/get_started/pro/cloud/), email [support@defectdojo.com](mailto:support@defectdojo.com) with your instance URL if you need a restart scheduled. -Both default to on, and the Feature Flags value was seeded from the deployment setting, so the two agree unless you change one of them. Keep them in sync if you use the Classic UI as well as the Pro UI. +The toggle is on by default. Its stored value was seeded from the `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` deployment setting on upgrade; from then on the database owns it, and the setting is only a fallback for when the database cannot be reached at start-up. Note that label changes are cosmetic only: API endpoints and field names remain unchanged, so existing automation will continue to work. diff --git a/docs/content/asset_modelling/locations/PRO__locations_overview.md b/docs/content/asset_modelling/locations/PRO__locations_overview.md index 4361ac4797..c1526a50bf 100644 --- a/docs/content/asset_modelling/locations/PRO__locations_overview.md +++ b/docs/content/asset_modelling/locations/PRO__locations_overview.md @@ -7,7 +7,7 @@ weight: 1 **Locations** are a new asset-modelling tool in DefectDojo Pro. They replace the legacy **Endpoints** model and absorb the previous **Components** (library) data, giving DefectDojo a single, polymorphic way to describe *where* a Finding lives — whether that's a URL, a software dependency from an **SBOM**, or, in the future, a **cloud resource ID**, **container image**, or **code repository**. -Locations must be enabled on your instance before you can use them. You can turn Locations on yourself from the [Feature Flags page](/admin/feature_flags/pro__feature_flags/) — no Support request is required. Enabling is one-way and takes effect for new imports right away; your existing history stays as it is until you run the [migration suite](/asset_modelling/locations/pro__migrating_from_endpoints/) that appears under the flag (endpoint, dependency, and source-code backfills, then an identity rehash). If you also use the Classic UI or depend on the `/api/v2` endpoint routes, keep the `DD_V3_FEATURE_LOCATIONS` deployment setting in sync and restart, since those surfaces are fixed when DefectDojo starts. +Locations must be enabled on your instance before you can use them. You can turn Locations on yourself from the [Feature Flags page](/admin/feature_flags/pro__feature_flags/) — no Support request is required. Enabling is one-way and takes effect for new imports right away; your existing history stays as it is until you run the [migration suite](/asset_modelling/locations/pro__migrating_from_endpoints/) that appears under the flag (endpoint, dependency, and source-code backfills, then an identity rehash). If you also use the Classic UI or depend on the `/api/v2` endpoint routes, restart DefectDojo after enabling: those surfaces are decided when DefectDojo starts, and they pick up the toggle on the next start. No deployment setting needs to change. ## Why Replace Endpoints? diff --git a/docs/content/releases/os_upgrading/3.3.200.md b/docs/content/releases/os_upgrading/3.3.200.md new file mode 100644 index 0000000000..81aebe4ca7 --- /dev/null +++ b/docs/content/releases/os_upgrading/3.3.200.md @@ -0,0 +1,28 @@ +--- +title: 'Upgrading to DefectDojo Version 3.3.200' +toc_hide: true +weight: -20260921 +description: In DefectDojo Pro, a restart now applies the Locations and Organization / Asset Relabeling toggles to the Classic UI and the /api/v2 route wiring. Those surfaces used to keep following the deployment environment variables no matter what the Feature Flags page said. +--- + +## Feature Flags toggles reach the Classic UI and `/api/v2` after a restart (DefectDojo Pro) + +Two features on the **Settings > Feature Flags** page, **Locations** and **Organization / Asset Relabeling**, have parts that are decided when DefectDojo starts: the Classic UI pages and labels, the `/api/v2` endpoint and location routes, and the `/api/v3/` API. Both carry a **Restart Recommended** tag for that reason. + +Before this release the tag over-promised. Those start-time surfaces read the `DD_V3_FEATURE_LOCATIONS` and `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL` deployment settings, and nothing carried the stored toggle into them, so a restart changed nothing. An operator who enabled Locations on the page and restarted still got a 404 from `/api/v2/location/`, and the routes were missing from the API documentation, until the environment variable was changed as well. The 3.2.200 notes told you to keep the deployment setting in sync for exactly this reason. + +DefectDojo Pro now reads each of these stored toggles at start-up and applies it to the deployment setting for the life of the process. After a restart: + +- With Locations on, `/api/v2/location/`, `/api/v2/url/` and the `/api/v3/` API are mounted and appear in the API documentation, `/api/v2/endpoints/` is served read-compatibly from Locations, and the Classic UI shows the Locations pages. +- Organization / Asset Relabeling follows the toggle on the Classic UI pages, their URLs and generated reports, in either direction. +- The **Restart Recommended** tag clears, and now means what it says. + +### What you need to do + +- **Nothing, if you already kept the environment variables in sync.** The stored toggle and the setting agree, so start-up changes nothing. +- **If you enabled a toggle on the page without changing your deployment**: restart DefectDojo. You no longer need to set `DD_V3_FEATURE_LOCATIONS` or `DD_ENABLE_V3_ORGANIZATION_ASSET_RELABEL`; they remain only as the seed for the stored value on upgrade and as a fallback when the database cannot be reached at start-up. +- **To keep a process pinned to its environment instead**, set `DD_FEATURE_FLAGS_BOOT_SYNC=False`. This is meant for test harnesses and unusual deployments; the default is on. + +Open source DefectDojo is unaffected: with the `pro` app absent, the deployment settings continue to govern these features exactly as before. + +For more information, check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/3.3.200).