From 049a82e77ab7bbb487c95e8816d72f7553be7f77 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Tue, 10 Mar 2026 11:25:39 +0100 Subject: [PATCH 1/3] Added details of live and read health check probes, the `UpgradingViewPath` configuration setting and updates to the boot and HTTP responsiveness behaviour in unnattended upgrades. --- 17/umbraco-cms/SUMMARY.md | 1 + .../fundamentals/setup/server-setup/README.md | 4 + .../setup/server-setup/health-probes.md | 81 +++++++++++++++++++ .../setup/upgrading/upgrade-unattended.md | 28 ++++++- .../reference/configuration/globalsettings.md | 8 ++ 5 files changed, 118 insertions(+), 4 deletions(-) create mode 100644 17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md diff --git a/17/umbraco-cms/SUMMARY.md b/17/umbraco-cms/SUMMARY.md index abe540cd1dd..218859219ec 100644 --- a/17/umbraco-cms/SUMMARY.md +++ b/17/umbraco-cms/SUMMARY.md @@ -42,6 +42,7 @@ * [File And Folder Permissions](fundamentals/setup/server-setup/permissions.md) * [Runtime Modes](fundamentals/setup/server-setup/runtime-modes.md) * [Running Umbraco in Docker](fundamentals/setup/server-setup/running-umbraco-in-docker.md) + * [Health Probes](fundamentals/setup/server-setup/health-probes.md) * [Umbraco in Load Balanced Environments](fundamentals/setup/server-setup/load-balancing/README.md) * [Load Balancing Azure Web Apps](fundamentals/setup/server-setup/load-balancing/azure-web-apps.md) * [Load Balancing the Backoffice](fundamentals/setup/server-setup/load-balancing/load-balancing-backoffice.md) diff --git a/17/umbraco-cms/fundamentals/setup/server-setup/README.md b/17/umbraco-cms/fundamentals/setup/server-setup/README.md index 3a12b2f5893..0afd4da2178 100644 --- a/17/umbraco-cms/fundamentals/setup/server-setup/README.md +++ b/17/umbraco-cms/fundamentals/setup/server-setup/README.md @@ -29,3 +29,7 @@ Best practices for running Umbraco on Azure Web Apps. ## [Runtime modes](runtime-modes.md) The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment. + +## [Health Probes](health-probes.md) + +Use .NET health check endpoints to monitor whether your Umbraco application is alive and ready to serve requests. diff --git a/17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md b/17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md new file mode 100644 index 00000000000..6f53bcb24d2 --- /dev/null +++ b/17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md @@ -0,0 +1,81 @@ +--- +description: Use .NET health probe endpoints to monitor whether your Umbraco application is alive and ready to serve requests. +--- + +# Health Probes + +.NET includes a built-in [health checks](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/implement-resilient-applications/monitor-app-health) middleware that exposes HTTP endpoints reporting whether an application is alive and functioning. Orchestrators, load balancers, and monitoring tools poll these endpoints to decide if an instance should receive traffic. + +{% hint style="info" %} +These endpoints are infrastructure-level HTTP probes used by orchestrators and load balancers. They are different from the [Health Check dashboard](../../../extending/health-check/) in the backoffice, which validates Umbraco and website specific best practices. +{% endhint %} + +## Overview + +Umbraco builds on this middleware and exposes two health probe endpoints that reflect the current runtime state. These endpoints are available in Umbraco 17.3 and later. + +## Endpoints + +| Endpoint | Behavior | +|---|---| +| `GET /umbraco/api/health/live` | Returns HTTP 200 if the process is responding. No checks run. | +| `GET /umbraco/api/health/ready` | Returns HTTP 200 when the site is running normally. Returns HTTP 503 when the site is not ready, for example during startup or an unattended upgrade. | + +Both endpoints are anonymous and bypass the maintenance page re-route that is active during upgrades. + +## Configuring health probes + +Use the endpoints above to configure liveness and readiness probes on your hosting platform. + +Examples for some common hosting environments are shown below. + +### Azure App Service + +In the Azure Portal, navigate to your App Service and open **Monitoring > Health check**. Set the path to: + +``` +/umbraco/api/health/ready +``` + +Azure uses this path to determine whether the instance is healthy and should receive traffic. + +### Kubernetes + +```yaml +livenessProbe: + httpGet: + path: /umbraco/api/health/live + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 10 +readinessProbe: + httpGet: + path: /umbraco/api/health/ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +### Docker Compose + +```yaml +services: + umbraco: + image: my-umbraco-app + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/umbraco/api/health/ready"] + interval: 10s + timeout: 5s + retries: 3 + start_period: 30s +``` + +### Load balancers + +Use the readiness probe path (`/umbraco/api/health/ready`) as the health check URL for your load balancer. The endpoint returns HTTP 503 while the site is upgrading. This causes the load balancer to stop routing traffic to that node until the upgrade completes. For more details on load-balanced setups, see [Umbraco in Load Balanced Environments](load-balancing/). + +## Related + +* [Upgrade Unattended](../upgrading/upgrade-unattended.md) +* [Umbraco in Load Balanced Environments](load-balancing/README.md) +* [Running Umbraco in Docker](running-umbraco-in-docker.md) diff --git a/17/umbraco-cms/fundamentals/setup/upgrading/upgrade-unattended.md b/17/umbraco-cms/fundamentals/setup/upgrading/upgrade-unattended.md index dc5e184078e..b9e849e226c 100644 --- a/17/umbraco-cms/fundamentals/setup/upgrading/upgrade-unattended.md +++ b/17/umbraco-cms/fundamentals/setup/upgrading/upgrade-unattended.md @@ -41,12 +41,30 @@ With the correct configuration applied, the project will be upgraded on the next ### Boot order -The Runtime level uses `Run` instead of `Upgrade` to allow the website to continue to boot up directly after the migration is run. This happens instead of initiating the otherwise required restart. - -{% hint style="info" %} -The upgrade is run after Composers but before Components, and the `UmbracoApplicationStartingNotification`. This is because the migration requires services that are registered in Composers, and Components require that Umbraco and the database are ready. +{% hint style=”info” %} +The behavior described below applies to Umbraco 17.3 and later. In earlier versions, migrations ran synchronously before the web server started accepting requests. {% endhint %} +When the application starts, migrations run in a background service after the web server begins listening. During the migration the RuntimeLevel is `Upgrading`. The web server is reachable during this time, serving health probe responses and maintenance pages. + +Once all migrations complete, the RuntimeLevel transitions to `Run` and the site operates normally. + +### HTTP behavior during upgrade + +While the RuntimeLevel is `Upgrading`, Umbraco responds differently depending on the request surface: + +| Surface | Behavior | +|---|---| +| Frontend | HTTP 503 with `Upgrading.cshtml` view | +| Surface controllers | HTTP 503 with `Upgrading.cshtml` view | +| Backoffice | Upgrade-in-progress screen | +| Management API | HTTP 503 JSON ProblemDetails | +| Delivery API | HTTP 503 JSON ProblemDetails | + +The [liveness probe](../server-setup/health-probes.md) returns HTTP 200 during the upgrade, confirming the process is alive. The [readiness probe](../server-setup/health-probes.md) returns HTTP 503, indicating the site is not yet ready to serve normal traffic. + +You can customize the maintenance page shown to frontend visitors by setting the `Umbraco:CMS:Global:UpgradingViewPath` configuration key. See [Global Settings](../../../reference/configuration/globalsettings.md#upgrading-view-path) for details. + ## Unattended upgrades in a load-balanced setup Follow the steps outlined below to use unattended upgrades in a load-balanced setup. @@ -57,3 +75,5 @@ Follow the steps outlined below to use unattended upgrades in a load-balanced se 4. Boot the Main server, and the upgrade will run automatically. 5. Wait for the upgrade to complete. 6. Boot the **Read-Only** servers and ensure they do not show the “Upgrade Required” screen. + +You can use the [readiness probe](../server-setup/health-probes.md) to let your load balancer detect when each server has completed its upgrade and is ready to receive traffic. diff --git a/17/umbraco-cms/reference/configuration/globalsettings.md b/17/umbraco-cms/reference/configuration/globalsettings.md index e9f95c640d7..25a5025e24e 100644 --- a/17/umbraco-cms/reference/configuration/globalsettings.md +++ b/17/umbraco-cms/reference/configuration/globalsettings.md @@ -31,6 +31,7 @@ The following snippet contains all the available options, with default values, a "MainDomKeyDiscriminator": "", "Id": "184a8175-bc0b-43dd-8267-d99871eaec3d", "NoNodesViewPath": "~/umbraco/UmbracoWebsite/NoNodes.cshtml", + "UpgradingViewPath": "~/umbraco/UmbracoWebsite/Upgrading.cshtml", "Smtp": { "From": "person@umbraco.dk", "Host": "localhost", @@ -242,6 +243,13 @@ Type: `string` (default: `~/umbraco/UmbracoWebsite/NoNodes.cshtml`) This setting specifies what view to render when there is no content on the site. +### Upgrading view path + +Key: `UpgradingViewPath` +Type: `string` (default: `~/umbraco/UmbracoWebsite/Upgrading.cshtml`) + +This setting specifies the view to render when an unattended upgrade is running in the background. Frontend and surface controller requests receive an HTTP 503 response with this view during the upgrade. See [Upgrade Unattended](../../fundamentals/setup/upgrading/upgrade-unattended.md) for details on the upgrade process. + ## SMTP settings By adding this settings to the appsettings.json you will be able to send out emails from your Umbraco installation. This could be notifications emails if you are using content workflow, or you are using Umbraco Forms you also need to specify SMTP settings to be able use the email workflows. The forgot password function from the backoffice also needs a SMTP server to send the email with the reset link. From 48ad05e5687bc45e8665cb692c05a2309b6a9e2b Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Tue, 10 Mar 2026 11:41:27 +0100 Subject: [PATCH 2/3] Add cross-reference from Umbraco health checks. --- 17/umbraco-cms/extending/health-check/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/17/umbraco-cms/extending/health-check/README.md b/17/umbraco-cms/extending/health-check/README.md index 7509667dcd7..b433e418859 100644 --- a/17/umbraco-cms/extending/health-check/README.md +++ b/17/umbraco-cms/extending/health-check/README.md @@ -4,6 +4,10 @@ description: "Health Checks are used to determine the state of your Umbraco proj # Health Check +{% hint style="info" %} +Looking for the .NET health probe endpoints used by orchestrators and load balancers? See [Health Probes](../../fundamentals/setup/server-setup/health-probes.md). +{% endhint %} + The Settings section of the Umbraco backoffice holds a dashboard named "Health Check". It is a handy list of checks to see if your Umbraco installation is configured according to best practices. It's possible to add your custom-built health checks. For inspiration when building your checks you can look at the checks we've [built into Umbraco](https://github.com/umbraco/Umbraco-CMS/tree/v16/dev/src/Umbraco.Core/HealthChecks/Checks), as well as our [guides](guides/). Some examples will follow in this document. From 0ced4b7098c7495dbf57f810d7bcb393db3fa421 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Tue, 10 Mar 2026 13:36:14 +0100 Subject: [PATCH 3/3] Fix minor grammar in health probes article --- .../fundamentals/setup/server-setup/health-probes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md b/17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md index 6f53bcb24d2..44602dab2fe 100644 --- a/17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md +++ b/17/umbraco-cms/fundamentals/setup/server-setup/health-probes.md @@ -7,7 +7,7 @@ description: Use .NET health probe endpoints to monitor whether your Umbraco app .NET includes a built-in [health checks](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/implement-resilient-applications/monitor-app-health) middleware that exposes HTTP endpoints reporting whether an application is alive and functioning. Orchestrators, load balancers, and monitoring tools poll these endpoints to decide if an instance should receive traffic. {% hint style="info" %} -These endpoints are infrastructure-level HTTP probes used by orchestrators and load balancers. They are different from the [Health Check dashboard](../../../extending/health-check/) in the backoffice, which validates Umbraco and website specific best practices. +These endpoints are infrastructure-level HTTP probes used by orchestrators and load balancers. They are different from the [Health Check dashboard](../../../extending/health-check/) in the backoffice, which validates Umbraco and website-specific best practices. {% endhint %} ## Overview @@ -19,9 +19,9 @@ Umbraco builds on this middleware and exposes two health probe endpoints that re | Endpoint | Behavior | |---|---| | `GET /umbraco/api/health/live` | Returns HTTP 200 if the process is responding. No checks run. | -| `GET /umbraco/api/health/ready` | Returns HTTP 200 when the site is running normally. Returns HTTP 503 when the site is not ready, for example during startup or an unattended upgrade. | +| `GET /umbraco/api/health/ready` | Returns HTTP 200 when the site is running normally. Returns HTTP 503 when the site is not ready, for example, during startup or an unattended upgrade. | -Both endpoints are anonymous and bypass the maintenance page re-route that is active during upgrades. +Both endpoints are anonymous and bypass the maintenance-page re-route active during upgrades. ## Configuring health probes