From 29794e316913b4d0d20d0e9d02200f01727ae9be Mon Sep 17 00:00:00 2001 From: Daniel DeGroff Date: Mon, 17 Jun 2024 14:27:13 -0700 Subject: [PATCH] Doc for new Health API (#3122) * Doc for new Health API. https://github.com/FusionAuth/fusionauth-issues/issues/1166 Fixes to release notes for 1.51.1. Formatting, adding missing links to GH issue, and provide additional clarity for documented issues. * Update astro/src/content/docs/apis/system.mdx Co-authored-by: Andy Pai * Copy updates from code review --------- Co-authored-by: Andy Pai --- astro/src/content/docs/apis/system.mdx | 50 ++++++++++++++----- .../src/content/docs/release-notes/index.mdx | 19 ++++--- 2 files changed, 48 insertions(+), 21 deletions(-) diff --git a/astro/src/content/docs/apis/system.mdx b/astro/src/content/docs/apis/system.mdx index 0e50078cf7..83d517d1e3 100644 --- a/astro/src/content/docs/apis/system.mdx +++ b/astro/src/content/docs/apis/system.mdx @@ -261,12 +261,10 @@ FusionAuth also supports a system status check [using Prometheus](/docs/operate/ ### Response The JSON response from the Status API is complex and subject to change. The only exception is the `version` key. -`version` will not change and will be returned as below. As a reminder, an API key is required to obtain this value unless explicitly allowed from `localhost`. -```javascript +The `version` key will not change and will be returned as below. As a reminder, an API key is required to obtain this value unless explicitly allowed from `localhost`. +```json { -{/* .. */} - "version": "1.26.1" -{/* .. */} + "version": "1.26.1" } ``` @@ -274,14 +272,40 @@ The specific contents of the JSON body are not documented here. If you choose to _Response Codes_ -| Code | Description | -|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 200 | The FusionAuth is functioning properly | -| 452 | The FusionAuth is failing to make a JDBC connection to the configured database. | -| 453 | The FusionAuth database connection pool connectivity is below the healthy threshold. Additional information may be available in the JSON response which is retrieved when using an API key. | -| 454 | The FusionAuth database connectivity pool connectivity is below the healthy threshold. Additional information may be available in the JSON response which is retrieved when using an API key. | -| 460 | FusionAuth is using Elasticsearch and the search service is reporting an unhealthy cluster status. In a cluster with 2+ nodes, this means the cluster status is being reported as `yellow` or `red`. In a single-node Elasticsearch configuration this means the cluster status is `red.` | -| 500 | The FusionAuth server is not functioning properly. This could indicate that the database connectivity failed or one or more services within FusionAuth failed. Consult the FusionAuth [Troubleshooting](/docs/operate/troubleshooting/troubleshooting) to learn more about the failure or contact FusionAuth support for assistance. | +| Code | Description | +|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 200 | FusionAuth is functioning properly | +| 452 | FusionAuth is failing to make a JDBC connection to the configured database. | +| 453 | The FusionAuth database connection pool connectivity is below the healthy threshold. This means requests are waiting too long to obtain a connection to the database. Additional information may be available in the JSON response which is retrieved when using an API key. | +| 454 | The FusionAuth database connection pool connectivity is below the healthy threshold. Additional information may be available in the JSON response which is retrieved when using an API key.

As of version `1.51.1` this status code will no longer be returned based upon the connectivity health check. In practice you only need to monitor for `452` to ensure FusionAuth is able to connect to the database. | +| 460 | FusionAuth is using Elasticsearch and the search service is reporting an unhealthy cluster status. In a cluster with 2+ nodes, this means the cluster status is being reported as `yellow` or `red`. In a single-node Elasticsearch configuration this means the cluster status is `red.`

As of version `1.51.1` this status code will no longer be returned based upon the Elasticsearch health check. If you are using an external Elasticsearch or OpenSearch service, you will want to monitor that separately from FusionAuth. | +| 500 | FusionAuth is not functioning properly. This could indicate that the database connectivity failed or one or more services within FusionAuth failed. Consult the FusionAuth [Troubleshooting](/docs/operate/troubleshooting/troubleshooting) to learn more about the failure or contact FusionAuth support for assistance. | + +## Retrieve System Health + + + +The Health API is used to monitor the health of the FusionAuth service. This endpoint is specifically intended for use by a load balancer to understand when FusionAUth is available, live and ready for requests. Prefer this endpoint to the Status API when using it for a load balancer or a Kubernetes readiness check. + +This API does not require an API key. + +### Request + + + +### Response + +This API does not return a JSON response body. + +_Response Codes_ + +| Code | Description | +|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 200 | FusionAuth is functioning properly and can accept requests. | +| 500 | FusionAuth is not functioning properly. This will generally indicate that FusionAuth is not able to communicate with the database or complete I/O operations. | + ## Retrieve System Version diff --git a/astro/src/content/docs/release-notes/index.mdx b/astro/src/content/docs/release-notes/index.mdx index cba867f2a9..23c09e1732 100644 --- a/astro/src/content/docs/release-notes/index.mdx +++ b/astro/src/content/docs/release-notes/index.mdx @@ -18,23 +18,26 @@ import ReleaseNoteHeading from 'src/components/docs/release-notes/ReleaseNoteHea Looking for release notes older than 1.23.0? Look in the [release notes archive](/docs/release-notes/archive). Looking to be [notified of new releases?](/docs/operate/roadmap/releases#release-notifications) + ### Fixed -* An HTTP request sent to FusionAuth with non-ASCII characters in request header values is causing the connection to be closed without a response. +* An HTTP request sent to FusionAuth with non-ASCII characters in request header values caused the request to be rejected and caused the connection to be closed without a response. Generally speaking values outside of the ASCII character set are not allowed, but in practice they may be used, and so these values are now treated as opaque and ignored by the HTTP request parser. * Resolves [GitHub Issue #2774](https://github.com/FusionAuth/fusionauth-issues/issues/2774) -* There is a misspelling in the description of the `user.password.reset.send` event on the tenant edit page. +* A typo was found in the description of the `user.password.reset.send` event on the tenant edit page. * Resolves [GitHub Issue #2782](https://github.com/FusionAuth/fusionauth-issues/issues/2782) -* The SCIM API is not properly handling reading, creating, and updating groups with more than one hundred memberships. Responses containing groups with more than one hundred memberships are only returning the first one hundred. Create and update operations are only creating or updating one hundred, and deleting the remainder. +* The SCIM API is not properly handling reading, creating, and updating groups with more than one hundred memberships. Responses containing groups with more than one hundred memberships are only returning the first one hundred. Create and update operations are only creating or updating one hundred, and deleting the remainder. This defect also caused the FusionAuth event for `group.member.update` and `group.member.update.complete` to contain the same truncated list of members. * Resolves [GitHub Issue #2784](https://github.com/FusionAuth/fusionauth-issues/issues/2784) ### New -* A new `/api/health` endpoint has been added. Prior to this, the `/api/status` endpoint was the best option for performing health checks, but was too complicated for some health check scenarios. This new endpoint provides a binary indication of the healthiness or unhealthiness of a FusionAuth instance. +* A Health API `/api/health` has been added. Prior to this addition, the `/api/status` endpoint was the best option for performing health checks. The Status API may not be ideal for all use cases because it returns a JSON body and the status code is used to indicate the status of various health checks that may not be valuable by a load balancer to indicate if requests should be routed to this node. This new endpoint provides a binary indication of the healthiness or unhealthiness of a FusionAuth instance by only returning a `200` or `500` status code w/out a JSON response. This new API also runs fewer health checks and may perform better than the Status API. * Resolves [GitHub Issue #1166](https://github.com/FusionAuth/fusionauth-issues/issues/1166) ### Internal -Update 3rd party dependencies. -* Upgrade io.fusionauth:java-http 0.3.4 to 0.3.5 +Update dependencies. +* Upgrade `io.fusionauth:java-http` `0.3.4` to `0.3.5` + * Resolves [GitHub Issue #2786](https://github.com/FusionAuth/fusionauth-issues/issues/2786) + ### Fixed * In version `1.45.0` we added a hosted OAuth backend capability, allowing a developer to write a front end-only application, but still take advantage of an authorization code grant workflow by leveraging the backend provided by FusionAuth. Multi-segment domain suffixes (e.g. `.co.uk`) are not handled correctly by this hosted backend when setting the domain on cookies. Cookie domains are now set properly. * Resolves [GitHub Issue #2735](https://github.com/FusionAuth/fusionauth-issues/issues/2735) @@ -52,7 +55,7 @@ Update 3rd party dependencies. * Resolves [GitHub Issue #2669](https://github.com/FusionAuth/fusionauth-issues/issues/2669) ### Internal -* Update 3rd party dependencies. +* Update dependencies. * Upgrade `org.graalvm.sdk:*:22.3.3` to `org.graalvm.polyglot:*:23.1.2` * Upgrade `org.graalvm.js:js` `22.3.3` to `23.0.3` * Upgrade `io.fusionauth:java-http` `0.3.2` to `0.3.4` @@ -383,7 +386,7 @@ Update 3rd party dependencies. * Resolves [GitHub Issue #2501](https://github.com/FusionAuth/fusionauth-issues/issues/2501) ### Internal -* Update 3rd party dependencies to remove CVE scan warnings and to stay current. These upgrades are simply a precautionary measure to stay current. +* Update dependencies to remove CVE scan warnings and to stay current. These upgrades are simply a precautionary measure to stay current. * Upgrade `google-guice` `5.1.0` to `6.0.0` * Upgrade `google-guava` `30.1.0` to `32.1.2` * Upgrade `java-http` `0.2.0` to `0.2.9`