Using Endpoints

Steeltoe provides a basic set of HTTP endpoints (also known as actuators), which are implemented using ASP.NET Core middleware.

Reference Materials

In this section, it is helpful to understand the following:

How the .NET Configuration System works
How the ASP.NET Core Startup is used to register services and middleware

Endpoint Listing

The following table describes the available Steeltoe management endpoints that can be used in an application:

ID	Description
cloudfoundry	Enables the management endpoint integration with Cloud Foundry
dbmigrations	Provides the ability to see current and pending database migrations for an application data source
env	Reports the keys and values from the application configuration
health	Customizable endpoint that gathers application health information
heapdump	Generates and downloads a mini-dump of the application (Windows and Linux only)
httpexchanges	Gathers recently processed HTTP requests
hypermedia	Lists the active management endpoints and their links
info	Customizable endpoint that gathers arbitrary application information (such as app version)
loggers	Gathers existing logger categories and allows changing their minimum levels at runtime
mappings	Reports the configured ASP.NET routes and route templates
prometheus	Exposes metrics collected using built-in instrumentation of various aspects of the application in the Prometheus format
refresh	Triggers a reload of the application configuration
services	Lists the contents of the .NET dependency injection service container
threaddump	Generates and reports a snapshot of the application's threads (Windows only)

Each endpoint has an associated ID. When you want to expose an endpoint over HTTP, its ID is used in the mapped URL that exposes the endpoint. For example, the health endpoint is mapped to /actuator/health.

Add NuGet Reference

To use the management endpoints, add a reference to the Steeltoe.Management.Endpoints NuGet package.

Configure Global Settings

Endpoints can be configured using the .NET Configuration System. You can globally configure settings that apply to all endpoints, as well as configure settings that are specific to a particular endpoint.

All management endpoint settings should be placed under the configuration key prefix Management:Endpoints. Any settings found under this prefix apply to all endpoints globally.

Settings that you want to apply to specific endpoints should be placed under the configuration key prefix Management:Endpoints:<ID>, where <ID> is the ID of the endpoint (for example, Management:Endpoints:Health). Any settings you apply to a specific endpoint override the configuration settings applied globally.

The following table describes the configuration settings that you can apply globally:

Key	Description	Default
`Enabled`	Whether to enable management endpoints	`true`
`Path`	The HTTP route prefix applied to all endpoints	`/actuator`
`Port`	Expose management endpoints on an alternate HTTP port ¹
`SslEnabled`	Whether `Port` applies to HTTP or HTTPS requests ¹	`false`
`UseStatusCodeFromResponse`	Reflect the actuator outcome in the HTTP response status code	`true`
`SerializerOptions`	Customize JSON serialization options	use camelCase properties
`CustomJsonConverters`	Additional `JsonConverter`s to use (see below)

Note

When running an application in IIS or with the HWC buildpack, response body content is automatically filtered out when the HTTP response code is 503. Some actuator responses intentionally return a code of 503 in failure scenarios. Setting UseStatusCodeFromResponse to false returns status code 200 instead. This switch does not affect the status code of responses outside of Steeltoe.

Configure Endpoint-specific Settings

The following table describes the configuration settings that are common to all endpoint-specific settings:

Key	Description	Default
`Enabled`	Whether the endpoint is enabled	`true`
`ID`	The unique ID of the endpoint
`Path`	The relative path at which the endpoint is exposed	same as `ID`
`RequiredPermissions`	Permissions required to access the endpoint when running on Cloud Foundry	`Restricted`
`AllowedVerbs`	An array of HTTP verbs at which the endpoint is exposed

Custom JSON Serialization Options

The JsonSerializerOptions used to serialize actuator responses are configurable, and custom JsonConverters can be used by adding the assembly-qualified type.

For example, to pretty-print all JSON, and serialize DateTime values as epoch times:

{
  "Management": {
    "Endpoints": {
      "SerializerOptions": {
        "WriteIndented": true
      },
      "CustomJsonConverters": [
        "Steeltoe.Management.Endpoint.Actuators.Info.EpochSecondsDateTimeConverter"
      ]
    }
  }
}

Exposing Endpoints

Since endpoints may contain sensitive information, only health and info are exposed by default. To change which endpoints are exposed, use the Include and Exclude properties.

Property	Default
`Exposure:Include`	[`info`, `health`]
`Exposure:Exclude`

Each key in the table must be prefixed with Management:Endpoints:Actuator. Use the actuator ID to specify the endpoint. To expose all endpoints, you can use *. For example, to expose everything except env and refresh, use the following:

"Management": {
    "Endpoints": {
        "Actuator":{
            "Exposure": {
                "Include": [ "*" ],
                "Exclude": [ "env", "refresh"]
            }
        }
    }
}

Important

