Live/ready checks and unattended upgrades

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)

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.

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.

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 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)

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.

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.