Stay organized with collections
Save and categorize content based on your preferences.
As of September 15, 2019, if you're using the legacy health checks, your
application will continue to run and receive health checks but you won't be
able to deploy new versions of your application.
This page explains upgrading from the legacy health checks to
split health checks.
Verifying your health check type
To verify the type of health checks your application is using, run the
following command:
gcloud app describe
If your application is using split health checks, the description should
include the following information:
featureSettings:splitHealthChecks:true
Understanding key differences
Before upgrading to split health checks, consider the following important
differences between legacy and split health checks:
HTTP requests for split health checks are not forwarded by default.
By contrast, legacy health checks forward to the /_ah/health path in your
application by default.
Forwarded split health checks must return 200 OK when healthy and
ready. Legacy health checks consider the following HTTP codes as healthy:
200, 301, 302, 303, 307, 401, 402, 403, 404, 405.
If you do not specify a liveness check path
or a readiness check path,
by default split health checks only confirm that the VM instance and the
Docker container are running. As long as these conditions hold, the VM will
continue to receive traffic and remain alive regardless of the app's internal
state.
By contrast, when legacy health checks are enabled, if your app's /_ah/health
path starts returning unhealthy HTTP error codes (e.g. 5XX) then legacy health
checks will start failing and the VM will stop receiving traffic and be
restarted.
Configure liveness_check.failure_threshold to the same value. Note the value of your check_interval_sec option multiplied by the failure_threshold option is the time it'll take for an unhealthy VM to be taken down.
Enabling split health checks
To migrate from legacy health checks to split health checks and avoid seeing
elevated 5xx status codes, complete the following steps:
Alternatively, you can customize the liveness_check or readiness_check
section in the app.yaml file for each version. For examples,
see Liveness checks
and Readiness checks.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eLegacy health checks will continue to run, but new application versions cannot be deployed after September 15, 2019, if legacy health checks are still in use.\u003c/p\u003e\n"],["\u003cp\u003eSplit health checks differ from legacy in that HTTP requests are not forwarded by default and they require a \u003ccode\u003e200 OK\u003c/code\u003e response for health and readiness, unlike legacy checks which accept a range of codes.\u003c/p\u003e\n"],["\u003cp\u003eBy default, split health checks verify only that the VM instance and the Docker container are running, but liveness and readiness check paths can be configured for more in-depth application state monitoring.\u003c/p\u003e\n"],["\u003cp\u003eMigrating to split health checks requires understanding the differences, converting legacy health check options, updating with the \u003ccode\u003egcloud\u003c/code\u003e command, removing the \u003ccode\u003ehealth_check\u003c/code\u003e section in the \u003ccode\u003eapp.yaml\u003c/code\u003e file if applicable, and deploying a new major version.\u003c/p\u003e\n"],["\u003cp\u003eLegacy health check options such as \u003ccode\u003eenable_health_check\u003c/code\u003e, \u003ccode\u003echeck_interval_sec\u003c/code\u003e, \u003ccode\u003etimeout_sec\u003c/code\u003e, \u003ccode\u003eunhealthy_threshold\u003c/code\u003e, \u003ccode\u003ehealthy_threshold\u003c/code\u003e, and \u003ccode\u003erestart_threshold\u003c/code\u003e can be rewritten and configured to maintain similar behavior in split health checks using equivalent fields.\u003c/p\u003e\n"]]],[],null,["# Migrate from legacy to split health checks\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nAs of September 15, 2019, if you're using the legacy health checks, your\napplication will continue to run and receive health checks but you won't be\nable to deploy new versions of your application.\n\nThis page explains upgrading from the legacy health checks to\n[split health checks](/appengine/docs/flexible/reference/app-yaml#updated_health_checks).\n\nVerifying your health check type\n--------------------------------\n\nTo verify the type of health checks your application is using, run the\nfollowing command: \n\n gcloud app describe\n\nIf your application is using split health checks, the description should\ninclude the following information: \n\n featureSettings:\n splitHealthChecks: true\n\nUnderstanding key differences\n-----------------------------\n\nBefore upgrading to split health checks, consider the following important\ndifferences between legacy and split health checks:\n\n- **HTTP requests for split health checks are not forwarded by default.**\n By contrast, legacy health checks forward to the `/_ah/health` path in your\n application by default.\n\n- **Forwarded split health checks must return `200 OK` when healthy and\n ready.** Legacy health checks consider the following HTTP codes as healthy:\n `200`, `301`, `302`, `303`, `307`, `401`, `402`, `403`, `404`, `405`.\n\nIf you do not specify a [liveness check path](/appengine/docs/flexible/reference/app-yaml#liveness_path)\nor a [readiness check path](/appengine/docs/flexible/reference/app-yaml#readiness_path),\nby default split health checks only confirm that the VM instance and the\nDocker container are running. As long as these conditions hold, the VM will\ncontinue to receive traffic and remain alive regardless of the app's internal\nstate.\n\nBy contrast, when legacy health checks are enabled, if your app's `/_ah/health`\npath starts returning unhealthy HTTP error codes (e.g. `5XX`) then legacy health\nchecks will start failing and the VM will stop receiving traffic and be\nrestarted.\n\nIf your app depends on the default legacy health check behavior, set the\n[liveness check path](/appengine/docs/flexible/reference/app-yaml#liveness_path)\nand the [readiness check path](/appengine/docs/flexible/reference/app-yaml#readiness_path)\naccordingly.\n\nConverting legacy health check options\n--------------------------------------\n\nEach legacy health check option can be rewritten using split health checks as\nfollows:\n\nEnabling split health checks\n----------------------------\n\nTo migrate from legacy health checks to split health checks and avoid seeing\nelevated `5xx` status codes, complete the following steps:\n\n1. Understand the [important differences](#understanding_key_differences)\n between legacy and split health checks.\n\n2. [Convert legacy health check options](#converting_legacy_health_check_options)\n for each version in your application.\n\n Alternatively, you can customize the `liveness_check` or `readiness_check`\n section in the `app.yaml` file for each version. For examples,\n see [Liveness checks](/appengine/docs/flexible/reference/app-yaml#liveness_checks)\n and [Readiness checks](/appengine/docs/flexible/reference/app-yaml#readiness_checks).\n3. Run the following command:\n\n ```transact-sql\n gcloud app update --split-health-checks --project \u003cvar translate=\"no\"\u003e[YOUR_PROJECT_ID]\u003c/var\u003e\n ```\n4. If you used customized settings for legacy health checks, you must remove the\n `health_check` section from your `app.yaml` file.\n\n5. Deploy a new major version of your app to start using liveness and readiness\n health checks."]]