When running on Cloud Foundry, exposure settings affect only requests starting with /actuator. They are ignored for requests starting with /cloudfoundryapplication, where access control is handled differently. Individual endpoints can be turned off by setting Enabled to false, which applies to both URLs.

HTTP Access

To expose any of the management endpoints over HTTP in an ASP.NET Core application:

Add a NuGet package reference to Steeltoe.Management.Endpoint.
Configure endpoint settings, as needed (typically in appsettings.json).
Add the actuator endpoint(s) to the service container.
Optional: Add any additional health/info contributors to the service container.
Optional: Customize the CORS policy.
Optional: Secure the endpoints.
Optional: Override the middleware pipeline setup.

Caution

By default, actuator endpoints are exposed on the same host(s) and port(s) as the application (which can be configured as described in the ASP.NET documentation and in 8 ways to set the URLs for an ASP.NET Core app). Use the Port and SslEnabled settings described earlier to isolate management endpoints from regular application endpoints.

The following example adds all actuators:

using Steeltoe.Management.Endpoint.Actuators.All;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAllActuators();

Tip

It is recommended that you use AddAllActuators() instead of adding individual actuators; this enables individually turning them on/off at runtime using configuration.

Alternatively, individual actuators can be added:

using Steeltoe.Management.Endpoint.Actuators.Hypermedia;
using Steeltoe.Management.Endpoint.Actuators.Loggers;
using Steeltoe.Management.Endpoint.Actuators.Refresh;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHypermediaActuator().AddLoggersActuator().AddRefreshActuator();

Note

AddAllActuators() and AddLoggingActuator() automatically configure Dynamic Console Logging. If you want to use Dynamic Serilog Logging instead, add it before adding actuators. For example:

using Steeltoe.Logging.DynamicSerilog;
using Steeltoe.Management.Endpoint.Actuators.All;

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddDynamicSerilog();
builder.Services.AddAllActuators();

Adding contributors

The health and info endpoints can be extended with custom contributors. For example:

using Steeltoe.Management.Endpoint.Actuators.Health;
using Steeltoe.Management.Endpoint.Actuators.Info;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthActuator();
builder.Services.AddHealthContributor<CustomHealthContributor>();
builder.Services.AddInfoActuator();
builder.Services.AddInfoContributor<CustomInfoContributor>()

Customizing the CORS policy

By default, any origin is allowed to access the actuator endpoints. To customize the CORS policy, use the ConfigureActuatorsCorsPolicy extension method:

using Steeltoe.Management.Endpoint;
using Steeltoe.Management.Endpoint.Actuators.All;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAllActuators();
builder.Services.ConfigureActuatorsCorsPolicy(policy => policy.WithOrigins("http://www.example.com"));

Securing Endpoints

Endpoints can be customized with IEndpointConventionBuilder. This allows calling RequireAuthorization() to configure the Authorization middleware:

using Steeltoe.Management.Endpoint;
using Steeltoe.Management.Endpoint.Actuators.All;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAllActuators();
builder.Services.ConfigureActuatorEndpoints(endpoints => endpoints.RequireAuthorization());

When RequireAuthorization() is called without arguments, the default profile is used. Other overloads allow passing a profile or a profile name.

Overriding the middleware pipeline setup

All Add*Actuator methods provide an overload that takes a boolean configureMiddleware, which enables skipping adding middleware to the ASP.NET Core pipeline. While this provides full control over the pipeline contents and order, it requires manual addition of the appropriate middleware for actuators to work correctly.

using Steeltoe.Management.Endpoint;
using Steeltoe.Management.Endpoint.Actuators.All;
using Steeltoe.Management.Endpoint.Actuators.CloudFoundry;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAllActuators(configureMiddleware: false);
await using WebApplication app = builder.Build();

app.UseManagementPort(); // required to block actuator requests on the app port
app.UseRouting();
app.UseActuatorsCorsPolicy(); // required to activate the CORS policy for actuators
app.UseCloudFoundrySecurity(); // required by AddCloudFoundryActuator()
app.UseActuatorEndpoints(); // maps the actuator endpoints

await app.StartAsync();

Rules for use

Follow these rules when overriding the middleware pipeline setup:

Do not change the order shown in the sample.
Leaving out entries is not recommended.
Additional middleware can be inserted as appropriate.

Conventional routing

Applications that use the legacy conventional routing are still supported by the Add*Actuator methods. However, they won't show up in the route mappings actuator anymore.

Using an alternate port does not apply to /cloudfoundryapplication endpoints.↩↩

Table of Contents

Using Endpoints

Reference Materials

Endpoint Listing

Add NuGet Reference

Configure Global Settings

Note

Configure Endpoint-specific Settings

Custom JSON Serialization Options

Exposing Endpoints

Important

HTTP Access

Caution

Tip

Note

Adding contributors

Customizing the CORS policy

Securing Endpoints

Overriding the middleware pipeline setup

Rules for use

Conventional routing