Skip to content

Commit

Permalink
Doc for new Health API (FusionAuth#3122)
Browse files Browse the repository at this point in the history 
* Doc for new Health API.
FusionAuth/fusionauth-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 <[email protected]>

* Copy updates from code review

---------

Co-authored-by: Andy Pai <[email protected]>
  • Loading branch information
@robotdan @andrewpai
robotdan and andrewpai authored Jun 17, 2024
1 parent fd8f5d1 commit 29794e3
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 21 deletions.
50 changes: 37 additions & 13 deletions astro/src/content/docs/apis/system.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -261,27 +261,51 @@ 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"
}
```

The specific contents of the JSON body are not documented here. If you choose to use this API for monitoring purposes you should primarily use the response code to indicate server health. If you receive a `200` you may consider FusionAuth in a healthy state. The response body is intended for use by FusionAuth support.

_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.<br/><br/> 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.`<br/><br/> 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

<Aside type="version">
This API has been available since 1.51.1
</Aside>

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

<API method="GET" uri="/api/health" authentication={["none"]} title="Return the system health"/>

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

Expand Down
19 changes: 11 additions & 8 deletions astro/src/content/docs/release-notes/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) <span class="not-prose no-underline"><a class="ml-2" href="/docs/releases.xml"><i class="fas fa-xs fa-rss text-orange-700 text-2xl" width="50px" /></a></span>

<ReleaseNoteHeading version='1.51.1' releaseDate='June 12, 2024' />

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

<ReleaseNoteHeading version='1.51.0' releaseDate='May 28, 2024' name="Theming Toucan" />

### 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)
Expand All @@ -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`
Expand Down Expand Up @@ -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`
Expand Down

0 comments on commit 29794e3

Please sign in to comment.