From 50b556a76e44c4b31c2123cadd6b8b61beb55982 Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Tue, 18 Feb 2025 11:31:03 -0600 Subject: [PATCH 01/43] run build-and-stage on pushes to Anita's branch --- .github/workflows/build-and-stage.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-and-stage.yml b/.github/workflows/build-and-stage.yml index 1d152f74..71e0a4c9 100644 --- a/.github/workflows/build-and-stage.yml +++ b/.github/workflows/build-and-stage.yml @@ -8,6 +8,7 @@ on: branches: - main - v4 + - anita concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} @@ -135,10 +136,10 @@ jobs: name: Build and push documentation image needs: [ change-detection, build-push-docfx, build-push-metadata ] environment: - name: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || vars.STAGING_SLOT_NAME }} + name: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || (github.ref_name == 'anita' && 'anita' || vars.STAGING_SLOT_NAME) }} url: ${{ steps.deploy-to-webapp.outputs.webapp-url }} env: - SLOT_NAME: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || vars.STAGING_SLOT_NAME }} + SLOT_NAME: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || (github.ref_name == 'anita' && 'anita' || vars.STAGING_SLOT_NAME) }} runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 From 4b3648d59909b11b90017b987fcb5026414969f1 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Mon, 24 Feb 2025 13:16:42 -0800 Subject: [PATCH 02/43] fix case for MySQL link (experiment) --- api/v4/connectors/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/v4/connectors/index.md b/api/v4/connectors/index.md index fdb46d46..e9b6b56b 100644 --- a/api/v4/connectors/index.md +++ b/api/v4/connectors/index.md @@ -8,7 +8,7 @@ for turning raw credentials into formatted connection strings and also provide h Get started with the [basic concepts](usage.md) or go directly to any supported technology: -- [MySql](mysql.md) +- [MySQL](mysql.md) - [Microsoft SQL Server](microsoft-sql-server.md) - [PostgreSQL](postgresql.md) - [RabbitMQ](rabbitmq.md) From 38f66fe605f742cc1d18c34121004ded279351ef Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Wed, 26 Feb 2025 07:37:33 -0800 Subject: [PATCH 03/43] full edit - Welcome section --- api/v4/welcome/common-steps.md | 8 +++---- api/v4/welcome/index.md | 2 +- api/v4/welcome/prerequisites.md | 4 ++-- api/v4/welcome/whats-new.md | 42 ++++++++++++++++----------------- 4 files changed, 28 insertions(+), 28 deletions(-) diff --git a/api/v4/welcome/common-steps.md b/api/v4/welcome/common-steps.md index 015a7276..15d17c17 100644 --- a/api/v4/welcome/common-steps.md +++ b/api/v4/welcome/common-steps.md @@ -18,11 +18,11 @@ You can use the `dotnet` CLI to [build and locally publish](https://learn.micros * macOS: `dotnet publish --framework net8.0 --runtime osx-x64` > [!TIP] -> Since .NET Core 2.0, the `dotnet publish` command automatically runs NuGet package restore for you. Running `dotnet restore` explicitly is no longer required. +> Since .NET Core 2.0, the `dotnet publish` command automatically runs the NuGet package restore for you. Running `dotnet restore` explicitly is no longer required. ## Cloud Foundry Push Sample -This section describes how to use the [Cloud Foundry CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html) to push the published application to Cloud Foundry by using the parameters that match what you selected for framework and runtime: +This section describes how to use the [Cloud Foundry CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html) to push the published application to Cloud Foundry using the parameters that match what you selected for framework and runtime: ```bash # Push to Linux cell @@ -39,7 +39,7 @@ cf push -f manifest-windows.yml -p bin/Debug/net8.0/win-x64/publish To see the logs as you start the application, use `cf logs your-app-name`. -On a Linux cell, you should see output that resembles the following during startup: +On a Linux cell, you should see output similar to the following during startup: ```bash 2016-06-01T09:14:14.38-0600 [CELL/0] OUT Creating container @@ -52,7 +52,7 @@ On a Linux cell, you should see output that resembles the following during start 2016-06-01T09:14:21.41-0600 [CELL/0] OUT Container became healthy ``` -On Windows cells, you should see something slightly different with similar information. +On Windows cells, you see similar information in a slightly different format. ### Reading Configuration Values diff --git a/api/v4/welcome/index.md b/api/v4/welcome/index.md index 5246ed53..53b65b81 100644 --- a/api/v4/welcome/index.md +++ b/api/v4/welcome/index.md @@ -22,7 +22,7 @@ List the active loggers and change their minimum log levels at runtime. ## [Management](../management/index.md) -Monitor and manage your application while it runs in production via various HTTP endpoints. +Monitor and manage your application while it runs in production through various HTTP endpoints. ## [Network File Sharing](../fileshares/index.md) diff --git a/api/v4/welcome/prerequisites.md b/api/v4/welcome/prerequisites.md index cc5dce2d..3de42a15 100644 --- a/api/v4/welcome/prerequisites.md +++ b/api/v4/welcome/prerequisites.md @@ -2,14 +2,14 @@ While not required, we recommend installing one of the development tools ([Visual Studio](https://www.visualstudio.com/) or [Visual Studio Code](https://code.visualstudio.com/)) provided by Microsoft. -If you plan to develop with [.NET](https://learn.microsoft.com/dotnet/fundamentals) or [ASP.NET Core](https://learn.microsoft.com/aspnet/core), you will need to download and install the latest [.NET SDK](https://dotnet.microsoft.com/download). Additionally, if you do not already know the language and framework well, we recommend you first spend time working through some of the following tutorials from Microsoft: +If you plan to develop with [.NET](https://learn.microsoft.com/dotnet/fundamentals) or [ASP.NET Core](https://learn.microsoft.com/aspnet/core), you must download and install the latest [.NET SDK](https://dotnet.microsoft.com/download). Additionally, if you do not already know the language and framework well, we recommend you first spend time working through some of the following tutorials from Microsoft: * [Getting Started with C#](https://learn.microsoft.com/dotnet/csharp) * [Getting Started with ASP.NET Core](https://learn.microsoft.com/aspnet/core/getting-started) ## NuGet Feeds -When developing applications with Steeltoe, you need to pull the Steeltoe NuGet packages into your project. +When developing applications with Steeltoe, you must pull the Steeltoe NuGet packages into your project. To use the latest *unstable* packages from the developer feed, create a `Nuget.config` file with the contents below. diff --git a/api/v4/welcome/whats-new.md b/api/v4/welcome/whats-new.md index 8099ff96..b289b4be 100644 --- a/api/v4/welcome/whats-new.md +++ b/api/v4/welcome/whats-new.md @@ -9,7 +9,7 @@ - Compatible with recent versions of Tanzu Platform (Cloud Foundry and Kubernetes) and Spring Boot - Changes to align with .NET conventions and patterns, extensive review of the public API surface - Performance and scalability improvements -- Numerous bugfixes +- Numerous bug fixes - Cleanup of logging output - Substantially improved documentation - Improved test coverage, including interaction between different Steeltoe components @@ -19,11 +19,11 @@ ### General - NuGet Packages - - Dropped the Core/Base suffix from package names, which was used to distinguish between NET Standard and .NET Core + - Dropped the Core/Base suffix from package names, which was used to distinguish between .NET Standard and .NET Core - Removed ".Extensions" from NuGet package names - Extension methods - Removed host builder extension methods that could be substituted with a single extension method on - `IServiceCollection`, `IConfiguration`, `IConfigurationBuilder`, `ILoggingBuilder` etc. + `IServiceCollection`, `IConfiguration`, `IConfigurationBuilder`, `ILoggingBuilder`, etc. Their redundancy led to confusion, and required Steeltoe to adapt each time a new host builder is introduced. - Added support for the new `IHostApplicationBuilder` (which `WebApplicationBuilder` and `HostApplicationBuilder` implement) to the remaining host builder extension methods - Moved extension methods to the appropriate Steeltoe namespaces to avoid clashes with other libraries @@ -32,14 +32,14 @@ - Removed various interfaces that weren't general-purpose, types not designed for inheritance/reuse made internal - Changed methods containing optional parameters with default values to overloaded methods - Made more methods async and expanded usage of `CancellationToken`, both as a parameter and internally - - Enhanced method input validation to prevent downstream `NullReferenceException`s + - Enhanced method input validation to prevent downstream `NullReferenceException` exceptions - Applied C#/.NET naming conventions, for example: renamed `HealthStatus.OUT_OF_SERVICE` to `HealthStatus.OutOfService` - Configuration - Added support in Steeltoe packages for auto-completion in `appsettings.json` (without needing a schema reference, which currently only works in Visual Studio for SDK-style web projects), updated global Steeltoe JSON schema - Changed nearly all configuration settings to be reloadable without app restart, now more consistently exposed via ASP.NET Options pattern - Up-to-date - Extensively tested with the latest versions of dependent packages, database drivers and third-party products - (including Tanzu, Cloud Foundry, Config Server, Consul, Eureka, RabbitMQ, Redis, OpenTelemetry, Grafana, Prometheus, Zipkin, Spring Boot Admin) + (including Tanzu, Cloud Foundry, Config Server, Consul, Eureka, RabbitMQ, Redis/Valkey, OpenTelemetry, Grafana, Prometheus, Zipkin, Spring Boot Admin) - Refreshed dev-local Docker images for Config Server, Eureka, UAA and Spring Boot Admin - Steeltoe no longer depends on legacy technologies, such as binary serialization and Newtonsoft.Json @@ -121,9 +121,9 @@ The following sections provide details on the changes per Steeltoe component, as - Unified handling for all host builder types (there were omissions in some cases, due to duplicate code not kept in sync) - Added wire-up of Steeltoe.Configuration.SpringBoot, Steeltoe.Configuration.Encryption and Steeltoe.Logging.DynamicConsole -- Removed wire-up of client certificate authentication, which was done only partly +- Removed wire-up of client certificate authentication, which was only partly done - When no `ILoggerFactory` is specified, `BootstrapLoggerFactory` is used by default (pass `NullLoggerFactory.Instance` to disable) -- Ignore casing when comparing assembly names (bugfix) +- Ignore casing when comparing assembly names (bug fix) ### NuGet Package changes @@ -156,7 +156,7 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind - Dynamically loading custom types for connectors and service discovery is no longer possible - Removed Spring Expression Language (SpEL) support - Removed `UseCloudHosting` (impossible to reliably detect bound ports in all cases, while Cloud Foundry usually [^1] sets the port automatically) -- Greater flexibility in using Bootstrap logger, bugfixes +- Greater flexibility in using Bootstrap logger, bug fixes - Certificates are no longer read from OS-specific store, which proved to not work reliably (store paths in configuration instead) ### NuGet Package changes @@ -164,8 +164,8 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | Source | Change | Replacement | Notes | | ---------------------------- | ------- | ---------------------------- | ---------------------------------------------------------- | | Steeltoe.Common.Abstractions | Moved | Steeltoe.Common package | | -| Steeltoe.Common.Certificates | Added | | Support for handling X509 certificates | -| Steeltoe.Common.Expression | Removed | None | Existed for SpEL support, which has been removed | +| Steeltoe.Common.Certificates | Added | | Support for handling X.509 certificates | +| Steeltoe.Common.Expression | Removed | None | Existed for Spring Extension Language (SpEL) support, which has been removed | | Steeltoe.Common.Kubernetes | Removed | None | | | Steeltoe.Common.Logging | Added | | Provides `BootstrapLoggerFactory` | | Steeltoe.Common.Retry | Removed | None | Existed for Messaging support, which has been removed | @@ -221,10 +221,10 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | `Steeltoe.Common.Reflection` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support Type Locators, which have been replaced with internal-only shims | | `Steeltoe.Common.Retry` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed for Messaging support, which has been removed | | `Steeltoe.Common.SecurityUtilities` | Type | Steeltoe.Common [Abstractions] | Removed | None | Internally used to sanitize line breaks in logs | -| `Steeltoe.Common.Services` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.Services` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.SteeltoeComponent` | Type | Steeltoe.Common [Abstractions] | Removed | None | This enum is no longer needed | | `Steeltoe.Common.Transaction` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed for Messaging support, which has been removed | -| `Steeltoe.Common.Util` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.Util` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.Certificates.CertificateConfigurationExtensions.AddAppInstanceIdentityCertificate` | Extension method | Steeltoe.Common.Certificates | Added | | Register/generate identity certificate for Cloud Foundry authentication | | `Steeltoe.Common.Certificates.CertificateOptions` | Type | Steeltoe.Common.Certificates | Added | | Provides access to loaded certificate using ASP.NET Options pattern | | `Steeltoe.Common.Certificates.CertificateServiceCollectionExtensions.ConfigureCertificateOptions` | Extension method | Steeltoe.Common.Certificates | Added | | Bind named certificate from `IConfiguration` and monitor for changes | @@ -433,9 +433,9 @@ For more information, see the updated [Configuration documentation](../configura - ADO.NET API: `builder.Add*()`, inject `ConnectorFactory` (driver-specific connection/client instances are no longer registered) - EF Core API: must call `builder.Add*()` first. Example: `builder.AddMySql(); builder.Services.AddDbContext((serviceProvider, options) => options.UseMySql(serviceProvider));` - The structure of configuration has changed severely to accommodate multiple named service bindings in a unified way -- Compatible with the latest versions of Tanzu, Cloud Foundry and .NET database drivers -- Added [Cloud Native Binding](https://github.com/servicebinding/spec) support (used by Tanzu Platform for Kubernetes, formerly TAP) for MongoDB, MySQL, PostgreSQL, RabbitMQ and Redis -- Leverage .NET connection strings (agnostic to the driver-specific parameters) via +- Compatible with the latest versions of Tanzu, Cloud Foundry, and .NET database drivers +- Added [Cloud Native Binding](https://github.com/servicebinding/spec) support (used by Tanzu Application Platform and Tanzu Platform for Kubernetes) for MongoDB, MySQL, PostgreSQL, RabbitMQ, and Redis/Valkey +- Leverage .NET connection strings (agnostic to the driver-specific parameters) using [ASP.NET Options pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) - Connection string from appsettings.json is preserved, replacing parameters from cloud bindings - No more defaults for missing connection parameters that are required by drivers @@ -556,7 +556,7 @@ For more information, see the updated [Configuration documentation](../configura | `Steeltoe.Connectors.RabbitMQ.RabbitMQOptions` | Type | Steeltoe.Connectors | Added | | Provides connection string | | `Steeltoe.Connectors.RabbitMQ.RabbitMQServiceCollectionExtensions.AddRabbitMQ` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | | `Steeltoe.Connectors.Redis.RedisConfigurationBuilderExtensions.ConfigureRedis` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | -| `Steeltoe.Connectors.Redis.RedisHostApplicationBuilderExtensions.AddRedis` | Extension method | Steeltoe.Connectors | Added | | Activates the Redis connector | +| `Steeltoe.Connectors.Redis.RedisHostApplicationBuilderExtensions.AddRedis` | Extension method | Steeltoe.Connectors | Added | | Activates the Redis/Valkey connector | | `Steeltoe.Connectors.Redis.RedisOptions` | Type | Steeltoe.Connectors | Added | | Provides connection string | | `Steeltoe.Connectors.Redis.RedisServiceCollectionExtensions.AddRedis` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | | `Steeltoe.Connectors.SqlServer.SqlServerConfigurationBuilderExtensions.ConfigureSqlServer` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | @@ -601,12 +601,12 @@ For more information, see the updated [Connectors documentation](../configuratio ### Behavior changes - Multiple discovery clients (one per type) can be active -- Simplified API: Use `IServiceCollection.Add*DiscoveryClient()` to register, `IHttpClientBuilder.AddServiceDiscovery()` to consume +- Simplified API: Use `IServiceCollection.Add*DiscoveryClient()` to register; `IHttpClientBuilder.AddServiceDiscovery()` to consume - Refactored configuration to use ASP.NET Options pattern, responding to changes at runtime nearly everywhere - Async all-the-way where possible - More reliable cross-platform detection of local hostname and IP address - Now supports global service discovery: `services.ConfigureHttpClientDefaults(builder => builder.AddServiceDiscovery())` -- Config Server discovery-first can now query Consul, Eureka and Configuration-based +- Config Server discovery-first can now query Consul, Eureka, and Configuration-based - Improved detection of port bindings, including support for new ASP.NET [environment variables](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-8.0#http_ports-and-https_ports-config-keys) - HTTP handlers now depend on a load balancer, which delegates to multiple discovery clients - Major improvements in documentation, samples cover more use cases @@ -767,7 +767,7 @@ For more information, see the updated [Connectors documentation](../configuratio | `Steeltoe.Discovery.Eureka.EurekaApplicationInfoManager.UpdateInstance` | Method | Steeltoe.Discovery.Eureka | Added | | Enables to change local instance from code (synced with configuration) | | `Steeltoe.Discovery.Eureka.EurekaClientConfig` | Type | Steeltoe.Discovery.Eureka | Removed | `Steeltoe.Discovery.Eureka.Configuration.EurekaClientOptions` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerConnectTimeoutSeconds` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.ConnectTimeoutSeconds` | | -| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerRetryCount` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.RetryCount` | Default changed from 3 attempts to 2 retries (bugfix) | +| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerRetryCount` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.RetryCount` | Default changed from 3 attempts to 2 retries (bug fix) | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerServiceUrls` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.EurekaServerServiceUrls` | Now supports comma-delimited list of URLs | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthCheckEnabled` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.CheckEnabled` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthContribEnabled` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.ContributorEnabled` | | @@ -890,8 +890,8 @@ For more information, see the updated [Discovery documentation](../discovery/ind ### API changes -| Source | Kind | Package | Change | Replacement | Notes | -| --------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------ | ------- | ---------------------------------------------------------------- | ------------------------------------------------------------------- | +| Source | Kind | Package | Change | Replacement | Notes | +| ----------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------ | ------- | -------------------------------------------------------------- | ------------------------------------------------------------------- | | `Steeltoe.Extensions.Logging.DynamicLoggerConfiguration` | Type | Steeltoe.Extensions.Logging.Abstractions | Renamed | `Steeltoe.Logging.DynamicLoggerState` | Represents logger state, is unrelated to `IConfiguration` | | `Steeltoe.Extensions.Logging.DynamicLoggerConfiguration.ConfiguredLevel` | Property | Steeltoe.Extensions.Logging.Abstractions | Renamed | `DynamicLoggerState.BackupMinLevel` | The minimum level before override | | `Steeltoe.Extensions.Logging.DynamicLoggerConfiguration.EffectiveLevel` | Property | Steeltoe.Extensions.Logging.Abstractions | Renamed | `DynamicLoggerState.EffectiveMinLevel` | The active minimum level, taking overrides into account | From 8d21ae80b091698e10fdce5e02068e48d8bd86ad Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Wed, 26 Feb 2025 07:58:59 -0800 Subject: [PATCH 04/43] full edit Application Bootstrapping --- api/v4/bootstrap/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/api/v4/bootstrap/index.md b/api/v4/bootstrap/index.md index 6c06cbb0..c2f5972d 100644 --- a/api/v4/bootstrap/index.md +++ b/api/v4/bootstrap/index.md @@ -8,7 +8,7 @@ Get started by adding a reference to the AutoConfiguration package (you may want dotnet add package Steeltoe.Bootstrap.AutoConfiguration ``` -After adding the NuGet reference(s), simply include `.AddSteeltoe()` like you see in the code below and you're all set with the basic implementation. +After adding the NuGet reference(s), include `.AddSteeltoe()` like you see in the code below and you're all set with the basic implementation. ```csharp using Steeltoe.Bootstrap.AutoConfiguration; @@ -19,9 +19,9 @@ builder.AddSteeltoe(); ## Supported Steeltoe Packages -`Steeltoe.Bootstrap.AutoConfiguration` is not a meta-package. In order for a Steeltoe feature to be automatically bootstrapped in the application, the appropriate NuGet package must also be referenced. The following table describes the Steeltoe package that is required to light up a feature and any additional packages that may also be installed: +`Steeltoe.Bootstrap.AutoConfiguration` is not a meta-package. For a Steeltoe feature to be automatically bootstrapped in the application, the appropriate NuGet package must also be referenced. The following table describes the Steeltoe package that is required to light up a feature, and any additional packages that may also be installed: -| Feature Description | Steeltoe Package | Additional Packages | +| Feature Description | Steeltoe Package | Additional Packages | | --- | --- | --- | | [Config Server Configuration Provider](../configuration/config-server-provider.md) | `Steeltoe.Configuration.ConfigServer` | Optional: `Steeltoe.Discovery.Eureka` to use discovery-first | | [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) |`Steeltoe.Configuration.CloudFoundry` | N/A | @@ -29,7 +29,7 @@ builder.AddSteeltoe(); | [Placeholder Configuration Provider](../configuration/placeholder-provider.md) |`Steeltoe.Configuration.Placeholder` | N/A | | [Encrypted Configuration Provider](../configuration/decryption-provider.md) | `Steeltoe.Configuration.Encryption` | N/A | | [Spring Boot Configuration Provider](../configuration/spring-boot-provider.md) | `Steeltoe.Configuration.SpringBoot` | N/A | -| [Connectors](../connectors/index.md) |`Steeltoe.Connectors` | Required: Supported driver [^1] (MySQL, PostgreSQL, SQL Server, MongoDB, CosmosDB, Redis, RabbitMQ) | +| [Connectors](../connectors/index.md) |`Steeltoe.Connectors` | Required: Supported driver [^1] (MySQL, PostgreSQL, SQL Server, MongoDB, CosmosDB, Redis/Valkey, RabbitMQ) | | [Eureka Service Discovery](../discovery/netflix-eureka.md) |`Steeltoe.Discovery.Eureka` | Optional: `Steeltoe.Management.Endpoint` for health checks | | [Consul Service Discovery](../discovery/hashicorp-consul.md) |`Steeltoe.Discovery.Consul` | N/A | | [Configuration-based Service Discovery](../discovery/configuration-based.md) |`Steeltoe.Discovery.Configuration` | N/A | @@ -38,7 +38,7 @@ builder.AddSteeltoe(); | [Actuators](../management/index.md) | `Steeltoe.Management.Endpoint` | N/A | | [Distributed Tracing](../tracing/index.md) | `Steeltoe.Management.Tracing` | Required: OpenTelemetry Exporter (Zipkin, OTLP) | -[^1]: Individual connector clients will only be configured if a corresponding supported driver NuGet package reference is also included. +[^1]: Individual connector clients are only configured if a corresponding supported driver NuGet package reference is also included. ## Excluding Components @@ -56,7 +56,7 @@ builder.AddSteeltoe(assemblyNamesToExclude); ## Logging inside Configuration Providers -For some Steeltoe components, primarily configuration providers, providing a `LoggerFactory` is required to retrieve logs for debugging. Use the optional parameter to provide one as needed: +For some Steeltoe components, primarily configuration providers, a `LoggerFactory` is required to retrieve logs for debugging. Use the optional parameter to provide one as needed: ```csharp using Microsoft.Extensions.Logging.Debug; @@ -72,7 +72,7 @@ builder.AddSteeltoe(loggerFactory); ``` Alternatively, you can use `BootstrapLoggerFactory`. It logs to the console until the service container has been built. -Once the service container has become available, it automatically upgrades existing loggers to use the application configuration. +After the service container has become available, it automatically upgrades existing loggers to use the application configuration. ```csharp using Steeltoe.Bootstrap.AutoConfiguration; @@ -84,11 +84,11 @@ builder.AddSteeltoe(loggerFactory); ## Limitations -At this time there is no support for: +Currently unsupported: * Features that need to be configured directly in `IApplicationBuilder`, such as Cloud Foundry SSO and JWT. * Features that require a custom type (such as a `DbContext`) for setup. ## Feedback -Love it? Hate it? Want to know more or make a suggestion? Let us know by [filing an issue](https://github.com/SteeltoeOSS/Steeltoe/issues/new/choose), [joining us on slack](https://slack.steeltoe.io/) or [Tweeting at us](https://twitter.com/steeltoeoss) +Love it? Hate it? Want to know more or make a suggestion? Let us know by filing an [issue](https://github.com/SteeltoeOSS/Steeltoe/issues/new/choose), joining us on [Slack](https://slack.steeltoe.io/) or [Tweeting us](https://twitter.com/steeltoeoss) From 50d5ff8247a44b70bf2970e298ddb37e3d18a83a Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Wed, 26 Feb 2025 14:35:10 -0600 Subject: [PATCH 05/43] V4 Updates for Metrics, Tracing and Security (#336) * Update Cloud Foundry actuator/integration --------- Co-authored-by: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> --- api/v4/bootstrap/index.md | 4 +- .../configuration/config-server-provider.md | 2 +- api/v4/connectors/cosmosdb.md | 2 +- api/v4/connectors/microsoft-sql-server.md | 2 +- api/v4/connectors/mongodb.md | 4 +- api/v4/connectors/mysql.md | 6 +- api/v4/connectors/postgresql.md | 6 +- api/v4/connectors/rabbitmq.md | 4 +- api/v4/connectors/redis.md | 6 +- api/v4/fileshares/usage.md | 2 +- api/v4/logging/index.md | 2 +- api/v4/management/cloud-foundry.md | 59 ++-- api/v4/management/metrics-endpoint.md | 118 ------- api/v4/management/metrics.md | 124 -------- api/v4/management/prometheus.md | 196 +++++++++++- api/v4/management/using-endpoints.md | 1 - api/v4/security/{mtls.md => certificate.md} | 113 ++++--- api/v4/security/index.md | 6 +- api/v4/security/jwt-authentication.md | 144 --------- api/v4/security/jwt-bearer.md | 219 +++++++++++++ api/v4/security/redis-key-storage-provider.md | 158 +++++----- api/v4/security/sso-open-id.md | 153 ++++++--- api/v4/toc.yml | 15 +- .../tracing/distributed-tracing-exporting.md | 115 ------- api/v4/tracing/index.md | 293 +++++++++++++----- 25 files changed, 945 insertions(+), 809 deletions(-) delete mode 100644 api/v4/management/metrics-endpoint.md delete mode 100644 api/v4/management/metrics.md rename api/v4/security/{mtls.md => certificate.md} (57%) delete mode 100644 api/v4/security/jwt-authentication.md create mode 100644 api/v4/security/jwt-bearer.md delete mode 100644 api/v4/tracing/distributed-tracing-exporting.md diff --git a/api/v4/bootstrap/index.md b/api/v4/bootstrap/index.md index 6c06cbb0..f911a19e 100644 --- a/api/v4/bootstrap/index.md +++ b/api/v4/bootstrap/index.md @@ -4,7 +4,7 @@ To improve the Steeltoe developer experience, this feature allows the configurat Get started by adding a reference to the AutoConfiguration package (you may want to add other Steeltoe references at this point too, see [the table below](#supported-steeltoe-packages) for the full list of what's supported): -``` +```shell dotnet add package Steeltoe.Bootstrap.AutoConfiguration ``` @@ -36,7 +36,7 @@ builder.AddSteeltoe(); | [Dynamic Console Logging](../logging/dynamic-console-logging.md) | `Steeltoe.Logging.DynamicConsole` | N/A | | [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) | `Steeltoe.Logging.DynamicSerilog` | N/A | | [Actuators](../management/index.md) | `Steeltoe.Management.Endpoint` | N/A | -| [Distributed Tracing](../tracing/index.md) | `Steeltoe.Management.Tracing` | Required: OpenTelemetry Exporter (Zipkin, OTLP) | +| [Distributed Tracing](../tracing/index.md) | `Steeltoe.Management.Tracing` | N/A | [^1]: Individual connector clients will only be configured if a corresponding supported driver NuGet package reference is also included. diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index 0c8cd318..b98c3d3a 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -6,7 +6,7 @@ The Spring Cloud Config Server is an application configuration service that give To gain a better understanding of the Spring Cloud Config Server, you should read the [Spring Cloud Config documentation](https://spring.io/projects/spring-cloud-config). -In addition to the Quick Start provided later, you can refer to the [Steeltoe ConfigurationProviders](https://github.com/SteeltoeOSS/Samples/tree/latest/Configuration/src/ConfigurationProviders) sample application when you need to understand how to use this provider. +In addition to the Quick Start provided later, you can refer to the [Steeltoe ConfigurationProviders](https://github.com/SteeltoeOSS/Samples/tree/main/Configuration/src/ConfigurationProviders) sample application when you need to understand how to use this provider. ## Usage diff --git a/api/v4/connectors/cosmosdb.md b/api/v4/connectors/cosmosdb.md index 8d37ac91..351130a0 100644 --- a/api/v4/connectors/cosmosdb.md +++ b/api/v4/connectors/cosmosdb.md @@ -118,7 +118,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `CosmosClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/CosmosDb. +A complete sample app that uses `CosmosClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/CosmosDb. ## Cloud Foundry diff --git a/api/v4/connectors/microsoft-sql-server.md b/api/v4/connectors/microsoft-sql-server.md index b3555513..6143765c 100644 --- a/api/v4/connectors/microsoft-sql-server.md +++ b/api/v4/connectors/microsoft-sql-server.md @@ -135,7 +135,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses Entity Framework Core with SQL Server is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/SqlServerEFCore. +A complete sample app that uses Entity Framework Core with SQL Server is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/SqlServerEFCore. ## Cloud Foundry diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index 2a8efe6a..c38d8554 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -96,7 +96,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IMongoClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MongoDb. +A complete sample app that uses `IMongoClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb. ## Cloud Foundry @@ -121,4 +121,4 @@ cf restage myApp This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MongoDb#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb#running-on-tanzu-application-platform-tap. diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index d1972b6c..00774ec4 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -86,7 +86,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `MySqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MySql. +A complete sample app that uses `MySqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql. ### Use Entity Framework Core @@ -139,7 +139,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses Entity Framework Core with MySQL is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MySqlEFCore. +A complete sample app that uses Entity Framework Core with MySQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySqlEFCore. ## Cloud Foundry @@ -166,4 +166,4 @@ cf restage myApp This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MySql#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql#running-on-tanzu-application-platform-tap. diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index 991548e9..541b3d46 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -84,7 +84,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `NpgsqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/PostgreSql. +A complete sample app that uses `NpgsqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql. ### Use Entity Framework Core @@ -137,7 +137,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses Entity Framework Core with PostgreSQL is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/PostgreSqlEFCore. +A complete sample app that uses Entity Framework Core with PostgreSQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSqlEFCore. ## Cloud Foundry @@ -163,4 +163,4 @@ cf restage myApp This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/PostgreSql#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql#running-on-tanzu-application-platform-tap. diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index b9ea0fa0..396aac46 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -82,7 +82,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/RabbitMQ. +A complete sample app that uses `IConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ. ## Cloud Foundry @@ -107,4 +107,4 @@ cf restage myApp This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/RabbitMQ#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ#running-on-tanzu-application-platform-tap. diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index 9126fcd0..a13976a1 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -81,7 +81,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IConnectionMultiplexer` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/Redis. +A complete sample app that uses `IConnectionMultiplexer` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. ### Use IDistributedCache @@ -109,7 +109,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IDistributedCache` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/Redis. +A complete sample app that uses `IDistributedCache` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. ## Cloud Foundry @@ -136,4 +136,4 @@ cf restage myApp This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/Redis#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis#running-on-tanzu-application-platform-tap. diff --git a/api/v4/fileshares/usage.md b/api/v4/fileshares/usage.md index eaf54961..becff280 100644 --- a/api/v4/fileshares/usage.md +++ b/api/v4/fileshares/usage.md @@ -40,7 +40,7 @@ Credentials are generally required for interacting with SMB shares. `WindowsNetw When used in conjunction with the Cloud Foundry Configuration Provider, you can access the values as follows: -``` +```shell dotnet add package Steeltoe.Configuration.CloudFoundry dotnet add package Steeltoe.Common.Net ``` diff --git a/api/v4/logging/index.md b/api/v4/logging/index.md index 30fda630..0422cbb9 100644 --- a/api/v4/logging/index.md +++ b/api/v4/logging/index.md @@ -1,6 +1,6 @@ # Dynamic Logging -Steeltoe includes two logging providers that enhance existing logger libraries with support for managing minimum log levels at runtime through the [Steeltoe Management logger endpoint](../management/loggers.md) and [recording distributed trace information](../tracing/index.md#enabling-log-correlation). +Steeltoe includes two logging providers that enhance existing logger libraries with support for managing minimum log levels at runtime through the [Steeltoe Management logger endpoint](../management/loggers.md) and [recording distributed trace information](../tracing/index.md#log-correlation). * [Dynamic Console Logging](./dynamic-console-logging.md) works with `Microsoft.Extensions.Logging.Console`. * [Dynamic Serilog Logging](./dynamic-serilog-logging.md) works with `Serilog` diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index ce4b16d3..3781c1e5 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -1,31 +1,15 @@ # Cloud Foundry Integration -Integration with Apps Manager is accomplished by adding the Cloud Foundry management endpoint to your application. When used, this endpoint enables the following additional functionality on Cloud Foundry: +Integration with [Tanzu Apps Manager](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/console-index.html) is accomplished by adding the Cloud Foundry management endpoint to your application. -* Provides an alternate, secured route to the endpoints expected by Apps Manager and configured in your application. -* Exposes an endpoint that can be queried to return the IDs of and links to the enabled management endpoints in the application. -* Adds Cloud Foundry security middleware to the request pipeline, to secure access to the management endpoints by using security tokens acquired from the UAA. +When used, this endpoint enables the following additional functionality on Cloud Foundry: -> [!NOTE] -> The Cloud Foundry integration will not work unless the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured. - -## Security - -When adding this management endpoint to your application, the Cloud Foundry security middleware is added to the request processing pipeline of your application to enforce that, when a request is made to any of the management endpoints, a valid UAA access token is provided as part of that request. Additionally, the security middleware uses the token to determine whether the authenticated user has permission to access the management endpoint. +* A variant of the [hypermedia](./hypermedia.md) endpoint is registered at `/cloudfoundryapplication`. +* All endpoints are additionally mapped under the base path `/cloudfoundryapplication`. +* [Authentication and authorization](#security) for your Cloud Foundry environment is added to the request pipeline. > [!NOTE] -> The Cloud Foundry security middleware is only active when your application is running on Cloud Foundry. - -## External access - -When running in Cloud Foundry, it is possible to access the endpoints via the [hypermedia](./hypermedia.md) URL, which defaults to `/actuator`. In other words, you can also access all your endpoints from this URL prefix. For example, the [info](./info.md) endpoint would be accessible at `/actuator/info`. - -While the endpoints provided on the `/cloudfoundryapplication` path are secured as described above, the endpoints provided on the `/actuator` path are not. -For this reason, all endpoints are exposed by default at `/cloudfoundryapplication`, but only health and info are exposed by default at `/actuator`. -In addition, the endpoints may be secured by whatever security mechanism the application itself uses. For more details, see [securing actuators](./using-endpoints.md#securing-endpoints). - -> [!CAUTION] -> Applying an authorization policy on `/actuator` will also impact `/cloudfoundryapplication`, which will break the integration with Apps Manager. +> The Cloud Foundry integration will not work unless the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured. ## Configure Settings @@ -50,7 +34,7 @@ The default path is `/cloudfoundryapplication`. See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. -To add the actuator to the service container, add a CORS policy, register security middleware and map its route, use the `AddCloudFoundryActuator` extension method. +To add the actuator to the service container, add a [CORS](#cross-origin-resource-sharing) policy, register security middleware and map its route, use the `AddCloudFoundryActuator` extension method. Add the following code to `Program.cs` to use the actuator endpoint: @@ -66,3 +50,32 @@ builder.Services.AddCloudFoundryActuator(); > [!TIP] > It's recommended to use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. + +### Cross Origin Resource Sharing + +When viewing an application in Apps Manager, HTTP requests are sent directly to application instances with the bearer token of the logged-in user attached. +The nature of this integration requires the use of Cross Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). +The policy defined in Steeltoe intends to limit sharing to the minimum required for the endpoints to function, however there is no way for Steeltoe to discover or even guess at what the origin of an Apps Manager instance could be. +As such, the default policy will allow any origin, unless the policy is customized. You should consider [customizing the CORS policy](./using-endpoints.md#customizing-the-cors-policy) to be more specific. + +## Security + +When adding this management endpoint to your application, the Cloud Foundry security middleware is added to the request processing pipeline of your application. +The Cloud Foundry security middleware requires a valid UAA access token to be provided as part of any request to any of the management endpoints. +Additionally, the security middleware evaluates the token to determine whether the authenticated user has permission to access the management endpoint. + +> [!NOTE] +> The Cloud Foundry security middleware is only active when your application is running on Cloud Foundry. + +## External access + +When running in Cloud Foundry, it is still possible to access the endpoints via the [hypermedia](./hypermedia.md) URL, which defaults to `/actuator`. +In other words, you can also access all your endpoints from this URL prefix. For example, the [info](./info.md) endpoint would be accessible at `/actuator/info`. + +While the endpoints provided on the `/cloudfoundryapplication` path are secured as described above, the endpoints provided on the `/actuator` path are not. +For this reason, all endpoints are exposed by default at `/cloudfoundryapplication`, but only health and info are exposed by default at `/actuator`. +In addition, the endpoints may be secured by whatever security mechanism the application itself uses. For more details, see [securing actuators](./using-endpoints.md#securing-endpoints). + +> [!CAUTION] +> Applying an authorization policy on `/actuator` will also impact `/cloudfoundryapplication`, which will break the integration with Apps Manager. +> In order to prevent public access to `/actuator` when running on Cloud Foundry, consider configuring actuators to [use an alternate port](./using-endpoints.md#configure-global-settings). diff --git a/api/v4/management/metrics-endpoint.md b/api/v4/management/metrics-endpoint.md deleted file mode 100644 index 9ca5752e..00000000 --- a/api/v4/management/metrics-endpoint.md +++ /dev/null @@ -1,118 +0,0 @@ -# Metrics - -The Steeltoe Metrics endpoint configures built-in instrumentation of various aspects of the application and exposes them in Spring Boot Metrics format. - -The following instrumentation is automatically configured: - -* CLR metrics - * Heap memory, garbage collections, thread utilization -* ASP.NET metrics - * Request timings and counts -* HttpClient metrics - * Request timings and counts - -All of these metrics are tagged with values specific to the request being processed, thereby giving multi-dimensional views of the collected metrics. - -## Configure Settings - -The following table describes the configuration settings that you can apply to the endpoint. -Each key must be prefixed with `Management:Endpoints:Metrics:`. - -| Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `metrics` | -| `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 the endpoint is exposed at. | `GET` | -| `CacheDurationMilliseconds` | The duration that metrics are cached for. | `500` | -| `MaxTimeSeries` | The maximum number of time series to return. | `100` | -| `MaxHistograms` | The maximum number of histograms to return. | `100` | -| `IncludedMetrics` | An array of additional [metric names](https://learn.microsoft.com/dotnet/core/diagnostics/available-counters#systemruntime-counters) to include. | | - -## Enable HTTP Access - -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. -The default path is `/actuator/metrics`. - -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. - -To add the actuator to the service container and map its route, use the `AddMetricsActuator` extension method. - -Add the following code to `Program.cs` to use the actuator endpoint: - -```csharp -using Steeltoe.Management.Endpoint.Actuators.Metrics; - -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddMetricsActuator(); -``` - -> [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. - -## Sample Output - -This endpoint returns the metric names. - -The response will always be returned as JSON, like this: - -```json -{ - "names": [ - "clr.gc.collections", - "http.client.request.time", - "clr.process.uptime", - "clr.memory.used", - "http.server.requests.seconds", - "clr.cpu.count", - "clr.threadpool.avail", - "http.client.request.count", - "clr.threadpool.active", - "http.server.requests.count" - ] -} -``` - -The names returned can be used to obtain metric values. -For example, a `GET` request to `actuator/metrics/http.server.requests.count` returns something like: - -```json -{ - "name": "http.server.requests.count", - "measurements": [ - { - "statistic": "Total", - "value": 4 - } - ], - "availableTags": [ - { - "tag": "exception", - "values": [ - "None" - ] - }, - { - "tag": "method", - "values": [ - "GET" - ] - }, - { - "tag": "status", - "values": [ - "200" - ] - }, - { - "tag": "uri", - "values": [ - "/actuator/metrics/http.server.requests.count", - "/actuator/metrics" - ] - } - ] -} -``` diff --git a/api/v4/management/metrics.md b/api/v4/management/metrics.md deleted file mode 100644 index d8feef70..00000000 --- a/api/v4/management/metrics.md +++ /dev/null @@ -1,124 +0,0 @@ -# Metrics - -The metrics functionality in Steeltoe is built on top of the OpenTelemetry project. Steeltoe extends its functionality by providing additional instrumentation (via Metric Observers) and makes it easy to export to additional destinations, such as Cloud Foundry, Spring Boot Admin, App Live View & Tanzu Observability. - -## Add NuGet References - -To use any of the metrics functionality, you need to add a reference to the `Steeltoe.Management.Endpoint` NuGet package. - -## Metric Observers - -Adding either the [metrics](./metrics-endpoint.md) or [prometheus](./prometheus.md) endpoints automatically configures built-in instrumentation of various aspects of the application. - -The following instrumentation is available: - -| Metrics Type | Description | -| --- | --- | -| CLR | Heap memory, Garbage collections, Thread utilization. | -| HTTP Client | Request timings & counts. | -| HTTP Server | Request timings & counts. | -| Event Counter | CPU, Memory. | - -All of the above metrics are tagged with values specific to the requests being processed, thereby giving multi-dimensional views of the collected metrics. - -### Configure Settings - -The following table describes the configuration settings that you can apply to the observers. -Each key must be prefixed with `Management:Metrics:Observer`. - -| Key | Description | Default | -| --- | --- | --- | -| `IngressIgnorePattern` | Regex pattern describing what incoming requests to ignore. | See `MetricsObserverOptions` | -| `EgressIgnorePattern` | Regex pattern describing what outgoing requests to ignore. | See `MetricsObserverOptions` | -| `AspNetCoreHosting` | Enable Http Server Metrics. | `true` | -| `GCEvents` | Enable Garbage collector Metrics. | `true` | -| `ThreadPoolEvents` | Enable Thread Pool Metrics. | `true` | -| `EventCounterEvents` | Enable Event Counter Metrics. | `false` | -| `HttpClientCore` | Enable Http Client Metrics. | `false` | -| `HttpClientDesktop` | Enable Http Client Desktop Metrics. | `false` | -| `ExcludedMetrics` | Specify a list of metrics that should not be captured | none | - -> [!NOTE] -> The ExcludedMetrics option only applies to [these events](https://learn.microsoft.com/dotnet/core/diagnostics/available-counters#systemruntime-counters), which are captured from counters in the runtime. The observer that reports these metrics is controlled by the `EventCounterEvents` setting above. - -## Metric Exporters - -Steeltoe supports both pull and push-based configuration for exporting metrics. The pull-based mechanism is supported by the [metrics](./metrics-endpoint.md) or [prometheus](./prometheus.md) endpoints. The push-based mechanism is supported by Wavefront Exporter. - -### Tanzu Observability (Wavefront) - -[Tanzu Observability](https://docs.wavefront.com/wavefront_introduction.html) is an observability platform for distributed applications that can ingest metric & trace data. A free trial is available [here](https://tanzu.vmware.com/observability-trial) to try it. - -To add the Wavefront metric exporter, you can use any of the available extension methods: - -* `hostBuilder.AddWavefrontMetrics` extension method from `ManagementHostBuilderExtensions`. -* `AddWavefrontMetrics()` extension method from `ManagementWebHostBuilderExtensions`. -* `AddWavefrontMetrics()` extension method from `ManagementWebApplicationBuilderExtensions`. - -In addition, the following settings are available to be configured. -Each key must be prefixed with `Management:Metrics:Export:Wavefront`. -Note that these settings are shared between tracing and metrics. - -| Key | Description | Default | -| --- | --- | --- | -| `ApiToken` | Your Tanzu Observability [API Token](https://docs.wavefront.com/users_account_managing.html#generate-an-api-token) | not set | -| `Uri` | The Uri of your Wavefront Instance | not set | -| `Step` | The interval between reporting to Wavefront | 30000 | -| `BatchSize` | The max batch of data sent per flush interval | 10000 | -| `MaxQueueSize` | the size of the internal buffer beyond which data is dropped | 500000 - -If using a proxy, the `ApiToken` is not needed and the `Uri` would be `proxy://:` - -In addition, the following configuration settings can be used to set the application and service names. -Each key must be prefixed with `Wavefront:Application`. - -| Key | Description | Default | -| --- | --- | --- | -| `Source`| Unique identifier for the app instance that is publishing metrics to Wavefront | DNS name -| `Name` | Name of the application | SteeltoeApp | -| `Service` | Name of the service | SteeltoeService | - - - -### Tanzu Platform for Cloud Foundry - -To emit custom metrics on v2.5 or later, use the Metric Registrar. For more information about enabling and configuring the Metric Registrar, see [Configuring the Metric Registrar](https://docs.pivotal.io/application-service/2-11/metric-registrar/index.html). - -To register your endpoint for metrics collection, install the metrics-registrar plugin and use it to register your endpoint: - -```bash -cf install-plugin -r CF-Community "metric-registrar" -cf register-metrics-endpoint your-dotnet-app /actuator/prometheus -``` - -### Prometheus Server - -You can set up [Prometheus Server](https://prometheus.io/) to scrape this endpoint by registering your application in the server's configuration. For example, the following `prometheus.yml` file expects a Steeltoe-enabled application to be running on port 8000 with the actuator management path at the default of `/actuator`: - -```yml -global: - scrape_interval: 15s # Set the scrape interval to every 15 seconds. The default is every 1 minute. - evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute. - # scrape_timeout is set to the global default (10s). -scrape_configs: - # The job name is added as a label `job=` to any timeseries scraped from this config. - - job_name: 'steeltoe-prometheus' - metrics_path: '/actuator/prometheus' - scrape_interval: 5s - static_configs: - - targets: ['host.docker.internal:8000'] -``` - -Running the Prometheus server with this configuration lets you view metrics in the built-in UI. You can then configure other visualization tools, such as [Grafana](https://grafana.com/docs/grafana/latest/features/datasources/prometheus/), to use Prometheus as a data source. The following example shows how to run Prometheus in Docker: - -```bash -docker run -d --name=prometheus -p 9090:9090 -v /prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml -``` - -### Tanzu App Live View - - [App Live View](https://docs.vmware.com/en/Application-Live-View-for-VMware-Tanzu/1.0/docs/GUID-index.html) has the ability to display and query metrics via the [metrics endpoint](metrics-endpoint.md) in addition to other management endpoints. - -### Spring Boot Admin - - The [metrics endpoint](metrics-endpoint.md) is also compatible with [Spring Boot Admin](https://github.com/codecentric/spring-boot-admin). See [Spring Boot Admin client](springbootadmin.md) for details. diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index 0c480095..d44a8475 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -1,10 +1,14 @@ # Prometheus -The Steeltoe Prometheus endpoint exposes metrics collected via built-in instrumentation of various aspects of the application in the Prometheus format. Similar to the [metrics endpoint](./metrics-endpoint.md), it automatically configures built-in instrumentation of various aspects of the application. +You can use the Prometheus endpoint to expose application metrics for collection by an external process. -The metrics collected are the same as those collected by the [metrics endpoint](./metrics-endpoint.md). +The Steeltoe Prometheus endpoint configures the [OpenTelemetry Prometheus Exporter](https://opentelemetry.io/docs/languages/net/exporters/#prometheus) to behave like a Steeltoe management endpoint. -## Add NuGet References +The Prometheus endpoint does not automatically instrument your application, but does make it easy to export metrics in the Prometheus metrics format, which can be used by tools like [Prometheus Server](https://prometheus.io/) and the [Metric Registrar for Tanzu Platform for Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/metric-registrar-index.html). + +The [Steeltoe Management samples](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src/ActuatorWeb/README.md) can help you understand how to use this tool. + +## Add NuGet Reference To use the Prometheus endpoint, you need to add a reference to the `Steeltoe.Management.Prometheus` NuGet package. @@ -21,7 +25,8 @@ Each key must be prefixed with `Management:Endpoints:Prometheus:`. | `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | | `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -To configure Observers, see [metric observers](./metrics.md#metric-observers). +> [!NOTE] +> The `AllowedVerbs` setting is inherited from Steeltoe's `EndpointOptions`, but is not intended to work for the Prometheus exporter, which is only registered to respond to `GET` requests. ## Enable HTTP Access @@ -41,6 +46,183 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddPrometheusActuator(); ``` -> [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +### Configuring the request pipeline for Prometheus + +In addition to the options described in [using endpoints](./using-endpoints.md), `AddPrometheusActuator` exposes an `Action?` that can be used to configure the branched request pipeline that is used in the underlying OpenTelemetry package. +This pipeline would need to be configured if, as an example, you are configuring an authorization policy. + +```csharp +builder.Services.AddPrometheusActuator(true, pipeline => pipeline.UseAuthorization()); +``` + +## Instrumentation + +In order for the Prometheus endpoint to return metrics, the application and relevant libraries need to be instrumented. +This page will cover the basics for elements that previous versions of Steeltoe configured automatically. +Please refer to the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net/instrumentation/) for more detailed information. + +### ASP.NET Core + +To instrument ASP.NET Core for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. + +Next, add the instrumentation to the `MeterProviderBuilder`: + +```csharp +using OpenTelemetry.Metrics; + +builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddAspNetCoreInstrumentation()); +``` + +[Learn more about ASP.NET Core instrumentation for OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore) + +### HttpClient + +To instrument `HttpClient`s for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. + +Next, add the instrumentation to the `MeterProviderBuilder`: + +```csharp +using OpenTelemetry.Metrics; + +builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddHttpClientInstrumentation()); +``` + +[Learn more about HttpClient instrumentation for OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http) + +### .NET Runtime + +To instrument the .NET Runtime for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.Runtime` NuGet package. + +Next, add the instrumentation to the `MeterProviderBuilder`: + +```csharp +using OpenTelemetry.Metrics; + +builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddRuntimeInstrumentation()); +``` + +[Learn more about Runtime Instrumentation for OpenTelemetry .NET](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Runtime) + +### Prometheus Server + +You can set up Prometheus to scrape this endpoint by registering your application in the server's configuration. + +As an example, the following `prometheus.yml` file configures metric scraping for a Steeltoe-enabled application listening on port 8091 with the default actuator path: + +```yml +global: + scrape_interval: 15s # Set the scrape interval to every 15 seconds. The default is every 1 minute. + evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute. + # scrape_timeout is set to the global default (10s). +scrape_configs: + # The job name is added as a label `job=` to any timeseries scraped from this config. + - job_name: 'steeltoe-prometheus' + metrics_path: '/actuator/prometheus' + scrape_interval: 5s + static_configs: + - targets: ['host.docker.internal:8091'] +``` + +Running the Prometheus server with this configuration lets you view metrics in the built-in UI. +You can then configure other visualization tools, such as [Grafana](https://grafana.com/docs/grafana/latest/features/datasources/prometheus/), to use Prometheus as a data source. + +The following example shows how to run Prometheus in Docker, referencing the configuration file from above: + +```shell +docker run -d --name=prometheus -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml +``` + +### Tanzu Platform for Cloud Foundry + +To emit custom metrics in Cloud Foundry, use [Metric Registrar](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/metric-registrar-index.html). + +> [!CAUTION] +> Authenticated endpoints are not supported with Metric Registrar. +> For this scenario, configure actuators to [use an alternate port](./using-endpoints.md#configure-global-settings) and use that private network port to offer the metrics. + +The examples below expect that actuators are mapped to an alternate port (8091 in this case). +The specific port that is used is not important to Steeltoe, it only matters that the binding and Steeltoe configurations match. + +#### Metrics Registrar Plugin + +Install the metrics-registrar plugin and use it to register your endpoint: + +```shell +cf install-plugin -r CF-Community "metric-registrar" +cf register-metrics-endpoint APP-NAME /actuator/prometheus --internal-port 8091 +``` + +> [!CAUTION] +> Due to an issue with the Cloud Foundry CLI plugin interface, some variations on this command do not work on Windows. +> If you are a Windows user, you should either use the metric registrar plugin from WSL or use another method. + +#### Create User Provided Service + +The result of using the metrics registrar plugin is a user-provided service, which can also be created and bound manually. + +```shell +cf create-user-provided-service APP-NAME -l secure-endpoint://:8091/actuator/prometheus +cf bind-service APP-NAME SERVICE-NAME +``` + +## Sample Output + +This endpoint returns information about the instrumented application metrics and their values. + +If no instrumentation has been included, the response will be very short, like this: + +```text +# EOF +``` + +With the addition of [.NET Runtime instrumentation](#net-runtime), the response will be like this: + +```text +# TYPE process_runtime_dotnet_gc_collections_count_total counter +# HELP process_runtime_dotnet_gc_collections_count_total Number of garbage collections that have occurred since process start. +process_runtime_dotnet_gc_collections_count_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0",generation="gen2"} 0 1740147372796 +process_runtime_dotnet_gc_collections_count_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0",generation="gen1"} 0 1740147372796 +process_runtime_dotnet_gc_collections_count_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0",generation="gen0"} 0 1740147372796 +# TYPE process_runtime_dotnet_gc_objects_size_bytes gauge +# UNIT process_runtime_dotnet_gc_objects_size_bytes bytes +# HELP process_runtime_dotnet_gc_objects_size_bytes Count of bytes currently in use by objects in the GC heap that haven't been collected yet. Fragmentation and other GC committed memory pools are excluded. +process_runtime_dotnet_gc_objects_size_bytes{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 8830400 1740147372797 +# TYPE process_runtime_dotnet_gc_allocations_size_bytes_total counter +# UNIT process_runtime_dotnet_gc_allocations_size_bytes_total bytes +# HELP process_runtime_dotnet_gc_allocations_size_bytes_total Count of bytes allocated on the managed GC heap since the process start. .NET objects are allocated from this heap. Object allocations from unmanaged languages such as C/C++ do not use this heap. +process_runtime_dotnet_gc_allocations_size_bytes_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 8813792 1740147372797 +# TYPE process_runtime_dotnet_gc_duration_nanoseconds_total counter +# UNIT process_runtime_dotnet_gc_duration_nanoseconds_total nanoseconds +# HELP process_runtime_dotnet_gc_duration_nanoseconds_total The total amount of time paused in GC since the process start. +process_runtime_dotnet_gc_duration_nanoseconds_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 0 1740147372797 +# TYPE process_runtime_dotnet_jit_il_compiled_size_bytes_total counter +# UNIT process_runtime_dotnet_jit_il_compiled_size_bytes_total bytes +# HELP process_runtime_dotnet_jit_il_compiled_size_bytes_total Count of bytes of intermediate language that have been compiled since the process start. +process_runtime_dotnet_jit_il_compiled_size_bytes_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 272834 1740147372797 +# TYPE process_runtime_dotnet_jit_methods_compiled_count_total counter +# HELP process_runtime_dotnet_jit_methods_compiled_count_total The number of times the JIT compiler compiled a method since the process start. The JIT compiler may be invoked multiple times for the same method to compile with different generic parameters, or because tiered compilation requested different optimization settings. +process_runtime_dotnet_jit_methods_compiled_count_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 4597 1740147372797 +# TYPE process_runtime_dotnet_jit_compilation_time_nanoseconds_total counter +# UNIT process_runtime_dotnet_jit_compilation_time_nanoseconds_total nanoseconds +# HELP process_runtime_dotnet_jit_compilation_time_nanoseconds_total The amount of time the JIT compiler has spent compiling methods since the process start. +process_runtime_dotnet_jit_compilation_time_nanoseconds_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 562297300 1740147372797 +# TYPE process_runtime_dotnet_monitor_lock_contention_count_total counter +# HELP process_runtime_dotnet_monitor_lock_contention_count_total The number of times there was contention when trying to acquire a monitor lock since the process start. Monitor locks are commonly acquired by using the lock keyword in C#, or by calling Monitor.Enter() and Monitor.TryEnter(). +process_runtime_dotnet_monitor_lock_contention_count_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 0 1740147372797 +# TYPE process_runtime_dotnet_thread_pool_threads_count gauge +# HELP process_runtime_dotnet_thread_pool_threads_count The number of thread pool threads that currently exist. +process_runtime_dotnet_thread_pool_threads_count{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 5 1740147372797 +# TYPE process_runtime_dotnet_thread_pool_completed_items_count_total counter +# HELP process_runtime_dotnet_thread_pool_completed_items_count_total The number of work items that have been processed by the thread pool since the process start. +process_runtime_dotnet_thread_pool_completed_items_count_total{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 62 1740147372797 +# TYPE process_runtime_dotnet_thread_pool_queue_length gauge +# HELP process_runtime_dotnet_thread_pool_queue_length The number of work items that are currently queued to be processed by the thread pool. +process_runtime_dotnet_thread_pool_queue_length{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 0 1740147372797 +# TYPE process_runtime_dotnet_timer_count gauge +# HELP process_runtime_dotnet_timer_count The number of timer instances that are currently active. Timers can be created by many sources such as System.Threading.Timer, Task.Delay, or the timeout in a CancellationSource. An active timer is registered to tick at some point in the future and has not yet been canceled. +process_runtime_dotnet_timer_count{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 2 1740147372797 +# TYPE process_runtime_dotnet_assemblies_count gauge +# HELP process_runtime_dotnet_assemblies_count The number of .NET assemblies that are currently loaded. +process_runtime_dotnet_assemblies_count{otel_scope_name="OpenTelemetry.Instrumentation.Runtime",otel_scope_version="1.11.0"} 149 1740147372797 +# EOF +``` diff --git a/api/v4/management/using-endpoints.md b/api/v4/management/using-endpoints.md index 53487873..91ff220b 100644 --- a/api/v4/management/using-endpoints.md +++ b/api/v4/management/using-endpoints.md @@ -25,7 +25,6 @@ The following table describes the available Steeltoe management endpoints that c | [info](./info.md) | Customizable endpoint that gathers arbitrary application information (such as app version). | | [loggers](./loggers.md) | Gathers existing logger categories and allows changing their minimum levels at runtime. | | [mappings](./mappings.md) | Reports the configured ASP.NET routes and route templates. | -| [metrics](./metrics.md) | Reports the collected metrics for the application. | | [prometheus](./prometheus.md) | Exposes metrics collected via built-in instrumentation of various aspects of the application in the Prometheus format. | | [refresh](./refresh.md) | Triggers a reload of the application configuration. | | [services](./services.md) | Lists the contents of the .NET dependency injection service container. | diff --git a/api/v4/security/mtls.md b/api/v4/security/certificate.md similarity index 57% rename from api/v4/security/mtls.md rename to api/v4/security/certificate.md index 8eddacf2..d563d67a 100644 --- a/api/v4/security/mtls.md +++ b/api/v4/security/certificate.md @@ -1,6 +1,9 @@ # Resource Protection using Mutual TLS in ASP.NET Core -This component builds on top of [ASP.NET Core's Certificate Authentication](https://learn.microsoft.com/aspnet/core/security/authentication/certauth), with the addition of automatic configuration for [Cloud Foundry Instance Identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) and authorization policies based on certificate data. Additionally, resources are included for automatically generating certificates for local development that resemble what is found on the platform. +Certificate Authentication, also known as Mutual TLS, is a way for a client and server to validate each other's identity. This method is commonly used to secure service-to-service communications. + +This library is a supplement to [ASP.NET Core Certificate Authentication](https://learn.microsoft.com/aspnet/core/security/authentication/certauth), adding functionality that helps you use [Cloud Foundry Instance Identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) and authorization policies based on certificate data. +Additionally, resources are included for automatically generating certificates for local development that resemble what is found on the platform. ## Usage @@ -8,44 +11,47 @@ In order to use this provider, the following steps are required: 1. Add NuGet package reference 1. Add identity certificates to the configuration -1. Configure authentication and authorization services -1. Include services in the ASP.NET Core pipeline -1. Secure endpoints +1. Add and use the security provider in the application +1. Secure your endpoints 1. Attach certificate to requests to secured endpoints ### Add NuGet Reference +> [!NOTE] +> This step is required on all applications that are sending or receiving certificate-authorized requests. + To use Certificate Authorization, you need to add a reference to the `Steeltoe.Security.Authorization.Certificate` NuGet package. +### Add Identity Certificates to Configuration + > [!NOTE] > This step is required on all applications that are sending or receiving certificate-authorized requests. -### Configure Settings - -In a Cloud Foundry environment, instance identity certificates are automatically provisioned (and rotated on a regular basis) for each application instance. Steeltoe provides the `AddAppInstanceIdentityCertificate` extension method to find the location of the certificate files from the environment variables `CF_INSTANCE_CERT` and `CF_INSTANCE_KEY`. When running outside of Cloud Foundry, this method will automatically generate similar certificates. Use the optional parameters to coordinate `organizationId` and/or `spaceId` between your applications to facilitate communication when running outside of Cloud Foundry. +In a Cloud Foundry environment, instance identity certificates are automatically provisioned (and rotated on a regular basis) for each application instance. +Steeltoe provides the extension method `AddAppInstanceIdentityCertificate` to find the location of the certificate files from the environment variables `CF_INSTANCE_CERT` and `CF_INSTANCE_KEY`. +When running outside of Cloud Foundry, this method will automatically generate similar certificates. +Use the optional parameters to coordinate `orgId` and/or `spaceId` between your applications to facilitate communication when running outside of Cloud Foundry. This code adds the certificate paths to the configuration for use later (and generates the instance identity certificate when running outside Cloud Foundry): ```csharp using Steeltoe.Common.Certificates; -const string organizationId = "a8fef16f-94c0-49e3-aa0b-ced7c3da6229"; +const string orgId = "a8fef16f-94c0-49e3-aa0b-ced7c3da6229"; const string spaceId = "122b942a-d7b9-4839-b26e-836654b9785f"; -WebApplicationBuilder builder = WebApplication.CreateBuilder(args); -builder.Configuration.AddAppInstanceIdentityCertificate(new Guid(organizationId), new Guid(spaceId)); +var builder = WebApplication.CreateBuilder(args); +builder.Configuration.AddAppInstanceIdentityCertificate(new Guid(orgId), new Guid(spaceId)); ``` -When running locally, the code shown above will create a chain of self-signed certificates and the application instance identity certificate will have a subject containing an OrgId of `a8fef16f-94c0-49e3-aa0b-ced7c3da6229` and a SpaceId of `122b942a-d7b9-4839-b26e-836654b9785f`. A root certificate and intermediate certificate are created on disk one level above the current project in a directory named `GeneratedCertificates`. The root and intermediate certificates will automatically be shared between applications housed within the same solution, so that the applications will be able to trust each other. - -> [!NOTE] -> This step is required on all applications that are sending or receiving certificate-authorized requests. - -### Securing Endpoints +When running locally, the code shown above will create a chain of self-signed certificates and the application instance identity certificate will have a subject containing an OrgId of `a8fef16f-94c0-49e3-aa0b-ced7c3da6229` and a SpaceId of `122b942a-d7b9-4839-b26e-836654b9785f`. +A root certificate and intermediate certificate are created on disk one level above the current project in a directory named `GeneratedCertificates`. +The root and intermediate certificates will automatically be shared between applications housed within the same solution, so that the applications will be able to trust each other. -In order to authorize incoming requests using an identity certificate, services need to be configured and activated, and policies need to be applied. +### Add and use Certificate Authentication -#### Adding and using services +> [!NOTE] +> This section is only required on applications that are receiving certificate-authorized requests. Several steps need to happen before certificate authorization policies can be used to secure resources: @@ -63,49 +69,48 @@ using Steeltoe.Security.Authorization.Certificate; // Register Microsoft's Certificate Authentication library builder.Services - .AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme) + .AddAuthentication() .AddCertificate(); // Register Microsoft authorization services builder.Services.AddAuthorizationBuilder() - // Register Steeltoe components and policies requiring space or org to match between client and server certificates + // Register Steeltoe components and policies requiring org and/or space to match between client and server certificates .AddOrgAndSpacePolicies(); ``` > [!TIP] > Steeltoe configures the certificate forwarding middleware to look for a certificate in the `X-Client-Cert` HTTP header. +> To change the HTTP header name used for authorization, include it when registering the policy. For example: `.AddOrgAndSpacePolicies("X-Custom-Certificate-Header")`. -To activate certificate-based authorization in the request pipeline, use the `IApplicationBuilder` extension method `UseCertificateAuthorization`: +Steeltoe exposes some of the policy-related components directly if more customized scenarios are required: ```csharp -WebApplication app = builder.Build(); +// AuthorizationPolicyBuilder setup +builder.Services.AddAuthorizationBuilder() + .AddOrgAndSpacePolicies() + .AddDefaultPolicy("sameOrgAndSpace", policy => policy.RequireSameOrg().RequireSameSpace()); -// Steeltoe: Use certificate and header forwarding along with ASP.NET Core Authentication and Authorization middleware -app.UseCertificateAuthorization(); +// Or the equivalent using different syntax +builder.Services.AddAuthorizationBuilder() + .AddOrgAndSpacePolicies() + .AddPolicy("sameOrgAndSpace", policy => policy.AddRequirements(new SameOrgRequirement(), new SameSpaceRequirement())); ``` -Steeltoe exposes some of the policy-related components directly if more customized scenarios are required: +To activate certificate-based authorization in the request pipeline, use the `UseCertificateAuthorization` extension method on `IApplicationBuilder`: ```csharp -// AuthorizationPolicyBuilder setup -builder.Services.AddAuthorizationBuilder().AddOrgAndSpacePolicies() - .AddDefaultPolicy("sameOrgAndSpace", authorizationPolicyBuilder => authorizationPolicyBuilder.RequireSameOrg().RequireSameSpace()); - -// Requirement classes are public -builder.Services.AddAuthorizationBuilder().AddOrgAndSpacePolicies() - .AddPolicy("sameOrgAndSpace", - authorizationPolicyBuilder => authorizationPolicyBuilder.AddRequirements([ - new SameOrgRequirement(), - new SameSpaceRequirement() - ])); +var app = builder.Build(); + +// Steeltoe: Use certificate and header forwarding along with ASP.NET Core Authentication and Authorization middleware +app.UseCertificateAuthorization(); ``` -> [!NOTE] -> These steps are only required on applications that are receiving certificate-authorized requests. +### Securing Endpoints -#### Applying Authorization Policies +> [!NOTE] +> This step is only required on applications that are receiving certificate-authorized requests. -As implied by the name of the extension method `AddOrgAndSpacePolicies` from the previous section on this page, Steeltoe provides policies for validating that a request came from an application in the same org or the same space. You can secure endpoints by using the standard ASP.NET Core `Authorize` attribute with one of these security policies. +As implied by the name of the extension method `AddOrgAndSpacePolicies` from the previous section on this page, Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints by using the standard ASP.NET Core `Authorize` attribute with these security policies. > [!TIP] > If needed, see the Microsoft documentation on [authorization in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/authorization/introduction) for a better understanding of how to use these attributes. @@ -113,10 +118,14 @@ As implied by the name of the extension method `AddOrgAndSpacePolicies` from the The following example shows a controller using the security attributes with the included policies: ```csharp +using Microsoft.AspNetCore.Authorization; +using Microsoft.AspNetCore.Mvc; +using Steeltoe.Security.Authorization.Certificate; + [Route("api")] public class HomeController : ControllerBase { - [Authorize(CertificateAuthorizationPolicies.SameOrganization)] + [Authorize(CertificateAuthorizationPolicies.SameOrg)] [HttpGet("[action]")] public string SameOrgCheck() { @@ -130,7 +139,8 @@ public class HomeController : ControllerBase return "Certificate is valid and both client and server are in the same space"; } - [Authorize("sameOrgAndSpace")] + [Authorize(CertificateAuthorizationPolicies.SameOrg)] + [Authorize(CertificateAuthorizationPolicies.SameSpace)] [HttpGet("[action]")] public string SameOrgAndSpaceCheck() { @@ -141,23 +151,26 @@ public class HomeController : ControllerBase In the preceding example, when an incoming request is made to the `SameOrgCheck` endpoint, the request is evaluated for the presence of a certificate. If a certificate is not present, the user is denied access. If a certificate is present, its subject is evaluated for the presence of an `org` value, which is then compared with the `org` value in the certificate found on disk where the service is deployed. If the values do not match, the user is denied access. The same process is applied for `SameSpaceCheck`, with the only difference being a check for the `space` value instead of the `org` value. -> [!NOTE] -> This step is only required on applications that are receiving certificate-authorized requests. - ### Communicating with Secured Services In order to use app instance identity certificates in a client application, services need to be configured, but nothing needs to be activated in the ASP.NET Core request pipeline. #### IHttpClientFactory integration -For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an `IHttpClientBuilder` extension method named `AddAppInstanceIdentityCertificate`. This method invokes code that handles loading certificates from paths defined in the application's configuration, monitors those file paths and their content for changes, and places the certificate in an HTTP header named `X-Client-Cert` on all outbound requests. +> [!NOTE] +> This step is only required on applications that are sending certificate-authorized requests. + +For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` named `AddAppInstanceIdentityCertificate`. +This method invokes code that handles loading certificates from paths defined in the application's configuration, monitors those file paths and their content for changes, and places the certificate in an HTTP header named `X-Client-Cert` on all outbound requests. > [!TIP] -> If needed, see the Microsoft documentation on [IHttpClientFactory documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests) +> If needed, see the Microsoft documentation on [IHttpClientFactory documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests) for details. ```csharp -builder.Services.AddHttpClient("AppInstanceIdentity").AddAppInstanceIdentityCertificate(); +using Steeltoe.Security.Authorization.Certificate; + +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddHttpClient().AddAppInstanceIdentityCertificate(); ``` -> [!NOTE] -> This step is only required on applications that are sending certificate-authorized requests. +This method has an overload that changes the name of the HTTP header used to pass the certificate. For example: `.AddAppInstanceIdentityCertificate("X-Custom-Certificate-Header")`. diff --git a/api/v4/security/index.md b/api/v4/security/index.md index b48331a4..32ba3f60 100644 --- a/api/v4/security/index.md +++ b/api/v4/security/index.md @@ -1,12 +1,12 @@ # Cloud Security -Steeltoe provides several libraries that simplify using Cloud Foundry-based security services (such as [UAA Server](https://github.com/cloudfoundry/uaa), [Single-Sign-on for VMware Tanzu](https://docs.vmware.com/en/Single-Sign-On-for-VMware-Tanzu-Application-Service/index.html) and [instance identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html)) for authentication and authorization. +Steeltoe provides several libraries that simplify using Cloud Foundry-based security services (such as [UAA Server](https://github.com/cloudfoundry/uaa), [Single Sign-On for VMware Tanzu](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/index.html) and [instance identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html)) for authentication and authorization. Choose from the following options when using Cloud Foundry security integration: * [Single Sign-on with OpenID Connect](sso-open-id.md) -* [Resource protection with JWT Bearer tokens](jwt-authentication.md) -* [Resource protection using Mutual TLS (Certificate Authorization)](mtls.md) +* [Resource protection with JWT Bearer tokens](jwt-bearer.md) +* [Resource protection using Mutual TLS (Certificate Authorization)](certificate.md) In addition to authentication and authorization providers, Steeltoe security offers: diff --git a/api/v4/security/jwt-authentication.md b/api/v4/security/jwt-authentication.md deleted file mode 100644 index aa64eb4d..00000000 --- a/api/v4/security/jwt-authentication.md +++ /dev/null @@ -1,144 +0,0 @@ -# Resource Protection using JWT in ASP.NET Core - -This provider lets you control access to REST resources by using JSON Web Tokens (JWT) issued by Cloud Foundry Security services (such as [UAA Server](https://github.com/cloudfoundry/uaa) or [Single-Sign-on for VMware Tanzu](https://docs.vmware.com/en/Single-Sign-On-for-VMware-Tanzu-Application-Service/index.html)) in ASP.NET Core. - -The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/latest/Security/src/AuthClient/README.md) can help you understand how to use this tool. - -Many resources are available for understanding JWT (for example, see [JWT IO](https://jwt.io/) or [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token)). - -## Usage - -This library supplements ASP.NET Security. For the documentation from Microsoft, visit [ASP.NET Core Security](https://learn.microsoft.com/aspnet/core/security). - -This package uses JSON Web Tokens (JWT) and builds on JWT Security services provided by ASP.NET Core Security. You should take some time to understand both before proceeding to use this provider. - -Steps involved in using this library: - -1. Add NuGet reference(s) -1. Configure settings for the security provider -1. Add and use the security provider in the application -1. Secure your endpoints -1. Create an instance of a Cloud Foundry Single SignOn service and bind it to your application - -### Add NuGet Reference - -To use the provider, you need to add a reference to the `Steeltoe.Security.Authentication.JwtBearer` NuGet package. - -### Configure Settings - -Since Steeltoe's OpenID Connect library configures Microsoft's JWT Bearer implementation, all available settings can be found in [`Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions) - -`JwtBearerOptions` is bound to configuration values found under `Authentication:Schemes:Bearer`. The following example shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): - -```json -{ - "Authentication": { - "Schemes": { - "Bearer": { - "Audience": "steeltoesamplesclient" - } - } - } -} -``` - -#### Cloud Foundry Service Bindings - -The Steeltoe package `Steeltoe.Configuration.CloudFoundry.ServiceBinding` reads Single SignOn credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft's JwtBearer to read. Add the configuration provider to your application with this code: - -```csharp -WebApplicationBuilder builder = WebApplication.CreateBuilder(args); - -// Steeltoe: Add Cloud Foundry service info to configuration -builder.Configuration.AddCloudFoundryServiceBindings(); -``` - -#### Local UAA - -A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your application to work with a local UAA server is possible with settings like these: - -```json -{ - "Authentication": { - "Schemes": { - "Bearer": { - "Authority": "http://localhost:8080/uaa", - "ClientId": "steeltoesamplesserver", - "ClientSecret": "server_secret", - "MetadataAddress": "http://localhost:8080/.well-known/openid-configuration", - "RequireHttpsMetadata": false - } - } - } -} -``` - -#### Add and use JWT Bearer Authentication - -Since the majority of the JWT Bearer functionality is provided by Microsoft's libraries, the only difference when using Steeltoe will be the addition of calling `ConfigureOpenIdConnectForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: - -```csharp -using Steeltoe.Security.Authentication.CloudFoundry; - -// Add Microsoft Authentication services -builder.Services - .AddAuthentication(JwtBearerDefaults.AuthenticationScheme) - .AddJwtBearer() - // Steeltoe: configure JWT to work with UAA/Cloud Foundry - .ConfigureJwtBearerForCloudFoundry(); - -// Register Microsoft Authorization services -builder.Services.AddAuthorizationBuilder() - // Create a named authorization policy that requires the user to have a scope with the same value - // In the Steeltoe sample application, Globals.RequiredJwtScope = "sampleapi.read", - // which represents the user's permission to read from the sample API - .AddPolicy(Globals.RequiredJwtScope, policy => policy.RequireClaim("scope", Globals.RequiredJwtScope)) -``` - -Activate authentication and authorization services after routing services, but before controller route registrations, with the following code: - -```csharp -WebApplication app = builder.Build(); - -// Use forwarded headers so that links generate correctly behind a reverse proxy (eg: when in Cloud Foundry) -app.UseForwardedHeaders(new ForwardedHeadersOptions { ForwardedHeaders = ForwardedHeaders.XForwardedHost | ForwardedHeaders.XForwardedProto }); - -app.UseRouting(); - -app.UseAuthentication(); -app.UseAuthorization(); - -app.MapDefaultControllerRoute(); - -app.Run(); -``` - -> [!TIP] -> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. - -### Securing Endpoints - -Once the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: - -```csharp -using Microsoft.AspNetCore.Authentication; -... - -[Route("api/[controller]")] -public class ValuesController : Controller -{ - // GET api/values - [HttpGet] - [Authorize(Policy = Globals.RequiredJwtScope)] - public IEnumerable Get() - { - return new string[] { "value1", "value2" }; - } -} -``` - -In the preceding example, if an incoming REST request is made to the `api/values` endpoint and the request does not contain a valid JWT bearer token with a `scope` claim equal to `sampleapi.read`, the request is rejected. - -### Cloud Foundry Single SignOn Service - -There are two services available on Cloud Foundry. We recommend you read the official documentation ([UAA Server](https://github.com/cloudfoundry/uaa) and [Single-Sign-on for VMware Tanzu](https://docs.vmware.com/en/Single-Sign-On-for-VMware-Tanzu-Application-Service/index.html)) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/latest/Security/src/AuthClient/README.md) for more information. diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md new file mode 100644 index 00000000..3b2a512d --- /dev/null +++ b/api/v4/security/jwt-bearer.md @@ -0,0 +1,219 @@ +# Resource Protection using JWT in ASP.NET Core + +This library is a supplement to ASP.NET Core Security, adding functionality that helps you use Cloud Foundry Security services such as [Single Sign-On for VMware Tanzu](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/index.html) or a [UAA Server](https://github.com/cloudfoundry/uaa) for authentication and authorization using JSON Web Tokens (JWT) in ASP.NET Core web applications. + +The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) can help you understand how to use this tool. + +General guidance on JWT is beyond the scope of this document and can be found in many other sources (for example, see [Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token) or [JWT IO](https://jwt.io/)). + +For the documentation of the underlying Microsoft Jwt Bearer Authentication library, visit the [official documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-jwt-bearer-authentication). + +## Usage + +Steps involved in using this library: + +1. Add NuGet references. +1. Configure settings for the security provider. +1. Add and use the security provider in the application. +1. Secure your endpoints. +1. Create an instance of a Cloud Foundry Single Sign-On service and bind it to your application. + +### Add NuGet References + +To use the provider, you need to add a reference to the `Steeltoe.Security.Authentication.JwtBearer` NuGet package. + +Also add a reference to `Steeltoe.Configuration.CloudFoundry`, so that Cloud Foundry service bindings can be read by Steeltoe. + +### Configure Settings + +Since Steeltoe's JWT Bearer library configures Microsoft's JWT Bearer implementation, all available settings can be found in [`Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions). + +`JwtBearerOptions` is bound to configuration values found under `Authentication:Schemes:Bearer`. The following example `appsettings.json` shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): + +```json +{ + "Authentication": { + "Schemes": { + "Bearer": { + "ValidAudience": "sampleapi" + } + } + } +} +``` + +#### Cloud Foundry Service Bindings + +The Steeltoe package `Steeltoe.Configuration.CloudFoundry` reads Single Sign-On credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft's JWT Bearer library to read. Add the configuration provider to your application with this code: + +```csharp +using Steeltoe.Configuration.CloudFoundry; +using Steeltoe.Configuration.CloudFoundry.ServiceBindings; + +var builder = WebApplication.CreateBuilder(args); + +// Steeltoe: Add Cloud Foundry application and service info to configuration. +builder.AddCloudFoundryConfiguration(); +builder.Configuration.AddCloudFoundryServiceBindings(); +``` + +#### Local UAA + +A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: + +```json +{ + "Authentication": { + "Schemes": { + "Bearer": { + "Authority": "http://localhost:8080/uaa", + "ClientId": "steeltoesamplesserver", + "ClientSecret": "server_secret", + "MetadataAddress": "http://localhost:8080/.well-known/openid-configuration", + "RequireHttpsMetadata": false + } + } + } +} +``` + +> [!IMPORTANT] +> If you wish to use the Steeltoe UAA server without modification, some application configuration options will be limited. +> The Steeltoe UAA Server configuration can be found in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L111). + +### Add and use JWT Bearer Authentication + +Since the majority of the JWT Bearer functionality is provided by Microsoft's libraries, the only difference when using Steeltoe will be the addition of calling `ConfigureJwtBearerForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: + +```csharp +using Microsoft.AspNetCore.Authentication.JwtBearer; +using Steeltoe.Security.Authentication.JwtBearer; + +// Add Microsoft Authentication services +builder.Services + .AddAuthentication(JwtBearerDefaults.AuthenticationScheme) + .AddJwtBearer() + // Steeltoe: configure JWT to work with UAA/Cloud Foundry + .ConfigureJwtBearerForCloudFoundry(); + +// Register Microsoft Authorization services +builder.Services.AddAuthorizationBuilder() + // Create a named authorization policy that requires the user to have a scope with the same value + .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); +``` + +Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, with the following code: + +```csharp +var app = builder.Build(); + +app.UseForwardedHeaders(new ForwardedHeadersOptions { ForwardedHeaders = ForwardedHeaders.XForwardedHost | ForwardedHeaders.XForwardedProto }); + +app.UseRouting(); + +app.UseAuthentication(); +app.UseAuthorization(); + +app.MapDefaultControllerRoute(); + +app.Run(); +``` + +> [!TIP] +> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. + +### Securing Endpoints + +Once the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: + +```csharp +using Microsoft.AspNetCore.Authorization; +using Microsoft.AspNetCore.Mvc; + +[Route("api/[controller]")] +[ApiController] +public class SampleController : ControllerBase +{ + + [HttpGet] + [Authorize(Policy = "sampleapi.read")] + public string Get() + { + return "You have permission to read from the sample API."; + } +} +``` + +In the preceding example, if an incoming GET request is made to the `/api/sample` endpoint and the request does not contain a valid JWT bearer token for a user with a `scope` claim equal to `sampleapi.read`, the request is rejected. + +Review the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for a demonstration of using a user's access token to interact with downstream APIs, focusing on these locations: + +- [Configure ASP.NET Core to save the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/appsettings.json#L15) +- [Get the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/Controllers/HomeController.cs#L60) +- [Include the token in a downstream request](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/ApiClients/JwtAuthorizationApiClient.cs#L24) + +### Single Sign-On for VMware Tanzu + +When using Single Sign-On for VMware Tanzu, you will need to identify the service plan to be used before creating a service instance of that plan. +If you do not have an existing service plan, a platform operator may need to create a new plan for you. +The operator should refer to the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html) for information on how to configure plans for developer use. + +Once you have identified the service plan that will be used, create a service instance: + +```shell +cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE +``` + +#### Bind and configure with app manifest + +Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. Review the Single Sign-On documentation for [configuring an app manifest](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). + +Consider this example manifest that names the application, buildpack and configures several properties for the SSO binding: + +```yml +applications: +- name: steeltoesamplesserver + buildpacks: + - dotnet_core_buildpack + env: + GRANT_TYPE: client_credentials + SSO_AUTHORITIES: uaa.resource, sampleapi.read + SSO_RESOURCES: sampleapi.read + SSO_SHOW_ON_HOME_PAGE: "false" + services: + - sampleSSOService +``` + +#### Bind and configure manually + +Alternatively, you can manually bind the instance, restage the app with the Cloud Foundry CLI and later configure the SSO binding yourself with the web interface: + +```shell +# Bind service to your app +cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE + +# Restage the app to pick up change +cf restage MY_APPLICATION +``` + +For further information, refer to the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/latest/Security/src/AuthWeb/README.md). + +### UAA Server + +If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA as an alternative. + +There is no service broker available to manage service instances or bindings for UAA, so a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) must be used to hold the credentials. + +The following command is an example of how the binding could be created: + +```shell +cf cups MY_SERVICE_INSTANCE -p '{"auth_domain": "https://uaa.login.sys.cf-app.com","grant_types": [ "authorization_code", "client_credentials" ],"client_secret": "SOME_CLIENT_SECRET","client_id": "SOME_CLIENT_ID"}' +``` + +And the command below is an example of how to bind the service instance to the app: + +```shell +cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE +``` + +For additional information, refer to the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index c65c0167..c442e6cb 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -1,107 +1,119 @@ # Redis Key Storage Provider -By default, ASP.NET Core stores the key ring on the local file system. Local file system usage in a Cloud Foundry environment is unworkable and violates the [twelve-factor guidelines](https://12factor.net/) for developing cloud-native applications. By using the Steeltoe Redis key storage provider, you can reconfigure the data protection service to use Redis on Cloud Foundry for storage. +The Redis Key Storage Provider is commonly used when secured data needs to be shared between two or more instances of the same application. + +By default, the [data protection system in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/data-protection/introduction) stores cryptographic keys on the local file system. +Even when not used by the application directly, these cryptographic keys are used for systems like [session state](https://learn.microsoft.com/aspnet/core/fundamentals/app-state#session-state) storage. + +By using the Steeltoe Redis key storage provider, you can easily reconfigure the data protection service to store these keys in Redis instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). + +The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) can help you understand how and why to use this tool. ## Usage To use this provider: +1. Add NuGet reference(s). +1. Configure your connection string. +1. Initialize the Steeltoe Connector at startup. +1. Configure the data protection system to persist keys in the Redis database. +1. Add the Cloud Foundry configuration provider. 1. Create a Redis service instance and bind it to your application. -1. Add the Steeltoe Cloud Foundry configuration provider to your `ConfigurationBuilder`. -1. Add the Redis `ConnectionMultiplexer` to your `ServiceCollection`. -1. Add `DataProtection` to your `ServiceCollection` and configure it to `PersistKeysToRedis`. -### Add NuGet Reference +### Add NuGet References To use the provider, you need to add a reference to the `Steeltoe.Security.DataProtection.Redis` NuGet package. -You also need the Steeltoe Redis connector. Add the `Steeltoe.Connectors` package to get the Redis connector and helpers for setting it up. +If you are using Cloud Foundry service bindings, you will also need to add a reference to `Steeltoe.Configuration.CloudFoundry`. -### Cloud Foundry +### Configure connection string -To use the Redis data protection key ring provider on Cloud Foundry, you have to install a Redis service and create and bind an instance of it to your application by using the Cloud Foundry command line, as follows: +You must configure a connection string in order to use Redis. +The following example `appsettings.Development.json` uses a local Redis server listening on the default Redis port: -```bash -# Create Redis service -cf create-service p-redis shared-vm myRedisCache +```json +{ + "Steeltoe": { + "Client": { + "Redis": { + "Default": { + "ConnectionString": "localhost" + } + } + } + } +} +``` -# Bind service to `myApp` -cf bind-service myApp myRedisCache +### Initialize Steeltoe Connector -# Restage the app to pick up change -cf restage myApp +Update your `Program.cs` as below to initialize the Connector: + +```csharp +using Steeltoe.Connectors.Redis; + +var builder = WebApplication.CreateBuilder(args); +builder.AddRedis(); ``` -> [!NOTE] -> The preceding commands are for the Redis service provided by Tanzu Platform for Cloud Foundry. If you use a different service, you have to adjust the `create-service` command. +### Persist Keys to Redis -Once the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`. +There are several steps required to configure key storage in Redis: -### Add Redis IConnectionMultiplexer +- Add data protection (while the services are added automatically, this step is required in order to access the builder). +- Set the key persistence location to Redis. +- Set an application name so all instances of the application can see the same data. -The next step is to add the StackExchange Redis `IConnectionMultiplexer` to your service container. +These steps can be performed by chaining the method calls together: -You can do so in the `ConfigureServices()` method of the `Startup` class by using the Steeltoe Redis Connector, as follows: +```csharp +using Microsoft.AspNetCore.DataProtection; +using Steeltoe.Security.DataProtection.Redis; + +builder.Services.AddDataProtection().PersistKeysToRedis().SetApplicationName("redis-data-protection-sample"); +``` + +> [!NOTE] +> At this point, the keys used by the `DataProtection` framework are stored in the bound Redis service. +> No additional steps are _required_, but you can also [use data protection in your application](https://learn.microsoft.com/aspnet/core/security/data-protection/consumer-apis/overview). + +### Add Cloud Foundry Configuration + +The Steeltoe package `Steeltoe.Configuration.CloudFoundry` reads Redis credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and maps them into the application's configuration in a format that the Redis connector can read. +Add the configuration provider to your application with this code: ```csharp -using Steeltoe.Connector.Redis; - -public class Startup { - ... - public IConfiguration Configuration { get; private set; } - public Startup(IConfiguration configuration) - { - Configuration = configuration; - } - public void ConfigureServices(IServiceCollection services) - { - // Add StackExchange ConnectionMultiplexer configured from Cloud Foundry - services.AddRedisConnectionMultiplexer(Configuration); - - // Add framework services. - services.AddMvc(); - ... - } - ... -} +using Steeltoe.Configuration.CloudFoundry; + +var builder = WebApplication.CreateBuilder(args); +builder.AddCloudFoundryConfiguration(); ``` -See the documentation on the Steeltoe Redis connector for details on how you can configure additional settings to control its behavior. +### Cloud Foundry -### Add PersistKeysToRedis +To use the Redis data protection key ring provider on Cloud Foundry, [use a supported Redis service](../connectors/redis.md#cloud-foundry) to create and bind an instance of Redis to your application. -The last step is to use the provider to configure data protection to persist keys to Redis. +You can complete these steps using the Cloud Foundry command line, as follows: -You can do so in the `ConfigureServices()` method of the `Startup` class: +```bash +# Push your app +cf push sampleApp --buildpack dotnet_core_buildpack -```csharp -using Steeltoe.Connector.Redis; - -public class Startup { - ... - public IConfiguration Configuration { get; private set; } - public Startup(IConfiguration configuration) - { - Configuration = configuration; - } - public void ConfigureServices(IServiceCollection services) - { - // Add StackExchange ConnectionMultiplexer configured from Cloud Foundry - services.AddRedisConnectionMultiplexer(Configuration); - - // Add DataProtection and persist keys to Cloud Foundry Redis service - services.AddDataProtection() - .PersistKeysToRedis() - .SetApplicationName("Some Name"); - - // Add framework services. - services.AddMvc(); - ... - } - ... -} +# Create Redis service +cf create-service p-redis shared-vm sampleRedisService + +# Bind service to your app +cf bind-service sampleApp sampleRedisService + +# Restage the app to pick up change +cf restage sampleApp ``` -### Use Redis Key Store +> [!NOTE] +> The preceding commands are for the Redis service provided by Tanzu Platform for Cloud Foundry. +> If you use a different service, you have to adjust the `create-service` command. + +Once the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`. -Once the Redis Key Store has been set up, the keys used by the `DataProtection` framework are stored in the bound Redis Cloud Foundry service. You need not do more. +> [!TIP] +> Explore the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) for a demonstration on why this provider is useful. diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index 2dbba213..a8970d80 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -1,30 +1,35 @@ -# Single Sign-on with OpenID Connect +# Single Sign-On with OpenID Connect -Single Sign-on with OpenID Connect helps you use a [UAA Server](https://github.com/cloudfoundry/uaa) or [Single-Sign-on for VMware Tanzu](https://docs.vmware.com/en/Single-Sign-On-for-VMware-Tanzu-Application-Service/index.html) for authentication and authorization in ASP.NET Core applications. +OpenID Connect is commonly used when users should be able to interact with a collection of applications using a single set of credentials for authentication and authorization. -## Usage +This library is a supplement to ASP.NET Core Security's OpenID Connect library (`Microsoft.AspNetCore.Authentication.OpenIdConnect`), adding functionality that helps you use Cloud Foundry Security services such as [Single Sign-On for VMware Tanzu](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/index.html) or [User Account and Authentication (UAA) Server](https://github.com/cloudfoundry/uaa). + +General guidance on OpenID Connect is beyond the scope of this document and can be found in many other sources (for example, see [OpenID](https://openid.net/developers/how-connect-works/)). +For the documentation of the underlying Microsoft OpenID Connect library, visit the [official documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-oidc-web-authentication). -This library supplements ASP.NET Security. For the documentation from Microsoft, visit [ASP.NET Core Security](https://learn.microsoft.com/aspnet/core/security). +The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) can help you understand how to use this library. + +## Usage Steps involved in using this library: -1. Add NuGet reference(s) -1. Configure settings for the security provider -1. Add and use the security provider in the application -1. Secure your endpoints -1. Create an instance of a Cloud Foundry Single SignOn service and bind it to your application +1. Add NuGet references. +1. Configure settings for the security provider. +1. Add and use the security provider in the application. +1. Secure your endpoints. +1. Create an instance of a Cloud Foundry Single Sign-On service and bind it to your application. -### Add NuGet Reference +### Add NuGet References To use this package, you will need to add a reference to the NuGet package `Steeltoe.Security.Authentication.OpenIdConnect`. -If you are using Cloud Foundry service bindings, you will also need to add a reference to `Steeltoe.Configuration.CloudFoundry.ServiceBinding`. +Also add a reference to `Steeltoe.Configuration.CloudFoundry`, so that Cloud Foundry service bindings can be read by Steeltoe. ### Configure Settings Since Steeltoe's OpenID Connect library configures Microsoft's OpenID Connect implementation, all available settings can be found in [`Microsoft.AspNetCore.Authentication.OpenIdConnect.OpenIdConnectOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions) -`OpenIdConnectOptions` is bound to configuration values found under `Authentication:Schemes:OpenIdConnect`. The following example shows how to declare a list of permissions that should be requested for users: +`OpenIdConnectOptions` is bound to configuration values found under `Authentication:Schemes:OpenIdConnect`. The following example `appsettings.json` shows how to declare a list of permissions that should be requested for users: ```json { @@ -41,18 +46,22 @@ Since Steeltoe's OpenID Connect library configures Microsoft's OpenID Connect im #### Cloud Foundry Service Bindings -The Steeltoe package `Steeltoe.Configuration.CloudFoundry.ServiceBinding` reads Single SignOn credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft's OpenID Connect to read. Add the configuration provider to your application with this code: +The Steeltoe package `Steeltoe.Configuration.CloudFoundry` reads Single Sign-On credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft's OpenID Connect to read. Add the configuration provider to your application with this code: ```csharp -WebApplicationBuilder builder = WebApplication.CreateBuilder(args); +using Steeltoe.Configuration.CloudFoundry; +using Steeltoe.Configuration.CloudFoundry.ServiceBindings; + +var builder = WebApplication.CreateBuilder(args); -// Steeltoe: Add Cloud Foundry service info to configuration +// Steeltoe: Add Cloud Foundry application and service info to configuration. +builder.AddCloudFoundryConfiguration(); builder.Configuration.AddCloudFoundryServiceBindings(); ``` #### Local UAA -A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your application to work with a local UAA server is possible with settings like these: +A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)) can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: ```json { @@ -70,11 +79,20 @@ A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/Steel } ``` +> [!IMPORTANT] +> If you wish to use the Steeltoe UAA server without modification, some application configuration options will be very limited. +> Because the OpenID Connect authentication flow requires user redirection to known locations, the client `steeltoesamplesclient` is expected to listen at , so you will need to update launchSettings.json accordingly. +> The Steeltoe UAA Server configuration can be found in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L116). + ### Add and use OpenID Connect Since the majority of the OpenID Connect functionality is provided by Microsoft's libraries, the only difference when using Steeltoe will be the addition of calling `ConfigureOpenIdConnectForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: ```csharp +using Microsoft.AspNetCore.Authentication.Cookies; +using Microsoft.AspNetCore.Authentication.OpenIdConnect; +using Steeltoe.Security.Authentication.OpenIdConnect; + // Add Microsoft Authentication services builder.Services .AddAuthentication(options => @@ -93,17 +111,17 @@ builder.Services // Register Microsoft Authorization services builder.Services.AddAuthorizationBuilder() // Create a named authorization policy that requires the user to have a scope with the same value - // In the Steeltoe sample application, Globals.RequiredJwtScope = "sampleapi.read", // which represents the user's permission to read from the sample API - .AddPolicy(Globals.RequiredJwtScope, policy => policy.RequireClaim("scope", Globals.RequiredJwtScope)) + .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); ``` -Direct ASP.NET Core to activate authentication and authorization services after routing services, but before controller route registrations, with the following code: +Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, with the following code: ```csharp -WebApplication app = builder.Build(); +using Microsoft.AspNetCore.HttpOverrides; + +var app = builder.Build(); -// Use forwarded headers so that links generate correctly behind a reverse proxy (eg: when in Cloud Foundry) app.UseForwardedHeaders(new ForwardedHeadersOptions { ForwardedHeaders = ForwardedHeaders.XForwardedHost | ForwardedHeaders.XForwardedProto }); app.UseRouting(); @@ -124,36 +142,99 @@ app.Run(); Once the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: ```csharp -using Microsoft.AspNetCore.Authentication; +using Microsoft.AspNetCore.Authorization; +using Microsoft.AspNetCore.Mvc; public class HomeController : Controller { - public IActionResult Index() - { - return View(); - } - [Authorize] - public IActionResult About() + public IActionResult Privacy() { - ViewData["Message"] = "Your About page."; return View(); } - [Authorize(Policy = Globals.RequiredJwtScope)] - public IActionResult TestGroup() + [Authorize(Policy = "sampleapi.read")] + public string TestGroup() { - ViewData["Message"] = $"You have the '{Globals.RequiredJwtScope}' permission."; - return View(); + return "You have the 'sampleapi.read' permission."; } } ``` The preceding example establishes the following security rules: -* If a user attempts to access the `About` action and the user is not authenticated, the user is redirected to the OAuth server (such as a UAA Server) to log in. +* If a user attempts to access the `Privacy` action and the user is not authenticated, the user is redirected to the OAuth server (such as a UAA Server) to log in. * If an authenticated user attempts to access the `TestGroup` action but does not meet the restrictions established by the referenced policy, the user is denied access. -### Cloud Foundry Single SignOn Service +> [!TIP] +> The Steeltoe UAA server has several pre-provisioned user accounts. Sign in with `testuser` and password `password` to access resources secured with `sampleapi.read` +> To test with a user that does not have the permission `sampleapi.read`, sign in with the user `customer` and password `password`. +> +> You may want to explore the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples of additional basic functionality such as signing out of the application. + +### Single Sign-On for VMware Tanzu + +When using Single Sign-On for VMware Tanzu, you will need to identify the service plan to be used before creating a service instance of that plan. +If you do not have an existing service plan, a platform operator may need to create a new plan for you. +The operator should refer to the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html) for information on how to configure plans for developer use. + +Once you have identified the service plan that will be used, create a service instance: + +```shell +cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE +``` + +#### Bind and configure with app manifest + +Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. Review the Single Sign-On documentation for [configuring an app manifest](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). + +Consider this example manifest that names the application, buildpack and configures several properties for the SSO binding: + +```yml +applications: +- name: steeltoesamplesclient + buildpacks: + - dotnet_core_buildpack + env: + GRANT_TYPE: authorization_code, client_credentials + SSO_AUTHORITIES: uaa.resource, sampleapi.read + SSO_IDENTITY_PROVIDERS: steeltoe-uaa + SSO_SCOPES: openid, profile, sampleapi.read + SSO_SHOW_ON_HOME_PAGE: "true" + services: + - sampleSSOService +``` + +#### Bind and configure manually + +Alternatively, you can manually bind the instance, restage the app with the Cloud Foundry CLI and later configure the SSO binding yourself with the web interface: + +```shell +# Bind service to your app +cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE + +# Restage the app to pick up change +cf restage MY_APPLICATION +``` + +For further information, such as instructions on using the web interface, refer to the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). + +### UAA Server + +If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA as an alternative. + +There is no service broker available to manage service instances or bindings for UAA, so a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) should be used to hold the credentials. + +This command is an example of how the binding could be created: + +```shell +cf cups MY_SERVICE_INSTANCE -p '{"auth_domain": "https://uaa.login.sys.cf-app.com","grant_types": [ "authorization_code", "client_credentials" ],"client_secret": "SOME_CLIENT_SECRET","client_id": "SOME_CLIENT_ID"}' +``` + +And this command is an example of how to bind the service instance to the app: + +```shell +cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE +``` -There are two services available on Cloud Foundry. We recommend you read the official documentation ([UAA Server](https://github.com/cloudfoundry/uaa) and [Single-Sign-on for VMware Tanzu](https://docs.vmware.com/en/Single-Sign-On-for-VMware-Tanzu-Application-Service/index.html)) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/latest/Security/src/AuthClient/README.md) for more information. +For additional information, refer to the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). diff --git a/api/v4/toc.yml b/api/v4/toc.yml index 4632e6d4..dc5e8416 100644 --- a/api/v4/toc.yml +++ b/api/v4/toc.yml @@ -43,9 +43,6 @@ name: Spring Boot Provider - name: Distributed Tracing topicHref: tracing/ - items: - - topicHref: tracing/distributed-tracing-exporting.md - name: Using Trace Exporters - name: Dynamic Logging topicHref: logging/ items: @@ -77,8 +74,6 @@ name: Loggers - topicHref: management/mappings.md name: Route Mappings - - topicHref: management/metrics-endpoint.md - name: Metrics - topicHref: management/prometheus.md name: Prometheus - topicHref: management/refresh.md @@ -89,8 +84,6 @@ name: Thread Dump - topicHref: management/tasks.md name: Tasks - - topicHref: management/metrics.md - name: Metrics - topicHref: management/springbootadmin.md name: Spring Boot Admin Client - topicHref: management/cloud-foundry.md @@ -105,10 +98,10 @@ items: - topicHref: security/sso-open-id.md name: SSO with Open ID Connect - - topicHref: security/jwt-authentication.md - name: JWT for ASP.NET Core - - topicHref: security/mtls.md - name: Mutual TLS + - topicHref: security/jwt-bearer.md + name: JWT Bearer Token + - topicHref: security/certificate.md + name: Certificate (Mutual TLS) - topicHref: security/redis-key-storage-provider.md name: Redis Key Storage Provider - name: Connectors diff --git a/api/v4/tracing/distributed-tracing-exporting.md b/api/v4/tracing/distributed-tracing-exporting.md deleted file mode 100644 index 1ec6638e..00000000 --- a/api/v4/tracing/distributed-tracing-exporting.md +++ /dev/null @@ -1,115 +0,0 @@ -# Exporting Distributed Traces - -Steeltoe is able to automatically configure several exporters provided by the [OpenTelemetry](https://opentelemetry.io) project, including [Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Zipkin), [Jaeger](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Jaeger) and [OpenTelemetryProtocol](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol), if a NuGet reference to the desired exporter is included. In addition, Steeltoe supports exporting traces to [Tanzu Observability](https://www.broadcom.com/products/software/aiops-observability/tanzu-observability) without any other NuGet references. - -## Common Settings - -As of version 3.1.0, the exporter settings class has been merged with [tracing settings](./index.md#configure-settings). -The table below includes settings that are only relevant to exporting traces. -Each key must be prefixed with `Management:Tracing`. - -| Key | Description | Default | -| --- | --- | --- | -| `ExporterEndpoint` | Defines an endpoint traces should be sent to. | not set | -| `MaxPayloadSizeInBytes` | Maximum payload size to export, in bytes. | 4096 | -| `UseShortTraceIds` | Whether to truncate the IDs to 8 bytes instead of 16. Used for backward compatibility. | `false` | - -## Zipkin Server - -Zipkin is a popular distributed tracing system that has been around for several years. It is composed of client libraries for instrumenting application code and a backend server for collecting and viewing the collected data. For more information on Zipkin, we encourage you to review the [documentation](https://zipkin.io/). See the [Quickstart](https://zipkin.io/pages/quickstart) guide for details on how to set up a server. - -### Configure Zipkin Options - -In addition to the [common exporter settings](#common-settings), you may configure ExportProcessorType and BatchExportProcessorOptions in code: - -```csharp -services.PostConfigure(options => -{ - options.ExportProcessorType = ExportProcessorType.Batch; - options.BatchExportProcessorOptions.ExporterTimeoutMilliseconds = 1000; -}); -``` - -### Use Zipkin Exporter - -Steeltoe will discover and automatically configure the Zipkin exporter when a standard NuGet reference is used: - -```xml - -``` - -## Jaeger Server - -Jaeger is another popular distributed tracing system that has been around for several years. For more information on Jaeger, we encourage you to visit the [Jaeger site](https://www.jaegertracing.io/). See the [Getting Started](https://www.jaegertracing.io/docs/1.24/getting-started/) guide for details on how to quickly set up a server. - -### Configure Jaeger Options - -In addition to the [common exporter settings](#common-settings), you may configure ExportProcessorType and BatchExportProcessorOptions in code: - -```csharp -services.PostConfigure(options => -{ - options.ExportProcessorType = ExportProcessorType.Batch; - options.BatchExportProcessorOptions.ExporterTimeoutMilliseconds = 1000; -}); -``` - -### Use Jaeger Exporter - -Steeltoe will discover and automatically configure the Jaeger exporter when a standard NuGet reference is used: - -```xml - -``` - -## Open Telemetry Protocol - -The OTLP (OpenTelemetry Protocol) is a vendor-agnostic way to export traces. Steeltoe will configure [this exporter](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol) to communicate to an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) through a gRPC protocol. - -### Configure Open Telemetry Protocol Options - -In addition to the [common exporter settings](#common-settings), you may configure Headers, ExportProcessorType, and BatchExportProcessorOptions in code: - -```csharp -services.PostConfigure(options => -{ - options.ExportProcessorType = ExportProcessorType.Batch; - options.BatchExportProcessorOptions.ExporterTimeoutMilliseconds = 1000; -}); -``` - -### Use Open Telemetry Protocol Exporter - -Steeltoe will discover and automatically configure the Open Telemetry Protocol exporter when a standard NuGet reference is used: - -```xml - -``` - -## Tanzu Observability by Wavefront - -[Tanzu Observability](https://docs.wavefront.com/wavefront_introduction.html) is an observability platform for distributed applications that can ingest metric & trace data. A free trial is available [here](https://tanzu.vmware.com/observability-trial) to try it. - -### Use Wavefront Exporter (Tanzu Observability) - -Steeltoe will automatically send traces to Wavefront if the following settings are provided. Note that these are shared between tracing and metrics and the Wavefront Trace exporter is activated by the presence of a valid `Uri` and `ApiToken` combination. -Each key must be prefixed with `Management:Metrics:Export:Wavefront`. - -| Key | Description | Default | -| --- | --- | --- | -| `ApiToken` | Your Tanzu Observability [API Token](https://docs.wavefront.com/users_account_managing.html#generate-an-api-token) | not set | -| `Uri` | The Uri of your Wavefront Instance | not set | -| `Step` | The interval between reporting to Wavefront | 30000 | -| `BatchSize` | The max batch of data sent per flush interval | 10000 | -| `MaxQueueSize` | the size of the internal buffer beyond which data is dropped | 500000 - -If using a proxy, the `ApiToken` is not needed and the `Uri` would be `proxy://:` - -In addition, the following settings can be used to set the application and service names. -Each key must be prefixed with `Wavefront:Application`. - -| Key | Description | Default | -| --- | --- | --- | -| `Source`| Unique identifier for the app instance that is publishing metrics to Wavefront | DNS name -| `Name` | Name of the application | SteeltoeApp | -| `Service` | Name of the service | SteeltoeService | diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index 7d75ae9c..dd9535b8 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -1,128 +1,253 @@ # Distributed Tracing -Steeltoe distributed tracing implements a solution for .NET applications using the open-source [OpenTelemetry](https://opentelemetry.io/) project. For most users, implementing and using distributed tracing should be invisible, and many of the interactions with external systems should be instrumented automatically. You can capture trace data in logs or by sending it to a remote collector service. +On the subject of distributed tracing for .NET applications, previous versions of Steeltoe offered either an implementation of OpenCensus or shortcuts for enabling distributed tracing with [OpenTelemetry](https://opentelemetry.io/) to integrate with the Tanzu platform. We painted ourselves into a corner with Steeltoe 3, which has a strong dependency on OpenTelemetry packages. New versions of OpenTelemetry contained breaking changes, which we couldn't adapt to without resorting to reflection. While we do that in other places, reflection is slow, and instrumentation is performance-sensitive. -A "span" is the basic unit of work. For example, sending an RPC is a new span, as is sending a response to an RPC. Spans are identified by a unique 64-bit ID for the span and by another 64-bit ID for the trace of which the span is a part. Spans also have other data, such as descriptions, key-value annotations, the ID of the span that caused them, and process IDs (normally an IP address). Spans are started and stopped, and they keep track of their timing information. Once you create a span, you must stop it at some point in the future. A set of spans form a tree-like structure called a "trace". For example, if you run a distributed big-data store, a trace might be formed by a PUT request. +By now, OpenTelemetry has evolved to the point that only a few lines of code are needed. So instead of providing a Steeltoe component, the guidance below is offered to accomplish the same. The benefit of that is greater flexibility: when OpenTelemetry changes, there's no need to wait for a new Steeltoe version first. -Steeltoe distributed tracing: +Steeltoe continues to directly offer an option for [log correlation](#log-correlation). This page also provides direction for developers looking to achieve the same outcomes Steeltoe has previously provided more directly. -* Adds trace and span IDs to the application log messages, so you can extract all the logs from a given trace or span in a log aggregator. -* Using the [OpenTelemetry](https://opentelemetry.io/) APIs, provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations, and key-value annotations. -* Automatically configures instrumentations of common ingress and egress points from .NET applications (such as ASP.NET Core and HTTP client). -* Automatically configures trace exporters (when a relevant NuGet reference is included). +## Introduction -## Usage +As the name implies, distributed tracing is a way of tracing requests through distributed systems. +Distributed tracing is typically accomplished by instrumenting components of the system to recognize and pass along metadata that is specific to a particular action or user request, and using another backend system to reconstruct the flow of the request through that metadata. -You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use the management endpoints. -You need at least a basic understanding of the `ConfigurationBuilder` and how to add providers to the builder to configure the endpoints. +In the parlance of distributed tracing, a "span" is the basic unit of work. For example, sending an HTTP request creates a new span, as does sending a response. +Spans are identified by a unique ID and contain the ID for the "trace" it is part of. +Spans also have other data like descriptions, key-value annotations, the ID of the span that initiated the execution flow, and process IDs. +Spans are started and stopped, and they keep track of their timing information. Once you create a span, you must stop it at some point in the future. +A set of spans form a tree-like structure called a "trace". For example, a trace might be formed by a POST request that adds an item to a shopping cart, which results in calling several backend services. -Steeltoe distributed tracing automatically applies instrumentation at key ingress and egress points in your ASP.NET Core application so that you are able to get meaningful traces without having to do any instrumentation yourself. These points include: +## Log correlation -* HTTP Server - * Request Start & Finish - * Unhandled and Handled exceptions -* HTTP Client - * Outgoing Request Start & Finish - * Unhandled and Handled exceptions +Log correlation is all about taking log entries from disparate systems and bringing them together using some matching criteria (such as a distributed trace ID). +The process can be easier when important pieces of data are logged in the same format across different systems (such as .NET and Java apps communicating with each other). -### Add NuGet References +Steeltoe provides the class `TracingLogProcessor`, which is an `IDynamicMessageProcessor` for correlating logs. The processor is built for use with a [Steeltoe Dynamic Logging provider](../logging/index.md). +It enriches log entries with correlation data using the same trace format popularized by [Spring Cloud Sleuth](https://cloud.spring.io/spring-cloud-sleuth/reference/html/#log-correlation), +that include `[,,,,]`. -To use the distributed tracing exporters, you need to add a reference to the `Steeltoe.Management.Tracing` NuGet package. +Consider this pair of log entries from the [Steeltoe Management sample applications](https://github.com/SteeltoeOSS/Samples/blob/main/Management/src/): -### Configure Settings +```text +info: System.Net.Http.HttpClient.ActuatorApiClient.LogicalHandler[100] + [ActuatorWeb,44ed2fe24a051bda2d1a56815448e9fb,8d51b985e3f0fd81,0000000000000000,true] Start processing HTTP request GET http://localhost:5140/weatherForecast?fromDate=2024-12-19&days=1 -You can configure distributed tracing by using the normal [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration). +dbug: Microsoft.EntityFrameworkCore.Database.Command[20104] + [ActuatorApi,44ed2fe24a051bda2d1a56815448e9fb,c32846ff227bed40,f315823f4c554816,true] Created DbCommand for 'ExecuteReader' (1ms). +``` -All settings should be placed under the prefix with a key of `Management:Tracing:`. -The following table describes the available settings: +Log correlation is easiest with a tool such as [Splunk](https://www.splunk.com/en_us/solutions/isolate-cloud-native-problems.html), [SumoLogic](https://www.sumologic.com/lp/log-analytics/) or [DataDog](https://www.datadoghq.com/dg/enterprise/log-management-analytics-security) (this is not an endorsement of any tool, only a pointer to some popular options). -| Key | Description | Default | -| --- | --- | --- | -| `Name` | The name of the application. | `Spring:Application:Name`, Cloud Foundry name, or `Unknown` | -| `IngressIgnorePattern` | Regex pattern describing what incoming requests to ignore. | See `TracingOptions` | -| `EgressIgnorePattern` | Regex pattern describing what outgoing requests to ignore. | See `TracingOptions` | -| `MaxPayloadSizeInBytes` | Maximum payload size to export, in bytes. | 4096 | -| `AlwaysSample` | Whether to enable the OpenTelemetry `AlwaysOnSampler`. | OpenTelemetry `Sampler` | -| `NeverSample` | Whether to enable the OpenTelemetry `AlwaysOffSampler`. | OpenTelemetry `Sampler` | -| `UseShortTraceIds` | Whether to truncate the IDs to 8 bytes instead of 16. Use it for backwards compatibility with Spring Sleuth, PCF Metrics, and others. | `false` | -| `PropagationType` | Propagation format that should be used. `B3` and `W3C` are supported. | `B3` | -| `SingleB3Header` | Defines whether B3 information is sent in one or multiple headers. | `true` | -| `EnableGrpcAspNetCoreSupport` | Defines if GRPC requests should participate in tracing. | `true` | -| `ExporterEndpoint` | Defines an endpoint traces should be sent to. | not set | +### Using TracingLogProcessor -### Enabling Log Correlation +To use the processor, first add a reference to the `Steeltoe.Management.Tracing` NuGet package. -To use distributed tracing together with log correlation, you can use a [Steeltoe Dynamic Logging provider](../logging/index.md) in your application. +The only remaining step is to register the processor: -Once that is done, whenever your application issues any log statements, the Steeltoe logger adds additional trace information to each log message if there is an active trace context. The format of that information is of the form `[app name, trace id, span id, trace flags]` (for example, `[service1,2485ec27856c56f4,2485ec27856c56f4,true]`). +```csharp +using Steeltoe.Management.Tracing; -### Propagating Trace Context +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddTracingLogProcessor(); +``` + +> [!NOTE] +> This extension method also ensures that implementations of `IApplicationInstanceInfo` and `IDynamicLoggerProvider` have been registered. +> If you wish to customize either of those or use non-default implementations, do so before calling `AddTracingLogProcessor`. + +## OpenTelemetry + +To use OpenTelemetry, start by adding a reference to the `OpenTelemetry.Extensions.Hosting` NuGet package. +Other package references will likely be necessary, but depend on your specific application needs. +This package provides access to `OpenTelemetryBuilder`, which is the main entrypoint to OpenTelemetry. + +### Add Open Telemetry Tracing + +```csharp +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddOpenTelemetry().WithTracing(); +``` + +> [!NOTE] +> At this point, not much has changed for the application - you will need changes to this line to add [instrumentation](#instrumenting-applications) and [exporting of traces](#exporting-distributed-traces). -When working with distributed tracing systems, you will find that a trace context (for example, trace state information) must get propagated to all child processes to ensure that child spans originating from a root trace get collected and correlated into a single trace in the end. The current trace and span IDs are just one piece of the required information that must be propagated. +### Sampler configuration -Steeltoe makes this easy by automatically configuring some of the instrumentation packages provided by Open Telemetry. +OpenTelemetry Provides the `Sampler` abstraction for configuring when traces should be recorded. +The simplest options are `AlwaysOnSampler` and `AlwaysOffSampler`, with their names describing exactly which traces will be recorded. -* Tracing configures [instrumentation on outbound requests](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.Http/README.md) and [instrumentation on inbound requests through ASP.NET Core and Grpc.AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore/README.md) -* Additional instrumentation libraries can be added with the [`Action` parameter](#adding-to-tracerproviderbuilder) +As a replacement for what Steeltoe used to provide for using these samplers, set the environment variable `OTEL_TRACES_SAMPLER` to `always_on` or `always_off`. -Steeltoe currently uses [Zipkin B3 Propagation](https://github.com/openzipkin/b3-propagation) by default, but can be configured to use [W3C trace context](https://www.w3.org/TR/trace-context/). As a result, you will find that Steeltoe tracing is interoperable with several other instrumentation libraries, such as [Spring Cloud Sleuth](https://spring.io/projects/spring-cloud-sleuth). +> [!TIP] +> OpenTelemetry is generally built to follow the [options pattern](https://learn.microsoft.com/dotnet/core/extensions/options). +> There are more ways to configure options than demonstrated on this page, these are just examples to get started. -### Add Distributed Tracing +### Set Application Name -To enable distributed tracing, add the service to the container. To do so, use either `AddDistributedTracing()` or `AddDistributedTracingAspNetCore()` from `TracingServiceCollectionExtensions`: +In order to use the Steeltoe name for your application with OpenTelemetry, call `SetResourceBuilder` and pass in a value from the registered `IApplicationInstanceInfo`: ```csharp -var host = Host.CreateDefaultBuilder(args) - .ConfigureServices(services => - { - // services.AddDistributedTracing(); - // or - services.AddDistributedTracingAspNetCore(); - }) +using OpenTelemetry.Resources; +using OpenTelemetry.Trace; +using Steeltoe.Common; + +builder.Services.ConfigureOpenTelemetryTracerProvider((serviceProvider, tracerProviderBuilder) => +{ + var appInfo = serviceProvider.GetRequiredService(); + tracerProviderBuilder.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(appInfo.ApplicationName!)); +}); ``` -`AddDistributedTracing()` is included in `Steeltoe.Management.Tracing`, configures OpenTelemetry, `HttpClient` instrumentation and [exporters](./distributed-tracing-exporting.md). -`AddDistributedTracingAspNetCore()` is included in `Steeltoe.Management.Tracing`, and calls `AddDistributedTracing()` with the addition of `ASP.NET Core` and `Grpc.AspNetCore` instrumentation. +The above example assumes you are already using some other Steeltoe component which adds `IApplicationInstanceInfo` to the IoC container. If that is not the case, there are two steps to take to register the default implementation: + +1. Add a NuGet package reference to `Steeltoe.Common` +1. Call `AddApplicationInstanceInfo` + +```csharp +using Steeltoe.Common.Extensions; + +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddApplicationInstanceInfo(); +``` -### Code-based Instrumentation Configuration +### Instrumenting applications -Some of the options for HttpClient and ASP.NET Core instrumentation must be configured in code. These can be accessed using IOptions configuration methods like [`PostConfigure`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.optionsservicecollectionextensions.postconfigure): +In order to maximize the benefit of collecting distributed traces, you'll want participation from the core components and frameworks of your application and some 3rd party components. +Some packages in the .NET ecosystem automatically support OpenTelemetry, others can be supported by the [collection of instrumentation libraries](https://opentelemetry.io/ecosystem/registry/?language=dotnet&component=instrumentation). +Steeltoe previously configured the instrumentation libraries for [HttpClient](#httpclient) and [ASP.NET Core](#aspnet-core). + +#### ASP.NET Core + +To instrument requests coming into the application through ASP.NET Core, start by adding a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. + +Next, add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: + +```csharp +using OpenTelemetry.Trace; + +builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddAspNetCoreInstrumentation()); +``` + +In order to replicate the Steeltoe setting `IngressIgnorePattern` (a Regex pattern describing which incoming requests to ignore), configure the `AspNetCoreTraceInstrumentationOptions`: ```csharp -services.PostConfigure(options => +using System.Text.RegularExpressions; +using OpenTelemetry.Instrumentation.AspNetCore; + +builder.Services.Configure(options => { - options.Enrich = (activity, eventName, rawObject) => - { - if (eventName.Equals("OnStartActivity")) - { - if (rawObject is HttpRequest httpRequest) - { - activity.SetTag("requestProtocol", httpRequest.Protocol); - } - } - }; + const string defaultIngressIgnorePattern = @"/actuator/.*|/cloudfoundryapplication/.*|.*\.png|.*\.css|.*\.js|.*\.html|/favicon.ico|.*\.gif"; + Regex ingressPathMatcher = new(defaultIngressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); + options.Filter += httpContext => !ingressPathMatcher.IsMatch(httpContext.Request.Path); }); ``` -### Adding to TracerProviderBuilder +As an alternative to using a regular expression, you can list out the paths to ignore in the Filter property (`Filter` is a `Func?`): -There are additional instrumentation libraries for OpenTelemetry, and other settings you may wish to configure that Steeltoe does directly address. For these cases, an `Action` is available. +```csharp +using OpenTelemetry.Instrumentation.AspNetCore; -For example, if you wanted to add SQL Server instrumentation and a custom sampler, your code could look like this: +builder.Services.Configure(options => +{ + options.Filter += httpContext => + !httpContext.Request.Path.StartsWithSegments("/actuator", StringComparison.OrdinalIgnoreCase) && + !httpContext.Request.Path.StartsWithSegments("/cloudfoundryapplication", StringComparison.OrdinalIgnoreCase); +}); +``` + +> [!TIP] +> By default, the ASP.NET Core instrumentation does not filter out any requests. +> The latter approach above may quickly prove unwieldy if there are many patterns to ignore, such as when listing many file types. + +To learn more about ASP.NET Core instrumentation for OpenTelemetry see [the documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore). + +#### HttpClient + +To instrument requests leaving the application through `HttpClient`, start by adding a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. + +Next, add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: ```csharp -var host = Host.CreateDefaultBuilder(args) - .ConfigureServices(services => - { - services.AddDistributedTracingAspNetCore(trace => - { - trace - .SetSampler(new MyCustomSampler()) - .AddSqlClientInstrumentation(); - }); - }) +using OpenTelemetry.Trace; + +builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddHttpClientInstrumentation()); ``` -## Next Steps +In order to replicate the Steeltoe setting `EgressIgnorePattern` (a Regex pattern describing which outgoing HTTP requests to ignore), configure the `HttpClientTraceInstrumentationOptions`: + +```csharp +using OpenTelemetry.Instrumentation.Http; +using System.Text.RegularExpressions; + +builder.Services.Configure(options => +{ + const string defaultEgressIgnorePattern = "/api/v2/spans|/v2/apps/.*/permissions"; + Regex egressPathMatcher = new(defaultEgressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); + options.FilterHttpRequestMessage += httpRequestMessage => !egressPathMatcher.IsMatch(httpRequestMessage.RequestUri?.PathAndQuery ?? string.Empty); +}); +``` + +To learn more about HttpClient instrumentation for OpenTelemetry see [the documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http). + +### Propagating Trace Context + +By default, OpenTelemetry uses the [W3C trace context](https://github.com/w3c/trace-context) for propagating traces. +Some systems like Cloud Foundry may still be configured for the Zipkin standard of [B3 propagation](https://github.com/openzipkin/b3-propagation). + +In order to use B3 propagation, add a reference to the `OpenTelemetry.Extensions.Propagators` NuGet package. + +Next, let the compiler know that the `B3Propagator` should come from the package reference you just added (rather than the deprecated class found in `OpenTelemetry.Context.Propagation`): + +```csharp +using B3Propagator = OpenTelemetry.Extensions.Propagators.B3Propagator; +``` + +Finally, register a `CompositeTextMapPropagator` that includes the `B3Propagator` and `BaggagePropagator`: + +```csharp +using OpenTelemetry; +using OpenTelemetry.Context.Propagation; +using OpenTelemetry.Trace; + +builder.Services.ConfigureOpenTelemetryTracerProvider((_, _) => +{ + List propagators = + [ + new B3Propagator(), + new BaggagePropagator() + ]; + + Sdk.SetDefaultTextMapPropagator(new CompositeTextMapPropagator(propagators)); +}); +``` + +### Exporting Distributed Traces + +Previous versions of Steeltoe could automatically configure several different trace exporters, including [Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Zipkin), [OpenTelemetryProtocol (OTLP)](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol) and Jaeger. +The Jaeger exporter has been deprecated in favor of OTLP, which was only minimally configured by Steeltoe and is better described by [the official OTLP exporter documentation](https://opentelemetry.io/docs/languages/net/exporters/#otlp). + +#### Zipkin Server + +To use the Zipkin Exporter, add a reference to the `OpenTelemetry.Exporter.Zipkin` NuGet package. + +Next, use the extension method `AddZipkinExporter` by updating the existing call from above to: + +```csharp +builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddZipkinExporter()); +``` + +The Zipkin options class `ZipkinExporterOptions` works nearly the same as Steeltoe settings with the same names in previous releases: + +```csharp +using OpenTelemetry.Exporter; + +builder.Services.Configure(options => +{ + options.Endpoint = new Uri("http://localhost:9411"); + options.MaxPayloadSizeInBytes = 4096; + options.UseShortTraceIds = true; +}); +``` -Once you've set up all the instrumentation, you'll want to [configure an exporter](./distributed-tracing-exporting.md). +> [!TIP] +> The Zipkin endpoint can also be set with the environment variable "OTEL_EXPORTER_ZIPKIN_ENDPOINT". From 2690da12fe917d23bdffccd900683b169a762e44 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Wed, 26 Feb 2025 12:46:41 -0800 Subject: [PATCH 06/43] full edit Application Config, Config Server --- .../configuration/config-server-provider.md | 169 +++++++++--------- api/v4/configuration/index.md | 10 +- 2 files changed, 93 insertions(+), 86 deletions(-) diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index b98c3d3a..53076482 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -2,7 +2,7 @@ This provider enables the Spring Cloud Config Server to be used as a source of configuration data for a .NET application. -The Spring Cloud Config Server is an application configuration service that gives you a central place to manage an application's configuration values externally across all environments. As an application moves through the deployment pipeline from development to test and into production, you can use the config server to manage the configuration between environments and be certain that the application has everything it needs to run when you migrate it. The config server easily supports labeled versions of environment-specific configurations and is accessible to a wide range of tooling for managing its content. +The Spring Cloud Config Server is an application configuration service that gives you a central place to manage an application's configuration values externally across all environments. As an application moves through the deployment pipeline from development to test and into production, you can use the Config Server to manage the configuration between environments and be certain that the application has everything it needs to run when you migrate it. The Config Server supports labeled versions of environment-specific configurations and is accessible to a wide range of tooling for managing its content. To gain a better understanding of the Spring Cloud Config Server, you should read the [Spring Cloud Config documentation](https://spring.io/projects/spring-cloud-config). @@ -17,20 +17,23 @@ You should also have a good understanding of the [Spring Cloud Config Server](ht To use the Steeltoe provider, you need to do the following: 1. Add the appropriate NuGet package reference to your project. -1. Configure the settings that the Steeltoe provider uses to access the Spring Cloud Config Server. +1. Configure the settings that the Steeltoe provider uses to access Spring Cloud Config Server. 1. Add the provider to the host builder or configuration builder. 1. Optionally, bind the configuration data to a class using the Options Pattern. 1. Inject and use `IConfiguration` or `IOptions<>` to access configuration data. ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.ConfigServer` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.ConfigServer` NuGet package. ### Configure Settings The most convenient way to configure settings for the provider is to put them in a file and then use one of the other file-based configuration providers to read them. -The following example shows some provider settings that have been put in a JSON file. Only two settings are really necessary. `Spring:Application:Name` configures the "application name" to be `sample`, and `Spring:Cloud:Config:Uri` configures the address of the config server. +The following example shows some provider settings that have been put in a JSON file. Only two settings are required: + +* `Spring:Application:Name` configures the "application name" to be `sample`. +* `Spring:Cloud:Config:Uri` configures the address of the Config Server. > [!TIP] > The `Spring:Application:Name` key is also used by various other Steeltoe components. @@ -52,38 +55,38 @@ The following example shows some provider settings that have been put in a JSON The following table describes all the settings that can be used to configure the behavior of the provider: +As mentioned earlier, all settings should start with `Spring:Cloud:Config:`. + | Key | Description | Default | -| --- | --- | --- | -| `Name` | Application name for which to request configuration. | | -| `Enabled` | Enable or disable the config server client. | `true` | -| `Uri` | Comma-separated list of config server endpoints. | `http://localhost:8888` | -| `Env` | Environment or profile used in the server request. | `Production` | -| `ValidateCertificates` | Enable or disable server certificate validation. | `true` | -| `Label` | Comma-separated list of labels to request. | | +| --- | ----------- | ------- | +| `Name` | Application name for which to request configuration | | +| `Enabled` | Enable or disable the Config Server client | `true` | +| `Uri` | Comma-separated list of Config Server endpoints | `http://localhost:8888` | +| `Env` | Environment or profile used in the server request | `Production` | +| `ValidateCertificates` | Enable or disable server certificate validation | `true` | +| `Label` | Comma-separated list of labels to request | | | `Timeout` | Time to wait for response from server, in milliseconds. | `60_000` (1 min) | -| `PollingInterval` | How often to check for changes in Config Server. | | -| `Username` | Username for basic authentication. | | -| `Password` | Password for basic authentication. | | -| `FailFast` | Enable or disable failure at startup. | `false` | -| `Headers` | Extra HTTP headers which are added to config server requests. | | -| `Token` | HashiCorp Vault authentication token. | | -| `TokenTtl` | HashiCorp Vault token renewal TTL, in milliseconds. Valid on Cloud Foundry only. | `300_000` (5 min) | -| `TokenRenewRate` | HashiCorp Vault token renewal rate, in milliseconds. Valid on Cloud Foundry only. | `60_000` (1 min) | -| `DisableTokenRenewal` | Enable or disable HashiCorp Vault token renewal. Valid on Cloud Foundry only. | `false` | -| `Retry:Enabled` | Enable or disable retry logic. | `false` | -| `Retry:MaxAttempts` | Max retries if retry enabled. | `6` | -| `Retry:InitialInterval` | Starting interval, in milliseconds. | `1000` | -| `Retry:MaxInterval` | Maximum retry interval, in milliseconds. | `2000` | -| `Retry:Multiplier` | Retry interval multiplier. | `1.1` | -| `ClientId` | OAuth2 client ID when using OAuth security. | | -| `ClientSecret` | OAuth2 client secret when using OAuth security. | | +| `PollingInterval` | How often to check for changes in Config Server | | +| `Username` | Username for basic authentication | | +| `Password` | Password for basic authentication | | +| `FailFast` | Enable or disable failure at startup | `false` | +| `Headers` | Extra HTTP headers that are added to Config Server requests | | +| `Token` | HashiCorp Vault authentication token | | +| `TokenTtl` | HashiCorp Vault token renewal TTL, in milliseconds. Valid on Cloud Foundry only | `300_000` (5 min) | +| `TokenRenewRate` | HashiCorp Vault token renewal rate, in milliseconds. Valid on Cloud Foundry only | `60_000` (1 min) | +| `DisableTokenRenewal` | Enable or disable HashiCorp Vault token renewal. Valid on Cloud Foundry only | `false` | +| `Retry:Enabled` | Enable or disable retry logic | `false` | +| `Retry:MaxAttempts` | Max retries if retry enabled | `6` | +| `Retry:InitialInterval` | Starting interval, in milliseconds | `1000` | +| `Retry:MaxInterval` | Maximum retry interval, in milliseconds | `2000` | +| `Retry:Multiplier` | Retry interval multiplier | `1.1` | +| `ClientId` | OAuth2 client ID when using OAuth security | | +| `ClientSecret` | OAuth2 client secret when using OAuth security | | | `AccessTokenUri` | URI to use to obtain OAuth access token. | | -| `Discovery:Enabled` | Enable or disable the Discovery First feature. | `false` | -| `Discovery:ServiceId` | Config Server service ID to use in Discovery First feature. | `configserver` | -| `Health:Enabled` | Enable or disable config server health check contributor. | `true` | -| `Health:TimeToLive` | Health check contributor cache time to live, in milliseconds. | `300_000` (5 min) | - -As mentioned earlier, all settings above should start with `Spring:Cloud:Config:` +| `Discovery:Enabled` | Enable or disable the Discovery First feature | `false` | +| `Discovery:ServiceId` | Config Server service ID to use in Discovery First feature | `configserver` | +| `Health:Enabled` | Enable or disable Config Server health check contributor | `true` | +| `Health:TimeToLive` | Health check contributor cache time to live, in milliseconds | `300_000` (5 min) | > [!TIP] > If you use self-signed certificates on Cloud Foundry, you might run into certificate validation issues when pushing an application. @@ -91,16 +94,16 @@ As mentioned earlier, all settings above should start with `Spring:Cloud:Config: ### Add Configuration Provider -Once the provider's settings have been defined and put in a file (such as a JSON file), the next step is to read them and make them available to the provider. +After the provider's settings have been defined and put in a file (such as a JSON file), the next step is to read them and make them available to the provider. In the next C# example, the provider's configuration settings from the preceding example are put in the `appsettings.json` file included with the application. Then, by using the .NET JSON configuration provider, we can read the settings by adding the JSON provider to the configuration builder (`AddJsonFile("appsettings.json")`). -Then, after the JSON provider has been added, you can add the config server provider to the builder. Steeltoe provides an extension method, `AddConfigServer()`, that you can use to do so. +Then, after the JSON provider has been added, you can add the Config Server provider to the builder. Steeltoe provides an extension method, `AddConfigServer()`, that you can use to do this. -Because the JSON provider that reads `appsettings.json` has been added *before* the config server provider, the JSON-based settings become available to the Steeltoe provider. Note that you do not have to use JSON for the Steeltoe settings. You can use any of the other off-the-shelf configuration providers for the settings (such as INI files, environment variables, and so on). +Because the JSON provider that reads `appsettings.json` has been added *before* the Config Server provider, the JSON-based settings become available to the Steeltoe provider. Note that you do not have to use JSON for the Steeltoe settings. You can use any of the other off-the-shelf configuration providers for the settings (such as INI files, environment variables, and so on). > [!CAUTION] -> You need to use the `Add*()` methods to add the source of the config server clients settings (`AddJsonFile(..)`) *before* you use `AddConfigServer(..)`. Otherwise, the settings are not picked up and used. +> You must use the `Add*()` methods to add the source of the Config Server clients settings (`AddJsonFile(..)`) *before* you use `AddConfigServer(..)`. Otherwise, the settings are not picked up and used. The following sample shows how to add a configuration provider: @@ -143,7 +146,7 @@ cf bind-service myApp myConfigServer cf restage myApp ``` -Once the service is bound to the application, the config server settings are available and can be set up in `VCAP_SERVICES`. +After the service is bound to the application, the Config Server settings are available and can be set up in `VCAP_SERVICES`. Then, when you push the application, the Steeltoe provider takes the settings from the service binding and merges those settings with the settings that you have provided through other configuration mechanisms (such as `appsettings.json`). @@ -153,12 +156,12 @@ If there are any merge conflicts, the last provider added to the configuration t When the `ConfigurationBuilder` builds the configuration, the Config Server client makes the appropriate REST calls to the Config Server and retrieves the configuration values based on the settings that have been provided. -If there are any errors or problems accessing the server, the application continues to initialize, but the values from the server are not retrieved. If this is not the behavior you want, you should set `Spring:Cloud:Config:FailFast` to `true`. Once that is done, the application fails to start if problems occur during the retrieval. +If there are any errors or problems accessing the server, the application continues to initialize, but the values from the server are not retrieved. If this is not the behavior you want, set `Spring:Cloud:Config:FailFast` to `true`. After that is done, the application fails to start if problems occur during the retrieval. > [!TIP] -> To diagnose startup errors, activate bootstrap logging as described [here](../bootstrap/index.md#logging-inside-configuration-providers). +> To diagnose startup errors, activate bootstrap logging as described in [Application Bootstrapping](../bootstrap/index.md#logging-inside-configuration-providers). -After the configuration has been built, you can access the retrieved data directly by using `IConfiguration`. The following example shows how to do so: +After the configuration has been built, you can access the retrieved data directly by using `IConfiguration`. See the following example: ```csharp var configuration = configurationBuilder.Build(); @@ -166,57 +169,57 @@ string? property1 = configuration["example:property1"]; string? property2 = configuration["example:property2"]; ``` -Alternatively, you can create a class to hold your configuration data and then use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) together with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to obtain an instance of your options class into your controllers and views. +Alternatively, you can create a class to hold your configuration data and then use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) along with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to get an instance of your options class into your controllers and views. -To do so, first create a class representing the configuration data you expect to retrieve from the server, as follows: +1. First create a class representing the configuration data you expect to retrieve from the server, as follows: -```csharp -public class ExampleOptions -{ - public string? Property1 { get; set; } - public string? Property2 { get; set; } -} -``` + ```csharp + public class ExampleOptions + { + public string? Property1 { get; set; } + public string? Property2 { get; set; } + } + ``` -Next, use the code below to bind the `example:*` values to an instance of the `ExampleOptions` class. +1. Bind the `example:*` values to an instance of the `ExampleOptions` class using the following code. -```csharp -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddOptions().BindConfiguration("example"); -``` + ```csharp + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddOptions().BindConfiguration("example"); + ``` -After this has been done, you can gain access to the data in your `Controller` or `View` through dependency injection. The following example shows how to do so: +1, Now you can gain access to the data in your `Controller` or `View` through dependency injection. The following example shows how to do this: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.Extensions.Options; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.Extensions.Options; -public class HomeController(IOptionsSnapshot optionsSnapshot) - : Controller -{ - public IActionResult Index() + public class HomeController(IOptionsSnapshot optionsSnapshot) + : Controller { - ExampleOptions options = optionsSnapshot.Value; - - ViewData["property1"] = options.Property1; - ViewData["property2"] = options.Property2; - ViewData["property2"] = options.Property2; - return View(); + public IActionResult Index() + { + ExampleOptions options = optionsSnapshot.Value; + + ViewData["property1"] = options.Property1; + ViewData["property2"] = options.Property2; + ViewData["property2"] = options.Property2; + return View(); + } } -} -``` + ``` ### Configuring Discovery First -The default behavior for the Steeltoe Config Client is to access the Config Server through the `Spring:Cloud:Config:Uri` configuration setting. This of course requires that the application contains an `appsettings.json` or an environment variable with the Config Server's address set in `Spring:Cloud:Config:Uri`. This mode of operation, the default, is called "Config First". +The default behavior for the Steeltoe Config Client is to access the Config Server through the `Spring:Cloud:Config:Uri` configuration setting. This requires that the application contains an `appsettings.json` or an environment variable with the Config Server's address set in `Spring:Cloud:Config:Uri`. This mode of operation, the default, is called "Config First." -Alternatively, you can set up your Config Server to register with a discovery service such as Netflix Eureka. This enables your application to look up the address of the Config Server by using a discovery service instead of configuring it in `appsettings.json`. Note that you have to specifically configure your Config Server deployment to register with a discovery service, as this does not happen automatically. See the Spring Cloud Config Server documentation for how to do so. +Alternatively, you can set up your Config Server to register with a discovery service such as Netflix Eureka. This enables your application to look up the address of the Config Server by using a discovery service instead of configuring it in `appsettings.json`. Note that you have to specifically configure your Config Server deployment to register with a discovery service; this does not happen automatically. See the Spring Cloud Config Server documentation for how to do this. -However, with the default "Config First" mode of the Steeltoe client, you are not able to take advantage of the Config Server registration unless you change the clients' mode of operation to "Discovery First". To do so: +However, with the default "Config First" mode of the Steeltoe client, you cannot take advantage of the Config Server registration unless you change the clients' mode of operation to "Discovery First." To do this: -1. If your application does not use a service discovery service, you need to configure your application to do so. See the [Steeltoe Discovery documentation](../discovery/initialize-discovery-client.md) for the details on how. At a minimum, you need to configure the Eureka Server address. +1. If your application does not use a service discovery service, you need to configure your application to do so. See the [Steeltoe Discovery documentation](../discovery/initialize-discovery-client.md) for instructions. At a minimum, you must configure the Eureka Server address. 1. Change the Steeltoe Config Server client setting `Spring:Cloud:Config:Discovery:Enabled` to `true` (the default is `false`). -1. If your Config Server is registered with Eureka using a name other than "configserver", use `Spring:Cloud:Config:Discovery:ServiceId` to specify the name used by the client for lookup. +1. If your Config Server is registered with Eureka using a name other than "configserver," use `Spring:Cloud:Config:Discovery:ServiceId` to specify the name used by the client for lookup. Note that the cost for using this mode of operation is an extra network roundtrip on startup to locate the Config Server service registration. The benefit is that, as long as the discovery service is at a fixed point, the Config Server can change its address and no changes to applications are needed. @@ -238,15 +241,19 @@ In some cases, you may want to fail the startup of your application if it cannot If you expect that the Config Server may occasionally be unavailable when your application starts, you can make it keep trying after a failure. -First, you need to set `Spring:Cloud:Config:FailFast` to `true`. Then you need to enable retry by setting `Spring:Cloud:Config:Retry:Enabled` to `true`. +1. First, set `Spring:Cloud:Config:FailFast` to `true`. +1. Then, enable retry by setting `Spring:Cloud:Config:Retry:Enabled` to `true`. -The default behavior is to retry six times with an initial back-off interval of 1000ms and an exponential multiplier of 1.1 for subsequent back-offs. You can configure these settings (and others) by setting the `Spring:Cloud:Config:Retry:*` configuration settings described earlier. +The default behavior is to retry six times with an initial back-off interval of 1000 ms and an exponential multiplier of 1.1 for subsequent back-offs. You can configure these settings (and others) by setting the `Spring:Cloud:Config:Retry:*` configuration settings described earlier. ### Configuring Multiple URLs -To ensure high availability when you have multiple instances of Config Server deployed and expect one or more instances to be unavailable from time to time, you can either specify multiple URLs as a comma-separated list for `Spring:Cloud:Config:Uri` or have all your instances register in a Service Registry such as Eureka (if you use "Discovery First" mode). +To ensure high availability when you have multiple instances of Config Server deployed, and you expect one or more instances to be unavailable from time to time, you can do one of the following: + +* Specify multiple URLs as a comma-separated list for `Spring:Cloud:Config:Uri` +* Have all your instances register in a Service Registry such as Eureka (if you use "Discovery First" mode) -Note that doing so ensures high availability only when the Config Server is not running or responding (for example, when the server has exited or when a connection timeout has occurred). For example, if the Config Server returns a 500 (Internal Server Error) response or the Steeltoe client receives a 401 from the Config Server (due to bad credentials or other causes), the client does not try to fetch properties from other URLs. An error of that kind indicates a user issue rather than an availability problem. +Note that this ensures high availability only when the Config Server is not running or responding (for example, when the server has exited or when a connection timeout has occurred). For example, if the Config Server returns a 500 (Internal Server Error) response or the Steeltoe client receives a 401 from the Config Server (due to bad credentials or other causes), the client does not try to fetch properties from other URLs. An error of that kind indicates a user issue rather than an availability problem. If you use HTTP basic auth security on your Config Server, it is possible to use per-Config Server auth credentials by embedding the credentials in each URL you specify for the `Spring:Cloud:Config:Uri` setting. If you use any other kind of security mechanism, you cannot currently use per-Config Server authentication and authorization. @@ -278,4 +285,4 @@ Aside from PEM files, Steeltoe supports a single file in PKCS#12 format: ``` > [!TIP] -> A single certificate can be shared with both Config Server and Eureka, by using the key "Certificates" instead of "Certificates:ConfigServer". +> A single certificate can be shared with both Config Server and Eureka by using the key `Certificates` instead of `Certificates:ConfigServer`. diff --git a/api/v4/configuration/index.md b/api/v4/configuration/index.md index f21f55e4..89c507a4 100644 --- a/api/v4/configuration/index.md +++ b/api/v4/configuration/index.md @@ -11,15 +11,15 @@ Each value contained in the configuration is tied to a string-typed key or name. * Environment variables * Custom providers -To better understand .NET configuration services, you should read the [ASP.NET Core documentation](https://learn.microsoft.com/aspnet/core/fundamentals/configuration). Note that, while the documentation link suggests this service is tied to ASP.NET Core, it is not. It can be used in many different application types, including Console, ASP.NET 4.x., UWP, and others. +To better understand .NET configuration services, see the [ASP.NET Core documentation](https://learn.microsoft.com/aspnet/core/fundamentals/configuration). Note that, while the documentation link suggests this service is tied to ASP.NET Core, it is not. It can be used in many different application types, including Console, ASP.NET 4.x., UWP, and others. -Steeltoe adds additional configuration providers to the preceding list: +Steeltoe adds the following configuration providers to the preceding list: -* Cloud Foundry (JSON from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables) * Spring Cloud Config Server +* Random value generator * Placeholder resolvers * Decryption of encrypted values -* Random value generator +* Cloud Foundry (JSON from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables) * Spring Boot configuration -The following sections provide more detail on each of these Steeltoe providers. +The following sections provide more detail about each of these Steeltoe providers. From 4a5109eddcd38b4b299f00500fc50f13b9b89120 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Wed, 26 Feb 2025 14:12:30 -0800 Subject: [PATCH 07/43] full edit Application Configuration topics + Mgmt section of What's New --- .../configuration/cloud-foundry-provider.md | 34 +++++----- api/v4/configuration/decryption-provider.md | 68 ++++++++++--------- api/v4/configuration/placeholder-provider.md | 12 ++-- api/v4/configuration/random-value-provider.md | 16 ++--- api/v4/configuration/spring-boot-provider.md | 14 ++-- api/v4/welcome/whats-new.md | 26 +++---- 6 files changed, 85 insertions(+), 85 deletions(-) diff --git a/api/v4/configuration/cloud-foundry-provider.md b/api/v4/configuration/cloud-foundry-provider.md index fab58612..b08d8e42 100644 --- a/api/v4/configuration/cloud-foundry-provider.md +++ b/api/v4/configuration/cloud-foundry-provider.md @@ -2,30 +2,30 @@ The Cloud Foundry provider enables the standard Cloud Foundry environment variables (`VCAP_APPLICATION`, `VCAP_SERVICES`, and `CF_*`) to be parsed and accessed as configuration data within a .NET application. -Cloud Foundry creates and uses these environment variables to communicate an application's environment and configuration to the application code running inside a container. More specifically, the values found in `VCAP_APPLICATION` provide information about the application's resource limits, routes (URIs), and version numbers, among other things. The `VCAP_SERVICES` environment variable provides information about the external services (databases, caches, and so on) to which the application is bound, along with details on how to contact those services. +Cloud Foundry creates and uses these environment variables to communicate an application's environment and configuration to the application code running inside a container. More specifically, the values found in `VCAP_APPLICATION` provide information about the application's resource limits, routes (URIs), and version numbers, among other things. The `VCAP_SERVICES` environment variable provides information about the external services (databases, caches, and so on) to which the application is bound, along with details for contacting those services. -You can read more information on the Cloud Foundry environment variables at the [Cloud Foundry docs](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html) website. +For more information about the Cloud Foundry environment variables, see the [Cloud Foundry documentation](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html). ## Usage You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe Cloud Foundry provider, you need to do the following: +To use the Steeltoe Cloud Foundry provider: 1. Add the appropriate NuGet package reference to your project. -1. Add the provider to the host builder or configuration builder. -1. Configure Cloud Foundry option classes by binding configuration data to them. -1. Inject and use `IConfiguration` or `IOptions<>` to access configuration data. +2. Add the provider to the host builder or configuration builder. +3. Configure Cloud Foundry option classes by binding configuration data to them. +4. Inject and use `IConfiguration` or `IOptions<>` to access configuration data. ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.CloudFoundry` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.CloudFoundry` NuGet package. ### Add Configuration Provider with Options The `AddCloudFoundryConfiguration()` host builder extension method is the easiest way to set things up. It performs -both of the individual steps described below: add the configuration provider and configure options. -The following example shows how to do so: +both of the individual steps described below: adding the configuration provider and configuring the options. +See the following example: ```csharp using Steeltoe.Configuration.CloudFoundry; @@ -34,7 +34,7 @@ var builder = WebApplication.CreateBuilder(args); builder.AddCloudFoundryConfiguration(); ``` -#### Add Configuration Provider +#### Add Configuration Provider without using the host builder extension method If you don't want to use the host builder extension method, the following code shows how to add the Cloud Foundry configuration provider to the `ConfigurationBuilder`: @@ -48,7 +48,7 @@ var configuration = configurationBuilder.Build(); ### Access Configuration Data -Once the configuration has been built, the values from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables have been added to the application's configuration data and become available under keys prefixed with `vcap:application` and `vcap:services` respectively. +After the configuration has been built, the values from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables have been added to the application's configuration data and become available under keys prefixed with `vcap:application` and `vcap:services`, respectively. You can access the values from the `VCAP_APPLICATION` environment variable settings directly from the `IConfiguration` as follows: @@ -57,9 +57,9 @@ var appName = configuration["vcap:application:application_name"]; var instanceId = configuration["vcap:application:instance_id"]; ``` -A list of all `VCAP_APPLICATION` keys is available in the [VCAP_APPLICATION](https://docs.CloudFoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION) topic of the Cloud Foundry documentation. +A list of all `VCAP_APPLICATION` keys is available in [VCAP_APPLICATION](https://docs.CloudFoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION), in the Cloud Foundry documentation. -You can also directly access the values from the `VCAP_SERVICES` environment variable. For example, to access the information about the first instance of a bound Cloud Foundry service with the name `service-name`, you could code the following: +You can also access the values directly from the `VCAP_SERVICES` environment variable. For example, to access the information about the first instance of a bound Cloud Foundry service with the name `service-name`, you could code the following: ```csharp var name = configuration["vcap:services:service-name:0:name"]; @@ -69,15 +69,15 @@ var uri = configuration["vcap:services:service-name:0:credentials:uri"]; A list of all `VCAP_SERVICES` keys is available in the [VCAP_SERVICES](https://docs.CloudFoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) topic of the Cloud Foundry documentation. > [!NOTE] -> This provider uses the built-in .NET [JSON configuration provider](https://learn.microsoft.com/dotnet/core/extensions/configuration-providers#json-configuration-provider) when parsing the JSON provided in the `VCAP_*` environment variables. As a result, you can expect the exact same key names and behavior as you see when parsing JSON configuration files (such as `appsettings.json`) in your application. +> This provider uses the built-in .NET [JSON configuration provider](https://learn.microsoft.com/dotnet/core/extensions/configuration-providers#json-configuration-provider) when parsing the JSON provided in the `VCAP_*` environment variables. As a result, you can expect exactly the same key names and behavior as you see when parsing JSON configuration files (such as `appsettings.json`) in your application. ### Access Configuration Data as Options -Alternatively, instead of accessing the Cloud Foundry configuration data directly from the configuration, you can use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) together with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to obtain an instance of the option classes into your controllers and views. +Alternatively, instead of accessing the Cloud Foundry configuration data directly from the configuration, you can use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to obtain an instance of the option classes into your controllers and views. The Cloud Foundry provider includes two additional classes, `CloudFoundryApplicationOptions` and `CloudFoundryServicesOptions`. You can configure both to bind to the parsed `VCAP_*` data. -If you're not using the host builder extension method mentioned above, the `AddCloudFoundryOptions()` method can be used to configure the Cloud Foundry option classes. This method binds the parsed `VCAP_*` data to the `CloudFoundryApplicationOptions` and `CloudFoundryServicesOptions` classes. The following example shows how to do so: +If you're not using the host builder extension method described earlier, you can use the `AddCloudFoundryOptions()` method to configure the Cloud Foundry option classes. This method binds the parsed `VCAP_*` data to the `CloudFoundryApplicationOptions` and `CloudFoundryServicesOptions` classes. See the following example: ```csharp using Steeltoe.Configuration.CloudFoundry; @@ -87,7 +87,7 @@ builder.Configuration.AddCloudFoundry(); builder.Services.AddCloudFoundryOptions(); ``` -Once this is done, you can access these configuration objects in the controllers or views of an application by using normal Dependency Injection, as follows: +After this is done, you can access these configuration objects in the controllers or views of an application by using normal Dependency Injection, as follows: ```csharp using Microsoft.AspNetCore.Mvc; diff --git a/api/v4/configuration/decryption-provider.md b/api/v4/configuration/decryption-provider.md index 52d50226..89a55b28 100644 --- a/api/v4/configuration/decryption-provider.md +++ b/api/v4/configuration/decryption-provider.md @@ -1,14 +1,15 @@ # Decryption Provider The decryption provider decrypts secrets generated by the Spring Cloud Config Server encryption method. For more details on generating secrets, -you should read the [Spring Cloud documentation](https://cloud.spring.io/spring-cloud-static/spring-cloud.html#_encryption_and_decryption_2) and the [Spring Cloud Config Server documentation](https://docs.spring.io/spring-cloud-config/docs/current/reference/html/#_encryption_and_decryption) -on encrypting and decrypting. +see the [Spring Cloud documentation](https://cloud.spring.io/spring-cloud-static/spring-cloud.html#_encryption_and_decryption_2) and the [Spring Cloud Config Server documentation](https://docs.spring.io/spring-cloud-config/docs/current/reference/html/#_encryption_and_decryption) +about encrypting and decrypting. The two main use cases for the decryption provider are: + - Decrypting encrypted secrets hosted by Config Server - Storing encrypted secrets in a git repository -To use the provider, you need to add a reference to the `Steeltoe.Configuration.Encryption` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.Encryption` NuGet package. Then the decryption provider can be enabled as follows: ```csharp @@ -18,9 +19,9 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddDecryption(); ``` -This will use the Spring Cloud Config encryption mechanism. +This uses the Spring Cloud Config encryption mechanism. -Any configuration value prefixed with `{cipher}` will be decrypted using the configured key: +Any configuration value prefixed with `{cipher}` is decrypted using the configured key: ```json { @@ -28,45 +29,46 @@ Any configuration value prefixed with `{cipher}` will be decrypted using the con } ``` -To decrypt secrets, the decryption provider needs to be configured to match the encryption settings. +To decrypt secrets, the decryption provider must be configured to match the encryption settings. There are two types of encryption: symmetric and asymmetric. -For symmetric encryption, a shared key is used to decrypt the secrets: -```json -{ - "Encrypt": { - "Enabled": true, - "Key": "12345678901234567890" - } -} -``` +* For symmetric encryption, a shared key is used to decrypt the secrets: -> [!CAUTION] -> The shared key should not be part of any source code repository, but should be passed in some other way to the application. + ```json + { + "Encrypt": { + "Enabled": true, + "Key": "12345678901234567890" + } + } + ``` -For asymmetric encryption, the configuration should be as follows: + > [!CAUTION] + > The shared key should not be part of any source code repository, but should be passed to the application in some other way. -```json -{ - "Encrypt": { - "Enabled": true, - "KeyStore": { - "Location": "path/to/keystore", - "Password": "keystore_password", - "Alias": "keyalias" +* For asymmetric encryption, the configuration should be as follows: + + ```json + { + "Encrypt": { + "Enabled": true, + "KeyStore": { + "Location": "path/to/keystore", + "Password": "keystore_password", + "Alias": "keyalias" + } + } } - } -} -``` + ``` -> [!CAUTION] -> The password and the keystore file should not be part of any source code repository, but should be passed in some other way to the application. + > [!CAUTION] + > The password and the keystore file should not be part of any source code repository, but should be passed to the application in some other way. The following table describes the configuration settings that you can apply to the decryption provider: | Key | Description | Default | -| --- | --- | --- | +| --- | ----------- | ------- | | `Encrypt:Enabled` | Enable decryption of encrypted `{cipher}` values. | `false` | | `Encrypt:Rsa:Strong` | When set to `true`, the "strong" GCM AES algorithm is used. Otherwise, the standard CBC algorithm is used. | `false` | | `Encrypt:Rsa:Salt` | Salt for the random secret used to encrypt cipher text. | `deadbeef` | @@ -106,4 +108,4 @@ builder.Configuration.AddDecryption(new ExampleTextDecryptor(), NullLoggerFactor ``` > [!WARNING] -> Creating encryption algorithms is notoriously difficult. Only use this if you know what you are doing. +> Creating encryption algorithms is notoriously difficult. Use this only if you know what you are doing. diff --git a/api/v4/configuration/placeholder-provider.md b/api/v4/configuration/placeholder-provider.md index 95a0930f..fa10918a 100644 --- a/api/v4/configuration/placeholder-provider.md +++ b/api/v4/configuration/placeholder-provider.md @@ -2,7 +2,7 @@ The placeholder resolver enables usage of `${....}` placeholders in your configuration. The provider lets you define configuration values as placeholders and have them be substituted with evaluated values at runtime during configuration access, based on the values of other configuration keys. -A placeholder takes the form of `${key:subkey1:subkey2?defaultValue}`, where `key:subkey1:subkey2` represents another key in the configuration. At runtime, when you access a configuration key whose value contains a placeholder, the resolver is called to substitute the placeholder with a value that exists in the configuration. If no value is found at the placeholder key, the placeholder is returned unresolved. But if a default value is specified in the placeholder, that default value is returned instead. +A placeholder takes the form of `${key:subkey1:subkey2?defaultValue}`, where `key:subkey1:subkey2` represents another key in the configuration. At runtime, when you access a configuration key for which the value contains a placeholder, the resolver is called to substitute the placeholder with a value that exists in the configuration. If no value is found at the placeholder key, the placeholder is returned unresolved. But if a default value is specified in the placeholder, that default value is returned instead. Note that placeholder defaults (for example, `defaultValue`) can also be defined to be placeholders, and they are resolved as well. @@ -10,7 +10,7 @@ Note that placeholder defaults (for example, `defaultValue`) can also be defined You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe placeholder resolver provider, you need to: +To use the Steeltoe placeholder resolver provider: 1. Add the appropriate NuGet package reference to your project. 1. Add the provider to the Configuration Builder. @@ -18,11 +18,11 @@ To use the Steeltoe placeholder resolver provider, you need to: ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.Placeholder` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.Placeholder` NuGet package. ### Add Configuration Provider -To have placeholders resolved when accessing your configuration data, you need to add the placeholder resolver provider to the `ConfigurationBuilder`. +To have placeholders resolved when accessing your configuration data, add the placeholder resolver provider to the `ConfigurationBuilder`. ```csharp using Steeltoe.Configuration.Placeholder; @@ -33,11 +33,11 @@ builder.Configuration.AddPlaceholderResolver(); > [!IMPORTANT] > The placeholder resolver works by wrapping and replacing (effectively taking ownership of) all existing configuration sources already added to the `ConfigurationBuilder`. -> As a result, you typically will want to add it as the *last* provider. +> As a result, you typically want to add it as the *last* provider. ### Access Configuration Data -Once the configuration has been built, the placeholder resolver is used to resolve any placeholders as you access your configuration data. You can access the configuration data as you normally would, and the resolver tries to resolve any placeholder before returning the value for the key requested. +After the configuration has been built, the placeholder resolver is used to resolve any placeholders as you access your configuration data. You can access the configuration data as you normally would, and the resolver tries to resolve any placeholder before returning the value for the key requested. Consider the following `appsettings.json` file: diff --git a/api/v4/configuration/random-value-provider.md b/api/v4/configuration/random-value-provider.md index 745324f5..4b52cd4b 100644 --- a/api/v4/configuration/random-value-provider.md +++ b/api/v4/configuration/random-value-provider.md @@ -2,7 +2,7 @@ Sometimes, you might need to generate random values as part of your application's configuration values. -The Steeltoe random value generator is a configuration provider that you can use to do just that. It can produce integers, longs, GUIDs, or strings, as the following examples show: +The Steeltoe random value generator is a configuration provider that you can use to produce integers, longs, GUIDs, or strings, as the following examples show: ```csharp string? randomValue = builder.Configuration["random:value"]; @@ -13,7 +13,7 @@ int randomNumberLessThanTen = builder.Configuration.GetValue("random:int(10 int randomNumberInRange = builder.Configuration.GetValue("random:int[1024,65536]"); ``` -You can also use the generator together with property placeholders. For example, consider the following `appsettings.json`: +You can also use the generator with property placeholders. For example, consider the following `appsettings.json`: ```json { @@ -32,7 +32,7 @@ You can also use the generator together with property placeholders. For example, You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe random value provider, you need to: +To use the Steeltoe random value provider: 1. Add the appropriate NuGet package reference to your project. 1. Add the provider to the Configuration Builder. @@ -40,13 +40,11 @@ To use the Steeltoe random value provider, you need to: ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.RandomValue` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.RandomValue` NuGet package. ### Add Configuration Provider -To have the ability to generate random values from the configuration, you need to add the random value provider to the `ConfigurationBuilder`. - -The following example shows how to do so: +To have the ability to generate random values from the configuration, add the random value provider to the `ConfigurationBuilder`. See the following example: ```csharp using Steeltoe.Configuration.RandomValue; @@ -56,11 +54,11 @@ builder.Configuration.AddRandomValueSource(); ``` > [!TIP] -> If you wish to generate random values as part of using placeholders, you need to add the random value provider to the builder *before* you add the placeholder resolver. +> To generate random values as part of using placeholders, add the random value provider to the builder *before* you add the placeholder resolver. ### Access Random Value Data -Once the configuration has been built, the random value provider can be used to generate values. You can access the configuration data by using the appropriate `random` keys. +After the configuration has been built, the random value provider can be used to generate values. You can access the configuration data by using the appropriate `random` keys. Consider the following `HomeController` example: diff --git a/api/v4/configuration/spring-boot-provider.md b/api/v4/configuration/spring-boot-provider.md index eb339304..e3fc9161 100644 --- a/api/v4/configuration/spring-boot-provider.md +++ b/api/v4/configuration/spring-boot-provider.md @@ -9,21 +9,21 @@ In both cases, any `.` delimiters in configuration keys are converted to `:`, wh You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe Spring Boot provider, you need to: +To use the Steeltoe Spring Boot provider: 1. Add the appropriate NuGet package reference to your project. -1. Add the provider to the Configuration Builder. -1. Access keys from the `IConfiguration`. +2. Add the provider to the Configuration Builder. +3. Access keys from the `IConfiguration`. ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.SpringBoot` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.SpringBoot` NuGet package. ### Add Configuration Provider -To access Spring Boot configuration data, you need to add the Spring Boot provider to the `ConfigurationBuilder`. +To access Spring Boot configuration data, add the Spring Boot provider to the `ConfigurationBuilder`. -The following example shows how to do so: +See the following example: ```csharp using Steeltoe.Configuration.SpringBoot; @@ -35,7 +35,7 @@ builder.Configuration.AddSpringBootFromCommandLine(args); ### Access Spring Boot Data -Once the configuration has been built, the Spring Boot provider can be used to access Spring-style keys in .NET syntax. +After the configuration has been built, you can use the Spring Boot provider to access Spring-style keys in .NET syntax. For example: ```csharp diff --git a/api/v4/welcome/whats-new.md b/api/v4/welcome/whats-new.md index 264eb647..82b2e914 100644 --- a/api/v4/welcome/whats-new.md +++ b/api/v4/welcome/whats-new.md @@ -267,7 +267,7 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | `Steeltoe.Common.Http.Serialization.BoolStringJsonConverter` | Type | Steeltoe.Common.Http | Removed | None | Made internal, moved to Steeltoe.Discovery.Eureka package | | `Steeltoe.Common.Http.Serialization.LongStringJsonConverter` | Type | Steeltoe.Common.Http | Removed | None | Made internal, moved to Steeltoe.Discovery.Eureka package | | `Steeltoe.Common.Logging.BootstrapLoggerFactory` | Type | Steeltoe.Common.Logging | Added | | Writes startup logs to console before logging has initialized | -| `Steeltoe.Common.Logging.BootstrapLoggerServiceCollectionExtensions.UpgradeBootstrapLoggerFactory` | Extension method | Steeltoe.Common.Logging | Added | | Upgrades existing loggers once app has started | +| `Steeltoe.Common.Logging.BootstrapLoggerServiceCollectionExtensions.UpgradeBootstrapLoggerFactory` | Extension method | Steeltoe.Common.Logging | Added | | Upgrades existing loggers after app has started | | `Steeltoe.Common.Net.IMPR` | Type | Steeltoe.Common.Net | Removed | None | Renamed to internal type `IMultipleProviderRouter` (existed for testing only) | | `Steeltoe.Common.Net.WindowsNetworkFileShare.GetLastError` | Method | Steeltoe.Common.Net | Removed | None | Now throws `IOException` on error | | `Steeltoe.Common.Net.WindowsNetworkFileShare.NetResource` | Type | Steeltoe.Common.Net | Removed | None | Nested type used internally for P/Invoke, should not be public | @@ -976,16 +976,16 @@ For more information, see the updated [Logging documentation](../logging/index.m - Cleaner extensibility model for third-party actuators - Fail at startup when actuators are used on Cloud Foundry without security - Improved security and redaction of sensitive data in responses and logs -- Actuators can be turned on/off or bound to different verbs at runtime via configuration -- Simplified content negotiation, updated all actuators to support latest Spring media type +- Actuators can be turned on/off or bound to different verbs at runtime using configuration +- Simplified content negotiation; updated all actuators to support latest Spring media type - New actuator `/beans` that lists the contents of the .NET dependency container, including support for keyed services -- Update health checks and actuator to align with latest Spring, hide details by default, contributors can be turned on/off at runtime via configuration -- Update `/mappings` actuator to include endpoints from Minimal APIs, Razor Pages and Blazor, with richer metadata and improved compatibility with Spring +- Update health checks and actuator to align with latest Spring; hide details by default; contributors can be turned on/off at runtime using configuration +- Update `/mappings` actuator to include endpoints from Minimal APIs, Razor Pages, and Blazor, with richer metadata and improved compatibility with Spring - Heap dumps are enabled by default in Cloud Foundry on Linux - Improved Prometheus exporter that works with latest OpenTelemetry - Various fixes for interoperability with latest Spring Boot Admin -- Unified `/traces` and `/httptraces` actuators to `/httpexchanges` to align with latest Spring -- WaveFront, Zipkin and Jaeger support was removed (use OpenTelemetry directly) +- Unified `/traces` and `/httptraces` actuators to `/httpexchanges`, to align with latest Spring +- WaveFront, Zipkin, and Jaeger support was removed (use OpenTelemetry directly) - Metrics endpoint was removed (use OpenTelemetry directly) - Kubernetes actuator was removed @@ -1009,7 +1009,7 @@ For more information, see the updated [Logging documentation](../logging/index.m | Source | Kind | Package | Change | Replacement | Notes | | ---------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | `Microsoft.Diagnostics.Runtime.Interop.IMAGE_FILE_MACHINE` | Type | Steeltoe.Management.Diagnostics | Removed | None | | -| `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddActuatorEndpointMapping` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Removed | `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorEndpoints` | Only needed when setting up middleware manually | +| `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddActuatorEndpointMapping` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Removed | `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorEndpoints` | Needed only when setting up middleware manually | | `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddCloudFoundryActuatorServices` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `builder.Services.AddCloudFoundryActuator()` | | | `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddDbMigrationsActuatorServices` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `builder.Services.AddDbMigrationsActuator()` | | | `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddEnvActuatorServices` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `builder.Services.AddEnvironmentActuator()` | | @@ -1066,10 +1066,10 @@ For more information, see the updated [Logging documentation](../logging/index.m | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.AvailabilityEventArgs` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.AvailabilityState` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.LivenessState` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | -| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.LivenessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables to turn off via configuration | +| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.LivenessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables turning off via configuration | | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.ReadinessState` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | -| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.ReadinessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables to turn off via configuration | -| `Steeltoe.Management.Endpoint.Actuators.Health.Contributors.DiskSpaceContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables to turn off via configuration | +| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.ReadinessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables turning off via configuration | +| `Steeltoe.Management.Endpoint.Actuators.Health.Contributors.DiskSpaceContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables turning off via configuration | | `Steeltoe.Management.Endpoint.Actuators.Health.HealthEndpointOptions.ShowComponents` | Property | Steeltoe.Management.Endpoint | Added | | Whether to show/hide contributors in response | | `Steeltoe.Management.Endpoint.Actuators.Health.HealthEndpointRequest` | Type | Steeltoe.Management.Endpoint | Added | | Data about incoming actuator request | | `Steeltoe.Management.Endpoint.Actuators.Health.HealthEndpointResponse.Components` | Property | Steeltoe.Management.Endpoint | Added | | List of health contributors in response | @@ -1113,8 +1113,8 @@ For more information, see the updated [Logging documentation](../logging/index.m | `Steeltoe.Management.Endpoint.ActuatorServiceCollectionExtensions.AddAllActuators` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `Steeltoe.Management.Endpoint.Actuators.All.EndpointServiceCollectionExtensions.AddAllActuators` | For custom CORS, call `services.ConfigureActuatorsCorsPolicy()` | | `Steeltoe.Management.Endpoint.ActuatorServiceCollectionExtensions.RegisterEndpointOptions` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Removed | None | Redundant | | `Steeltoe.Management.Endpoint.AllActuatorsStartupFilter` | Type | Steeltoe.Management.Endpoint [Base/Core] | Removed | None | Moved to internal type `ConfigureActuatorsMiddlewareStartupFilter` | -| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorsCorsPolicy` | Extension method | Steeltoe.Management.Endpoint | Added | | Only needed when setting up middleware manually | -| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseManagementPort` | Extension method | Steeltoe.Management.Endpoint | Added | | Only needed when setting up middleware manually | +| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorsCorsPolicy` | Extension method | Steeltoe.Management.Endpoint | Added | | Needed only when setting up middleware manually | +| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseManagementPort` | Extension method | Steeltoe.Management.Endpoint | Added | | Needed only when setting up middleware manually | | `Steeltoe.Management.Endpoint.CloudFoundry` | Namespace | Steeltoe.Management.Endpoint [Base/Core] | Moved | `Steeltoe.Management.Endpoint.Actuators.CloudFoundry` | | | `Steeltoe.Management.Endpoint.CloudFoundry.CloudFoundryActuatorStartupFilter` | Type | Steeltoe.Management.Endpoint [Base/Core] | Removed | `builder.Services.AddCloudFoundryActuator()` | Redundant | | `Steeltoe.Management.Endpoint.CloudFoundry.CloudFoundryEndpoint` | Type | Steeltoe.Management.Endpoint [Base/Core] | Removed | `ICloudFoundryEndpointHandler` | Moved to internal type `CloudFoundryEndpointHandler` | From 214f54e485f834f68c2e3f2d23717d1d94150db8 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Thu, 27 Feb 2025 14:46:02 -0800 Subject: [PATCH 08/43] full edit tracing section --- api/v4/tracing/index.md | 222 ++++++++++++++++++++++------------------ 1 file changed, 121 insertions(+), 101 deletions(-) diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index dd9535b8..6f9cc394 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -1,26 +1,28 @@ # Distributed Tracing -On the subject of distributed tracing for .NET applications, previous versions of Steeltoe offered either an implementation of OpenCensus or shortcuts for enabling distributed tracing with [OpenTelemetry](https://opentelemetry.io/) to integrate with the Tanzu platform. We painted ourselves into a corner with Steeltoe 3, which has a strong dependency on OpenTelemetry packages. New versions of OpenTelemetry contained breaking changes, which we couldn't adapt to without resorting to reflection. While we do that in other places, reflection is slow, and instrumentation is performance-sensitive. +This topic describes distributed tracing for .NET applications. -By now, OpenTelemetry has evolved to the point that only a few lines of code are needed. So instead of providing a Steeltoe component, the guidance below is offered to accomplish the same. The benefit of that is greater flexibility: when OpenTelemetry changes, there's no need to wait for a new Steeltoe version first. +Previous versions of Steeltoe offered either an implementation of OpenCensus or shortcuts for enabling distributed tracing with [OpenTelemetry](https://opentelemetry.io/) to integrate with the Tanzu platform. Steeltoe 3 has a strong dependency on OpenTelemetry packages, but with the breaking changes in the latest versions of OpenTelemetry, Steeltoe couldn't adapt without resorting to reflection. While we do that in other places, reflection is slow, and instrumentation is performance-sensitive. -Steeltoe continues to directly offer an option for [log correlation](#log-correlation). This page also provides direction for developers looking to achieve the same outcomes Steeltoe has previously provided more directly. +OpenTelemetry has evolved to the point that only a few lines of code are needed. So instead of providing a Steeltoe component, the guidance below is offered to accomplish the same. The benefit of this approach is greater flexibility: when OpenTelemetry changes, there's no need to wait for a new Steeltoe version before using it. -## Introduction +Steeltoe continues to directly offer an option for [log correlation](#log-correlation). This topic provides direction for developers looking to achieve the same outcomes Steeltoe has previously provided more directly. + +## About distributed tracing As the name implies, distributed tracing is a way of tracing requests through distributed systems. -Distributed tracing is typically accomplished by instrumenting components of the system to recognize and pass along metadata that is specific to a particular action or user request, and using another backend system to reconstruct the flow of the request through that metadata. +Distributed tracing is typically accomplished by instrumenting components of the system to allow recognizing and passing along metadata that is specific to a particular action or user request, and using another backend system to reconstruct the flow of the request through that metadata. In the parlance of distributed tracing, a "span" is the basic unit of work. For example, sending an HTTP request creates a new span, as does sending a response. -Spans are identified by a unique ID and contain the ID for the "trace" it is part of. +Each span is identified by a unique ID and contains the ID for the "trace" it is part of. Spans also have other data like descriptions, key-value annotations, the ID of the span that initiated the execution flow, and process IDs. -Spans are started and stopped, and they keep track of their timing information. Once you create a span, you must stop it at some point in the future. -A set of spans form a tree-like structure called a "trace". For example, a trace might be formed by a POST request that adds an item to a shopping cart, which results in calling several backend services. +Spans are started and stopped, and they keep track of their timing information. After you create a span, you must stop it at some point in the future. +A set of spans form a tree-like structure called a "trace." For example, a trace might be formed by a POST request that adds an item to a shopping cart, which results in calling several backend services. ## Log correlation -Log correlation is all about taking log entries from disparate systems and bringing them together using some matching criteria (such as a distributed trace ID). -The process can be easier when important pieces of data are logged in the same format across different systems (such as .NET and Java apps communicating with each other). +Log correlation refers to the process of taking log entries from disparate systems and bringing them together using some matching criteria (such as a distributed trace ID). +The process is easier when important pieces of data are logged in the same format across different systems (such as .NET and Java apps communicating with each other). Steeltoe provides the class `TracingLogProcessor`, which is an `IDynamicMessageProcessor` for correlating logs. The processor is built for use with a [Steeltoe Dynamic Logging provider](../logging/index.md). It enriches log entries with correlation data using the same trace format popularized by [Spring Cloud Sleuth](https://cloud.spring.io/spring-cloud-sleuth/reference/html/#log-correlation), @@ -36,55 +38,62 @@ dbug: Microsoft.EntityFrameworkCore.Database.Command[20104] [ActuatorApi,44ed2fe24a051bda2d1a56815448e9fb,c32846ff227bed40,f315823f4c554816,true] Created DbCommand for 'ExecuteReader' (1ms). ``` -Log correlation is easiest with a tool such as [Splunk](https://www.splunk.com/en_us/solutions/isolate-cloud-native-problems.html), [SumoLogic](https://www.sumologic.com/lp/log-analytics/) or [DataDog](https://www.datadoghq.com/dg/enterprise/log-management-analytics-security) (this is not an endorsement of any tool, only a pointer to some popular options). +Log correlation is easiest with a tool such as [Splunk](https://www.splunk.com/en_us/solutions/isolate-cloud-native-problems.html), [SumoLogic](https://www.sumologic.com/lp/log-analytics/), or [DataDog](https://www.datadoghq.com/dg/enterprise/log-management-analytics-security). (This is not an endorsement of any tool, only a pointer to some popular options). ### Using TracingLogProcessor -To use the processor, first add a reference to the `Steeltoe.Management.Tracing` NuGet package. +To use the processor: -The only remaining step is to register the processor: +1. Add a reference to the `Steeltoe.Management.Tracing` NuGet package. -```csharp -using Steeltoe.Management.Tracing; +2. Register the processor: -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddTracingLogProcessor(); -``` + ```csharp + using Steeltoe.Management.Tracing; + + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddTracingLogProcessor(); + ``` > [!NOTE] > This extension method also ensures that implementations of `IApplicationInstanceInfo` and `IDynamicLoggerProvider` have been registered. -> If you wish to customize either of those or use non-default implementations, do so before calling `AddTracingLogProcessor`. +> If you wish to customize either of these or use non-default implementations, make these changes before calling `AddTracingLogProcessor`. ## OpenTelemetry To use OpenTelemetry, start by adding a reference to the `OpenTelemetry.Extensions.Hosting` NuGet package. -Other package references will likely be necessary, but depend on your specific application needs. +Other package references will probably be necessary, but these depend on your specific application needs. This package provides access to `OpenTelemetryBuilder`, which is the main entrypoint to OpenTelemetry. ### Add Open Telemetry Tracing +To add Open Telemetry Tracing, use the following: + ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry().WithTracing(); ``` > [!NOTE] -> At this point, not much has changed for the application - you will need changes to this line to add [instrumentation](#instrumenting-applications) and [exporting of traces](#exporting-distributed-traces). +> At this point, not much has changed for the application, but you will continue by making changes to add [instrumentation](#instrumenting-applications) and [exporting of traces](#exporting-distributed-traces) to this line. ### Sampler configuration OpenTelemetry Provides the `Sampler` abstraction for configuring when traces should be recorded. The simplest options are `AlwaysOnSampler` and `AlwaysOffSampler`, with their names describing exactly which traces will be recorded. -As a replacement for what Steeltoe used to provide for using these samplers, set the environment variable `OTEL_TRACES_SAMPLER` to `always_on` or `always_off`. +As a replacement for what Steeltoe used to provide for using these samplers, set the environment variable `OTEL_TRACES_SAMPLER` to: + +* `always_on` +* `always_off` > [!TIP] > OpenTelemetry is generally built to follow the [options pattern](https://learn.microsoft.com/dotnet/core/extensions/options). -> There are more ways to configure options than demonstrated on this page, these are just examples to get started. +> There are more ways to configure options than demonstrated on this page; these are just examples to help you get started. ### Set Application Name -In order to use the Steeltoe name for your application with OpenTelemetry, call `SetResourceBuilder` and pass in a value from the registered `IApplicationInstanceInfo`: +To use the Steeltoe name for your application with OpenTelemetry, call `SetResourceBuilder` and pass in a value from the registered `IApplicationInstanceInfo`: ```csharp using OpenTelemetry.Resources; @@ -98,51 +107,53 @@ builder.Services.ConfigureOpenTelemetryTracerProvider((serviceProvider, tracerPr }); ``` -The above example assumes you are already using some other Steeltoe component which adds `IApplicationInstanceInfo` to the IoC container. If that is not the case, there are two steps to take to register the default implementation: +The above example assumes you are already using some other Steeltoe component that adds `IApplicationInstanceInfo` to the IoC container. If that is not the case, follow these steps to register the default implementation: -1. Add a NuGet package reference to `Steeltoe.Common` -1. Call `AddApplicationInstanceInfo` +1. Add a NuGet package reference to `Steeltoe.Common`. +2. Call `AddApplicationInstanceInfo`. -```csharp -using Steeltoe.Common.Extensions; + ```csharp + using Steeltoe.Common.Extensions; -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddApplicationInstanceInfo(); -``` + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddApplicationInstanceInfo(); + ``` ### Instrumenting applications -In order to maximize the benefit of collecting distributed traces, you'll want participation from the core components and frameworks of your application and some 3rd party components. -Some packages in the .NET ecosystem automatically support OpenTelemetry, others can be supported by the [collection of instrumentation libraries](https://opentelemetry.io/ecosystem/registry/?language=dotnet&component=instrumentation). -Steeltoe previously configured the instrumentation libraries for [HttpClient](#httpclient) and [ASP.NET Core](#aspnet-core). +To maximize the benefit of collecting distributed traces, ideally, you will have participation from the core components and frameworks of your application and some third-party components. +Some packages in the .NET ecosystem automatically support OpenTelemetry; others can be supported by the [collection of instrumentation libraries](https://opentelemetry.io/ecosystem/registry/?language=dotnet&component=instrumentation). +Steeltoe previously configured the instrumentation libraries for [ASP.NET Core](#aspnet-core) and [HttpClient](#httpclient). #### ASP.NET Core -To instrument requests coming into the application through ASP.NET Core, start by adding a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. +To instrument requests coming into the application through ASP.NET Core: -Next, add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: +1. Add a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. -```csharp -using OpenTelemetry.Trace; +1. Add the instrumentation to the `TracerProviderBuilder` by updating the existing call from the earlier example to: -builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddAspNetCoreInstrumentation()); -``` + ```csharp + using OpenTelemetry.Trace; -In order to replicate the Steeltoe setting `IngressIgnorePattern` (a Regex pattern describing which incoming requests to ignore), configure the `AspNetCoreTraceInstrumentationOptions`: + builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddAspNetCoreInstrumentation()); + ``` -```csharp -using System.Text.RegularExpressions; -using OpenTelemetry.Instrumentation.AspNetCore; +1. To replicate the Steeltoe setting `IngressIgnorePattern` (a Regex pattern describing which incoming requests to ignore), configure the `AspNetCoreTraceInstrumentationOptions`: -builder.Services.Configure(options => -{ - const string defaultIngressIgnorePattern = @"/actuator/.*|/cloudfoundryapplication/.*|.*\.png|.*\.css|.*\.js|.*\.html|/favicon.ico|.*\.gif"; - Regex ingressPathMatcher = new(defaultIngressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); - options.Filter += httpContext => !ingressPathMatcher.IsMatch(httpContext.Request.Path); -}); -``` + ```csharp + using System.Text.RegularExpressions; + using OpenTelemetry.Instrumentation.AspNetCore; + + builder.Services.Configure(options => + { + const string defaultIngressIgnorePattern = @"/actuator/.*|/cloudfoundryapplication/.*|.*\.png|.*\.css|.*\.js|.*\.html|/favicon.ico|.*\.gif"; + Regex ingressPathMatcher = new(defaultIngressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); + options.Filter += httpContext => !ingressPathMatcher.IsMatch(httpContext.Request.Path); + }); + ``` -As an alternative to using a regular expression, you can list out the paths to ignore in the Filter property (`Filter` is a `Func?`): +Alternatively, rather than using a regular expression, you can list the paths to ignore in the Filter property (`Filter` is a `Func?`): ```csharp using OpenTelemetry.Instrumentation.AspNetCore; @@ -157,84 +168,93 @@ builder.Services.Configure(options => > [!TIP] > By default, the ASP.NET Core instrumentation does not filter out any requests. -> The latter approach above may quickly prove unwieldy if there are many patterns to ignore, such as when listing many file types. +> The alternative approach described can quickly prove unwieldy if there are many patterns to ignore, such as when listing many file types. -To learn more about ASP.NET Core instrumentation for OpenTelemetry see [the documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore). +To learn more about ASP.NET Core instrumentation for OpenTelemetry see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore). #### HttpClient -To instrument requests leaving the application through `HttpClient`, start by adding a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. +To instrument requests leaving the application through `HttpClient`: -Next, add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: +1. Add a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. -```csharp -using OpenTelemetry.Trace; +1. Add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: -builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddHttpClientInstrumentation()); -``` + ```csharp + using OpenTelemetry.Trace; -In order to replicate the Steeltoe setting `EgressIgnorePattern` (a Regex pattern describing which outgoing HTTP requests to ignore), configure the `HttpClientTraceInstrumentationOptions`: + builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddHttpClientInstrumentation()); + ``` -```csharp -using OpenTelemetry.Instrumentation.Http; -using System.Text.RegularExpressions; +1. To replicate the Steeltoe setting `EgressIgnorePattern` (a Regex pattern describing which outgoing HTTP requests to ignore), configure the `HttpClientTraceInstrumentationOptions`: -builder.Services.Configure(options => -{ - const string defaultEgressIgnorePattern = "/api/v2/spans|/v2/apps/.*/permissions"; - Regex egressPathMatcher = new(defaultEgressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); - options.FilterHttpRequestMessage += httpRequestMessage => !egressPathMatcher.IsMatch(httpRequestMessage.RequestUri?.PathAndQuery ?? string.Empty); -}); -``` + ```csharp + using OpenTelemetry.Instrumentation.Http; + using System.Text.RegularExpressions; + + builder.Services.Configure(options => + { + const string defaultEgressIgnorePattern = "/api/v2/spans|/v2/apps/.*/permissions"; + Regex egressPathMatcher = new(defaultEgressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); + options.FilterHttpRequestMessage += httpRequestMessage => !egressPathMatcher.IsMatch(httpRequestMessage.RequestUri?.PathAndQuery ?? string.Empty); + }); + ``` -To learn more about HttpClient instrumentation for OpenTelemetry see [the documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http). +To learn more about HttpClient instrumentation for OpenTelemetry see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http). ### Propagating Trace Context By default, OpenTelemetry uses the [W3C trace context](https://github.com/w3c/trace-context) for propagating traces. Some systems like Cloud Foundry may still be configured for the Zipkin standard of [B3 propagation](https://github.com/openzipkin/b3-propagation). -In order to use B3 propagation, add a reference to the `OpenTelemetry.Extensions.Propagators` NuGet package. +To use B3 propagation: -Next, let the compiler know that the `B3Propagator` should come from the package reference you just added (rather than the deprecated class found in `OpenTelemetry.Context.Propagation`): +1. Add a reference to the `OpenTelemetry.Extensions.Propagators` NuGet package. -```csharp -using B3Propagator = OpenTelemetry.Extensions.Propagators.B3Propagator; -``` +1. Let the compiler know that the `B3Propagator` should come from the package reference you just added (rather than the deprecated class found in `OpenTelemetry.Context.Propagation`): -Finally, register a `CompositeTextMapPropagator` that includes the `B3Propagator` and `BaggagePropagator`: + ```csharp + using B3Propagator = OpenTelemetry.Extensions.Propagators.B3Propagator; + ``` -```csharp -using OpenTelemetry; -using OpenTelemetry.Context.Propagation; -using OpenTelemetry.Trace; +2. Register a `CompositeTextMapPropagator` that includes the `B3Propagator` and `BaggagePropagator`: -builder.Services.ConfigureOpenTelemetryTracerProvider((_, _) => -{ - List propagators = - [ - new B3Propagator(), - new BaggagePropagator() - ]; + ```csharp + using OpenTelemetry; + using OpenTelemetry.Context.Propagation; + using OpenTelemetry.Trace; - Sdk.SetDefaultTextMapPropagator(new CompositeTextMapPropagator(propagators)); -}); -``` + builder.Services.ConfigureOpenTelemetryTracerProvider((_, _) => + { + List propagators = + [ + new B3Propagator(), + new BaggagePropagator() + ]; + + Sdk.SetDefaultTextMapPropagator(new CompositeTextMapPropagator(propagators)); + }); + ``` ### Exporting Distributed Traces -Previous versions of Steeltoe could automatically configure several different trace exporters, including [Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Zipkin), [OpenTelemetryProtocol (OTLP)](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol) and Jaeger. -The Jaeger exporter has been deprecated in favor of OTLP, which was only minimally configured by Steeltoe and is better described by [the official OTLP exporter documentation](https://opentelemetry.io/docs/languages/net/exporters/#otlp). +Previous versions of Steeltoe could automatically configure several different trace exporters, including: + +* [Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Zipkin) +* [OpenTelemetryProtocol (OTLP)](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol) +* Jaeger. The Jaeger exporter has been deprecated in favor of OTLP, which was only minimally configured by Steeltoe. For more information, see the [OTLP exporter documentation](https://opentelemetry.io/docs/languages/net/exporters/#otlp). #### Zipkin Server -To use the Zipkin Exporter, add a reference to the `OpenTelemetry.Exporter.Zipkin` NuGet package. +To use the Zipkin Exporter: -Next, use the extension method `AddZipkinExporter` by updating the existing call from above to: +1. Add a reference to the `OpenTelemetry.Exporter.Zipkin` NuGet package. -```csharp -builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddZipkinExporter()); -``` +1. Use the extension method `AddZipkinExporter` by updating the existing call from above to: + + ```csharp + builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddZipkinExporter()); + ``` The Zipkin options class `ZipkinExporterOptions` works nearly the same as Steeltoe settings with the same names in previous releases: @@ -250,4 +270,4 @@ builder.Services.Configure(options => ``` > [!TIP] -> The Zipkin endpoint can also be set with the environment variable "OTEL_EXPORTER_ZIPKIN_ENDPOINT". +> The Zipkin endpoint can also be set with the environment variable `OTEL_EXPORTER_ZIPKIN_ENDPOINT`. From 8a9271feb9c08c8e8d04222a194f7e3222696c38 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Fri, 28 Feb 2025 07:47:19 -0800 Subject: [PATCH 09/43] full edit dynamic logging topics --- api/v4/logging/dynamic-console-logging.md | 19 +++++++++++-------- api/v4/logging/dynamic-serilog-logging.md | 19 ++++++++++--------- api/v4/logging/index.md | 2 +- 3 files changed, 22 insertions(+), 18 deletions(-) diff --git a/api/v4/logging/dynamic-console-logging.md b/api/v4/logging/dynamic-console-logging.md index 381567a0..f82549ba 100644 --- a/api/v4/logging/dynamic-console-logging.md +++ b/api/v4/logging/dynamic-console-logging.md @@ -1,31 +1,34 @@ # Dynamic Console Logging -This logging provider is a wrapper around the [Microsoft Console Logger](https://learn.microsoft.com/dotnet/core/extensions/logging-providers#console). It allows for querying the active loggers and their minimum levels, as well as then modifying the levels dynamically at runtime via the [loggers actuator](../management/loggers.md). +This logging provider is a wrapper around the [Microsoft Console Logger](https://learn.microsoft.com/dotnet/core/extensions/logging-providers#console). It allows you to: + +* Query the active loggers and their minimum levels +* Modify the levels dynamically at runtime using the [loggers actuator](../management/loggers.md) > [!CAUTION] > External tool integration involves sending the fully-qualified logger name over HTTP. Avoid using colons in the name of a logger to prevent invalid HTTP requests. ## Usage -Before starting to use Steeltoe provider, you should know how [Logging in .NET](https://learn.microsoft.com/aspnet/core/fundamentals/logging) works, as Steeltoe provides nothing more than a wrapper around the existing Microsoft console logger. +Before starting to use Steeltoe provider, you should know how [Logging in .NET](https://learn.microsoft.com/aspnet/core/fundamentals/logging) works; Steeltoe provides nothing more than a wrapper around the existing Microsoft console logger. -To use the Steeltoe logging provider, you need to: +To use the Steeltoe logging provider: 1. Add the appropriate NuGet package reference to your project. -1. Configure logging settings. -1. Add the dynamic logging provider to the logging builder. +2. Configure logging settings. +3. Add the dynamic logging provider to the logging builder. ### Add NuGet References -To use the logging provider, you need to add a reference to the `Steeltoe.Logging.DynamicConsole` NuGet package. +To use the logging provider, add a reference to the `Steeltoe.Logging.DynamicConsole` NuGet package. ### Configure Settings -As mentioned earlier, the Steeltoe Logging provider is a wrapper around the Microsoft Console logging provider. Consequently, you can configure it the same way you would the Microsoft provider. For more details on how this is done, see [Configure logging](https://learn.microsoft.com/aspnet/core/fundamentals/logging#configure-logging). +The Steeltoe Logging provider is a wrapper around the Microsoft Console logging provider, so you can configure it the same way you would the Microsoft provider. For more details about how to do this, see [Configure logging](https://learn.microsoft.com/aspnet/core/fundamentals/logging#configure-logging). ### Add the Logging Provider -To use the provider, you need to add it to the logging builder by using the `AddDynamicConsole()` extension method: +To use the provider, add it to the logging builder by using the `AddDynamicConsole()` extension method: ```csharp using Steeltoe.Logging.DynamicConsole; diff --git a/api/v4/logging/dynamic-serilog-logging.md b/api/v4/logging/dynamic-serilog-logging.md index 6ee13c07..e4880b12 100644 --- a/api/v4/logging/dynamic-serilog-logging.md +++ b/api/v4/logging/dynamic-serilog-logging.md @@ -1,22 +1,22 @@ # Dynamic Serilog Logging -This logging provider integrates with [Serilog](https://serilog.net/). It enables logger minimum levels configured via Serilog to be queried and modified at runtime via the [loggers actuator](../management/loggers.md). +This logging provider integrates with [Serilog](https://serilog.net/). It enables logger minimum levels configured through Serilog to be queried and modified at runtime using the [loggers actuator](../management/loggers.md). ## Usage -To use the Serilog Dynamic Logger, you need to do the following: +To use the Serilog Dynamic Logger, do the following: 1. Add the appropriate NuGet package reference to your project. -1. Configure Logging settings. -1. Add the Serilog Dynamic Logger to the logging builder. +2. Configure Logging settings. +3. Add the Serilog Dynamic Logger to the logging builder. ### Add NuGet References -To use the logging provider, you need to add a reference to the `Steeltoe.Logging.DynamicSerilog` NuGet package. +To use the logging provider, add a reference to the `Steeltoe.Logging.DynamicSerilog` NuGet package. ### Configure Settings -As mentioned earlier, the Serilog Dynamic Logger provider extends Serilog. Consequently, you can configure it the same way you would Serilog. For more details on how this is done, see [Serilog-Settings-Configuration](https://github.com/serilog/serilog-settings-configuration). +The Serilog Dynamic Logger provider extends Serilog, so you can configure it the same way you would Serilog. For more information, see [Serilog-Settings-Configuration](https://github.com/serilog/serilog-settings-configuration). ```json { @@ -60,7 +60,7 @@ var serilogConfiguration = new LoggerConfiguration() ### Add Serilog Dynamic Logger -To use this logging provider, you need to add it to the logging builder by using the `AddDynamicSerilog()` extension method: +To use this logging provider, add it to the logging builder by using the `AddDynamicSerilog()` extension method: ```csharp using Steeltoe.Logging.DynamicSerilog; @@ -70,13 +70,14 @@ builder.Logging.AddDynamicSerilog(); ``` If you built the Serilog configuration from code, use the appropriate overload instead: + ```csharp builder.Logging.AddDynamicSerilog(serilogConfiguration); ``` ### Serilog API usage -Because dynamic logging is built on the `Microsoft.Extensions.Logging` abstractions, changing log levels dynamically **won't work** if you're using Serilog's static `Log` class directly. +Because dynamic logging is built on the `Microsoft.Extensions.Logging` abstractions, changing log levels dynamically **doesn't work** if you're using Serilog's static `Log` class directly. ```csharp using Serilog; @@ -103,7 +104,7 @@ var exampleLogger = loggerFactory.CreateLogger("Example"); exampleLogger.LogInformation("Hello from Example."); ``` -The Serilog dynamic logger supports the use of logger scopes, as well as Serilog's enrichers and destructuring. +The Serilog dynamic logger supports the use of logger scopes, and also Serilog's enrichers and destructuring. ```csharp using Serilog.Context; diff --git a/api/v4/logging/index.md b/api/v4/logging/index.md index 0422cbb9..f8f0be83 100644 --- a/api/v4/logging/index.md +++ b/api/v4/logging/index.md @@ -2,5 +2,5 @@ Steeltoe includes two logging providers that enhance existing logger libraries with support for managing minimum log levels at runtime through the [Steeltoe Management logger endpoint](../management/loggers.md) and [recording distributed trace information](../tracing/index.md#log-correlation). -* [Dynamic Console Logging](./dynamic-console-logging.md) works with `Microsoft.Extensions.Logging.Console`. +* [Dynamic Console Logging](./dynamic-console-logging.md) works with `Microsoft.Extensions.Logging.Console` * [Dynamic Serilog Logging](./dynamic-serilog-logging.md) works with `Serilog` From dc6556644d7a84a191d390761f49dd280ffd6623 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Fri, 28 Feb 2025 14:31:08 -0800 Subject: [PATCH 10/43] full edit management topics(1) + bulk Note wording change --- api/v4/configuration/decryption-provider.md | 2 +- api/v4/management/cloud-foundry.md | 2 +- api/v4/management/dbmigrations.md | 24 ++--- api/v4/management/env.md | 24 ++--- api/v4/management/health.md | 95 +++++++++-------- api/v4/management/heapdump.md | 33 +++--- api/v4/management/httpexchanges.md | 4 +- api/v4/management/hypermedia.md | 2 +- api/v4/management/info.md | 2 +- api/v4/management/loggers.md | 2 +- api/v4/management/mappings.md | 2 +- api/v4/management/refresh.md | 2 +- api/v4/management/services.md | 2 +- api/v4/management/tasks.md | 2 +- api/v4/management/threaddump.md | 4 +- api/v4/management/using-endpoints.md | 107 +++++++++++--------- api/v4/tracing/index.md | 2 +- 17 files changed, 168 insertions(+), 143 deletions(-) diff --git a/api/v4/configuration/decryption-provider.md b/api/v4/configuration/decryption-provider.md index 89a55b28..d664c700 100644 --- a/api/v4/configuration/decryption-provider.md +++ b/api/v4/configuration/decryption-provider.md @@ -107,5 +107,5 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddDecryption(new ExampleTextDecryptor(), NullLoggerFactory.Instance); ``` -> [!WARNING] +> [!CAUTION] > Creating encryption algorithms is notoriously difficult. Use this only if you know what you are doing. diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 3781c1e5..12c1aa74 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -48,7 +48,7 @@ builder.Services.AddCloudFoundryActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ### Cross Origin Resource Sharing diff --git a/api/v4/management/dbmigrations.md b/api/v4/management/dbmigrations.md index 5f9e24e4..9731a3d8 100644 --- a/api/v4/management/dbmigrations.md +++ b/api/v4/management/dbmigrations.md @@ -1,9 +1,9 @@ # Database Migrations -The Steeltoe Database Migrations endpoint exposes information about database migrations that are available to an application's data source that has been built with Entity Framework Core (EF Core). EF Core migrations give developers the ability to update an application's database schema while staying consistent with the application's data model without removing any existing data. +The Steeltoe Database Migrations endpoint exposes information about database migrations that are available to an application's data source that has been built with Entity Framework Core (EF Core). EF Core migrations give developers the ability to update an application's database schema while staying consistent with the application's data model, and without removing any existing data. > [!NOTE] -> Please review Microsoft's [EF Core Migrations Overview](https://learn.microsoft.com/ef/core/managing-schemas/migrations) for more in-depth information. +> For more detailed information, see [EF Core Migrations Overview](https://learn.microsoft.com/ef/core/managing-schemas/migrations) in the Microsoft documentation. ## Configure Settings @@ -11,19 +11,19 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:DbMigrations:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `dbmigrations` | -| `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 the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `dbmigrations` | +| `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 | `GET` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/dbmigrations`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddDbMigrationsActuator` extension method. @@ -37,14 +37,14 @@ builder.Services.AddDbMigrationsActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of objects representing each registered `DbContext` along with its migrations, grouped by status (pending or applied). -The response will always be returned as JSON, like this: +The response is always returned as JSON, as shown here: ```json { diff --git a/api/v4/management/env.md b/api/v4/management/env.md index 25eb7e47..e6596b59 100644 --- a/api/v4/management/env.md +++ b/api/v4/management/env.md @@ -8,22 +8,22 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Env:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `env` | -| `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 the endpoint is exposed at. | `GET` | -| `KeysToSanitize` | An array of keys to sanitize. [^1] | `[ "password", "secret", "key", "token", ".*credentials.*", "vcap_services" ]` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `env` | +| `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 | `GET` | +| `KeysToSanitize` | An array of keys to sanitize [^1] | `[ "password", "secret", "key", "token", ".*credentials.*", "vcap_services" ]` | [^1]: A key can be a simple string that the property must end with, or a regular expression. A case-insensitive match is always performed. Use a single-element empty string to disable sanitization. ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/env`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddEnvironmentActuator` extension method. @@ -36,15 +36,15 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddEnvironmentActuator(); ``` -> [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> [!NOTE] +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of objects representing information from `IConfiguration`. -The response will always be returned as JSON, like this: +The response is always returned as JSON, like this: ```json { diff --git a/api/v4/management/health.md b/api/v4/management/health.md index ca5bfdf5..adfd090f 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -5,9 +5,9 @@ It is often used to monitor software and alert someone if a production system go Health information is collected from all `IHealthContributor` implementations registered in the application, as well as from [ASP.NET Core Health Checks](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks). -Steeltoe includes several contributors out of the box that you can use. +Steeltoe includes several contributors, out-of-the-box, that you can use. Other Steeltoe components typically add their own contributors where applicable. -Also, and perhaps more importantly, you can write your own. +In addition, you can write your own. By default, the final application health state is computed by the registered `IHealthAggregator` implementation. It is responsible for sorting out all of the returned statuses from each `IHealthContributor` and [`IHealthCheck`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.diagnostics.healthchecks.ihealthcheck) and deriving an overall application health state. @@ -19,26 +19,29 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Health:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `health` | -| `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 the endpoint is exposed at. | `GET` | -| `ShowComponents` | Whether health check components should be included in the response. | `Never` | -| `ShowDetails` | Whether details of health check components should be included in the response. | `Never` | -| `Claim` | The claim required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized`. | | -| `Role` | The role required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized`. | | - -The depth of information exposed by the health endpoint depends on the `ShowComponents` and `ShowDetails` properties, which can both be configured with one of the following values: - -| Name | Description | -| --- | --- | -| `Never` | Never shown. | -| `WhenAuthorized` | Shown only to authorized users. | -| `Always` | Always shown. | - -`ShowDetails` only has an effect when `ShowComponents` is set to `Always`, or `WhenAuthorized` and the request is authorized. +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `health` | +| `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 in which the endpoint is exposed | `GET` | +| `ShowComponents` | Whether health check components should be included in the response | `Never` | +| `ShowDetails` | Whether details of health check components should be included in the response | `Never` | +| `Claim` | The claim required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized` | | +| `Role` | The role required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized` | | + +The depth of information exposed by the health endpoint depends on the `ShowComponents` and `ShowDetails` properties; both be configured with one of the following values: + +| Name | Description | +| ------- | ----------- | +| `Never` | Never shown | +| `WhenAuthorized` | Shown only to authorized users | +| `Always` | Always shown | + +`ShowDetails` has an effect only when `ShowComponents` is set to: + +* `Always` +* `WhenAuthorized` if the request is authorized Authorized users can be configured by setting `Claim` or `Role`. A user is considered to be authorized when they are in the given role or have the specified claim. @@ -63,10 +66,10 @@ The following example uses `Management:Endpoints:Health:Claim`: ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/health`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHealthActuator` extension method. @@ -80,12 +83,12 @@ builder.Services.AddHealthActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. By default, the health status is reflected in the HTTP response status code. For example, when a health check fails, the response status code is `503 Service Unavailable`. -The configuration key `Management:Endpoints:UseStatusCodeFromResponse` can be set to `false`, which makes the health response status code always be `200 OK`. +The configuration key `Management:Endpoints:UseStatusCodeFromResponse` can be set to `false`, which makes the health check always respond with status code `200 OK`. Clients can overrule this per request by sending an `X-Use-Status-Code-From-Response` HTTP header with the value `true` or `false`. > [!TIP] @@ -112,7 +115,7 @@ Clients can overrule this per request by sending an `X-Use-Status-Code-From-Resp This endpoint returns the top-level status, along with the details of the contributors and checks. -The response will always be returned as JSON, and this is the default value: +The response is always returned as JSON, and this is the default value: ```json { @@ -149,7 +152,7 @@ When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `Whe ## Health Groups -Should you need to check application health based on a subset of health contributors, you may specify the name of the grouping and a comma-separated list of contributors to include like this: +If you need to check application health based on a subset of health contributors, you can specify the name of the grouping and a comma-separated list of contributors to include: ```json { @@ -167,9 +170,9 @@ Should you need to check application health based on a subset of health contribu } ``` -While group names are case-sensitive, the entries in `Include` are case-insensitive and will only activate health contributors with a matching `Id`, and/or ASP.NET health check registrations with a matching name. +While group names are case-sensitive, the entries in `Include` are case-insensitive and activate only health contributors with a matching `Id`, and/or ASP.NET health check registrations with a matching name. -For any group that has been defined, you may access health information from the group by appending the group name to the HTTP request URL. For example: `/actuator/health/example-group`. +For any group that has been defined, you can access health information from the group by appending the group name to the HTTP request URL. For example: `/actuator/health/example-group`. `ShowComponents` and `ShowDetails` can also be set at the group level, overriding the settings found at the endpoint level. @@ -198,15 +201,15 @@ For any group that has been defined, you may access health information from the ### Kubernetes Health Groups Applications deployed on Kubernetes can provide information about their internal state with [Container Probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). -Depending on your [Kubernetes configuration](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/), the kubelet will call those probes and react to the result. +Depending on your [Kubernetes configuration](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/), the kubelet calls those probes and reacts to the result. Steeltoe provides an [`ApplicationAvailability`](https://github.com/SteeltoeOSS/Steeltoe/blob/main/src/Management/src/Endpoint/Actuators/Health/Availability/ApplicationAvailability.cs) class for managing various types of application state. -Out of the box, support is provided for Liveness and Readiness, where each is exposed in a corresponding `IHealthContributor` and health group. -While these health contributors are included, they are disabled by default and must be enabled in configuration (as demonstrated in the example below). +Support is provided, out of the box, for Liveness and Readiness, where each is exposed in a corresponding `IHealthContributor` and health group. +While these health contributors are included, they are disabled by default and must be enabled in the configuration (as shown in the example below). To change the health contributors that are included in either of the two built-in groups, use the same style of configuration described above. -Please note that this will _replace_ these groupings, so if you would like to _add_ an `IHealthContributor` you will need to include the original entry. -These entries demonstrate enabling the probes, their groups and including disk space in both groups: +Note that this _replaces_ these groupings, so if you want to _add_ an `IHealthContributor`, you must include the original entry. +These entries demonstrate enabling the probes and their groups, and specifies including disk space in both groups: ```json { @@ -235,22 +238,27 @@ These entries demonstrate enabling the probes, their groups and including disk s #### Liveness -The "Liveness" state of an application instance tells whether its internal state allows it to work correctly, or recover by itself if it's currently failing. A broken "Liveness" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application. +The "Liveness" state of an application instance tells whether its internal state allows it to work correctly, or recover itself if it's currently failing. A broken "Liveness" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application. -Out of the box, any of Steeltoe's extension methods that set up the health actuator will initialize the liveness state `LivenessState.Correct`. The only other defined state for liveness is `LivenessState.Broken`, though Steeltoe code does not currently cover any conditions that set this state. +Out of the box, any of Steeltoe's extension methods that set up the health actuator initialize the liveness state, `LivenessState.Correct`. The only other defined state for liveness is `LivenessState.Broken`, though Steeltoe code does not currently cover any conditions that set this state. -> [!NOTE] +> [!CAUTION] > In general, the "Liveness" state should not depend on external system checks such as a database, queue, or cache server. Including checks on external systems could trigger massive restarts and cascading failures across the platform. #### Readiness The "Readiness" state of an application instance describes whether the application is ready to handle traffic. A failing "Readiness" state tells the platform that it should not route traffic to the application instance. -Out of the box, any of Steeltoe's extension methods that set up the health actuator will also register a callback on [`ApplicationStarted`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstarted) to initialize the readiness state to `AcceptingTraffic` when the application has started, and register a callback on [`ApplicationStopping`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstopping) to change the state to `RefusingTraffic` when the application begins to shut down. These are the only defined states for this availability type. +Out of the box, any of Steeltoe's extension methods that set up the health actuator also: + +* Registers a callback on [`ApplicationStarted`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstarted) to initialize the readiness state to `AcceptingTraffic` when the application has started +* Registers a callback on [`ApplicationStopping`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstopping) to change the state to `RefusingTraffic` when the application begins to shut down + +These are the only defined states for this availability type. #### Managing Application Availability State -Application components can retrieve the current availability state at any time, by requesting `ApplicationAvailability` from the dependency injection container and calling methods on it: +Application components can retrieve the current availability state at any time by requesting `ApplicationAvailability` from the dependency injection container and calling methods on it: ```csharp [ApiController] @@ -285,7 +293,10 @@ app.Run(); ## Creating a Custom Health Contributor -If you wish to provide custom health information for your application, create a class that implements the `IHealthContributor` interface and then add it to the service container. +If you want to provide custom health information for your application: + +1. Create a class that implements the `IHealthContributor` interface. +2. Add the new class to the service container. The following example contributor always returns a `HealthStatus` of `WARNING`: @@ -355,7 +366,7 @@ When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `Whe ## ASP NET Core Health Checks -ASP.NET Core also offers [middleware and libraries](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks) and abstractions for reporting health. There is wide community support for these abstractions from libraries such as [AspNetCore.Diagnostics.HealthChecks](https://github.com/Xabaril/AspNetCore.Diagnostics.HealthChecks). You can use these community-provided health checks and make them available over the health actuator endpoint (for integration with Cloud Foundry or any other infrastructure that depends on this format). In addition, Steeltoe Connectors expose functionality to get the connection string, which is needed to set up these community health checks. +ASP.NET Core offers [middleware and libraries](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks) and abstractions for reporting health. There is wide community support for these abstractions from libraries such as [AspNetCore.Diagnostics.HealthChecks](https://github.com/Xabaril/AspNetCore.Diagnostics.HealthChecks). You can use these community-provided health checks and make them available using the health actuator endpoint (for integration with Cloud Foundry or any other infrastructure that depends on this format). In addition, Steeltoe Connectors expose functionality to get the connection string, which is needed to set up these community health checks. For example, to use the Steeltoe MySQL connector, but replace its health contributor with the ASP.NET Core community health check, use the following code in `Program.cs`: diff --git a/api/v4/management/heapdump.md b/api/v4/management/heapdump.md index 51cc6276..95356248 100644 --- a/api/v4/management/heapdump.md +++ b/api/v4/management/heapdump.md @@ -7,25 +7,32 @@ You can use the Steeltoe Heap Dump endpoint to capture and download a mini-dump The following table describes the configuration settings that you can apply to the endpoint. Each key must be prefixed with `Management:Endpoints:HeapDump:`. -| Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `heapdump` | -| `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 the endpoint is exposed at. | `GET` | -| `HeapDumpType` | Sets the type of heap dump to capture. | `Full` | +| Key | Description | Default | +| --------- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `heapdump` | +| `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 | `GET` | +| `HeapDumpType` | Sets the type of heap dump to capture | `Full` | The `HeapDumpType` setting is supported on Linux and Windows only. -Acceptable values are `Normal`, `WithHeap`, `Triage`, and `Full`. -On macOS, this setting is ignored and a gcdump is always captured. +Acceptable values are: + +* `Normal` +* `WithHeap` +* `Triage` +* `Full` + +> [!IMPORTANT] +> On macOS, this setting is ignored and a gcdump is always captured. ## Enable HTTP Access The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. The default path is `/actuator/heapdump`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHeapDumpActuator` extension method. @@ -38,6 +45,6 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHeapDumpActuator(); ``` -> [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> [!NOTE] +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/httpexchanges.md b/api/v4/management/httpexchanges.md index efa337e7..c8fe315b 100644 --- a/api/v4/management/httpexchanges.md +++ b/api/v4/management/httpexchanges.md @@ -103,14 +103,14 @@ builder.Services.AddHttpExchangesActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns an array of exchanges. -The response will always be returned as JSON, like this: +The response is always returned as JSON, like this: ```json { diff --git a/api/v4/management/hypermedia.md b/api/v4/management/hypermedia.md index 11b60d4d..d4c4849b 100644 --- a/api/v4/management/hypermedia.md +++ b/api/v4/management/hypermedia.md @@ -58,7 +58,7 @@ builder.Services.AddHypermediaActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/info.md b/api/v4/management/info.md index 81ea051a..737036ce 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -38,7 +38,7 @@ builder.Services.AddInfoActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Built-in Contributors diff --git a/api/v4/management/loggers.md b/api/v4/management/loggers.md index ff1ee6ef..da1f1068 100644 --- a/api/v4/management/loggers.md +++ b/api/v4/management/loggers.md @@ -36,7 +36,7 @@ builder.Services.AddLoggersActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. > [!TIP] diff --git a/api/v4/management/mappings.md b/api/v4/management/mappings.md index 405dd2b0..3d9be6bf 100644 --- a/api/v4/management/mappings.md +++ b/api/v4/management/mappings.md @@ -35,7 +35,7 @@ builder.Services.AddRouteMappingsActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/refresh.md b/api/v4/management/refresh.md index d604ec76..32035a02 100644 --- a/api/v4/management/refresh.md +++ b/api/v4/management/refresh.md @@ -40,7 +40,7 @@ builder.Services.AddRefreshActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/services.md b/api/v4/management/services.md index 6807f661..0186d4f1 100644 --- a/api/v4/management/services.md +++ b/api/v4/management/services.md @@ -37,7 +37,7 @@ builder.Services.AddServicesActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/tasks.md b/api/v4/management/tasks.md index 080088e4..cddfc596 100644 --- a/api/v4/management/tasks.md +++ b/api/v4/management/tasks.md @@ -42,7 +42,7 @@ public class ExampleTask(ILogger logger) : IApplicationTask } ``` -> [!TIP] +> [!NOTE] > Steeltoe includes the `MigrateDbContextTask` task, which runs database migrations with Entity Framework Core. > It requires a reference to the `Steeltoe.Connectors.EntityFrameworkCore` NuGet package. diff --git a/api/v4/management/threaddump.md b/api/v4/management/threaddump.md index 742ff093..5abd5972 100644 --- a/api/v4/management/threaddump.md +++ b/api/v4/management/threaddump.md @@ -36,8 +36,8 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddThreadDumpActuator(); ``` -> [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, +> [!NOTE] +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/using-endpoints.md b/api/v4/management/using-endpoints.md index 91ff220b..d469bbc3 100644 --- a/api/v4/management/using-endpoints.md +++ b/api/v4/management/using-endpoints.md @@ -6,35 +6,35 @@ Steeltoe provides a basic set of HTTP endpoints (also known as actuators), which In this section, it is helpful to understand the following: -* How the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works. -* How the [ASP.NET Core Startup](https://learn.microsoft.com/aspnet/core/fundamentals/startup) is used to register services and middleware. +* How the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works +* How the [ASP.NET Core Startup](https://learn.microsoft.com/aspnet/core/fundamentals/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](./cloud-foundry.md) | Enables the management endpoint integration with Cloud Foundry. | -| [dbmigrations](./dbmigrations.md) | Provides the ability to see current and pending database migrations for an application data source. | -| [env](./env.md) | Reports the keys and values from the application's configuration. | -| [health](./health.md) | Customizable endpoint that gathers application health information. | -| [heapdump](./heapdump.md) | Generates and downloads a mini-dump of the application (Windows and Linux only). | -| [httpexchanges](./httpexchanges.md) | Gathers recently processed HTTP requests. | -| [hypermedia](./hypermedia.md) | Lists the active management endpoints and their links. | -| [info](./info.md) | Customizable endpoint that gathers arbitrary application information (such as app version). | -| [loggers](./loggers.md) | Gathers existing logger categories and allows changing their minimum levels at runtime. | -| [mappings](./mappings.md) | Reports the configured ASP.NET routes and route templates. | -| [prometheus](./prometheus.md) | Exposes metrics collected via built-in instrumentation of various aspects of the application in the Prometheus format. | -| [refresh](./refresh.md) | Triggers a reload of the application configuration. | -| [services](./services.md) | Lists the contents of the .NET dependency injection service container. | -| [threaddump](./threaddump.md) | Generates and reports a snapshot of the application's threads (Windows only). | +| ID |Description | +| --- | ---------- | +| [cloudfoundry](./cloud-foundry.md) | Enables the management endpoint integration with Cloud Foundry | +| [dbmigrations](./dbmigrations.md) | Provides the ability to see current and pending database migrations for an application data source | +| [env](./env.md) | Reports the keys and values from the application configuration | +| [health](./health.md) | Customizable endpoint that gathers application health information | +| [heapdump](./heapdump.md) | Generates and downloads a mini-dump of the application (Windows and Linux only) | +| [httpexchanges](./httpexchanges.md) | Gathers recently processed HTTP requests | +| [hypermedia](./hypermedia.md) | Lists the active management endpoints and their links | +| [info](./info.md) | Customizable endpoint that gathers arbitrary application information (such as app version) | +| [loggers](./loggers.md) | Gathers existing logger categories and allows changing their minimum levels at runtime | +| [mappings](./mappings.md) | Reports the configured ASP.NET routes and route templates | +| [prometheus](./prometheus.md) | Exposes metrics collected using built-in instrumentation of various aspects of the application in the Prometheus format | +| [refresh](./refresh.md) | Triggers a reload of the application configuration | +| [services](./services.md) | Lists the contents of the .NET dependency injection service container | +| [threaddump](./threaddump.md) | 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, you need to add a reference to the `Steeltoe.Management.Endpoints` NuGet package. +To use the management endpoints, add a reference to the `Steeltoe.Management.Endpoints` NuGet package. ## Configure Global Settings @@ -47,37 +47,37 @@ Settings that you want to apply to specific endpoints should be placed under the 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. [^1] | | -| `SslEnabled` | Whether `Port` applies to HTTP or HTTPS requests. [^1] | `false` | -| `UseStatusCodeFromResponse` | Reflect the actuator outcome in the HTTP response status code. | `true` | -| `SerializerOptions` | Customize JSON serialization options. | use camelCase properties | -| `CustomJsonConverters` | Additional [`JsonConverter`](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/converters-how-to)s to use (see below). | | +| --- | ----------- | ------- | +| `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 [^1] | | +| `SslEnabled` | Whether `Port` applies to HTTP or HTTPS requests [^1] | `false` | +| `UseStatusCodeFromResponse` | Reflect the actuator outcome in the HTTP response status code | `true` | +| `SerializerOptions` | Customize JSON serialization options | use camelCase properties | +| `CustomJsonConverters` | Additional [`JsonConverter`](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/converters-how-to)s to use (see below) | | [^1]: Using an alternate port does not apply to `/cloudfoundryapplication` endpoints. > [!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` will return status code 200 instead. This switch does not affect the status code of responses outside of Steeltoe. +> 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 the endpoint is exposed at. | | +| --- | ----------- | ------- | +| `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 `JsonConverter`s can be used by adding the [assembly-qualified type](https://learn.microsoft.com/dotnet/api/system.type.assemblyqualifiedname"). -For example, to pretty-print all JSON and serialize `DateTime` values as epoch times: +For example, to pretty-print all JSON, and serialize `DateTime` values as epoch times: ```json { @@ -99,12 +99,12 @@ For example, to pretty-print all JSON and serialize `DateTime` values as epoch t 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 above must be prefixed with `Management:Endpoints:Actuator`. Use the actuator ID to specify the endpoint. -To expose all endpoints, `*` can be used. For example, to expose everything except `env` and `refresh`, use the following: +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: ```json "Management": { @@ -120,7 +120,7 @@ To expose all endpoints, `*` can be used. For example, to expose everything exce ``` > [!NOTE] -> When running on Cloud Foundry, exposure settings *only* have an effect on requests starting with `/actuator`. +> 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](./cloud-foundry.md#security). > Individual endpoints can be turned off by setting `Enabled` to `false`, which applies to both URLs. @@ -133,14 +133,15 @@ To expose any of the management endpoints over HTTP in an ASP.NET Core applicati 1. Add the actuator endpoint(s) to the service container. 1. Optional: Add any additional health/info contributors to the service container. 1. Optional: Customize the CORS policy. -1. Optional: Secure endpoints. +1. Optional: Secure the endpoints. 1. 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 [here](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/endpoints) and [here](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/)). -> Use the `Port` and `SslEnabled` settings described above to isolate management endpoints from regular application endpoints. +> 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](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/endpoints) and in +> [8 ways to set the URLs for an ASP.NET Core app](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/)). +> Use the `Port` and `SslEnabled` settings described earlier to isolate management endpoints from regular application endpoints. -The example below adds all actuators: +The following example adds all actuators: ```csharp using Steeltoe.Management.Endpoint.Actuators.All; @@ -149,9 +150,9 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddAllActuators(); ``` -> [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> [!NOTE] +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, +> which enables individually turning them on/off at runtime using configuration. Alternatively, individual actuators can be added: @@ -165,7 +166,7 @@ builder.Services.AddHypermediaActuator().AddLoggersActuator().AddRefreshActuator ``` > [!NOTE] -> `AddAllActuators()` and `AddLoggingActuator()` automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). To use [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md), be sure to do so *before* adding actuators. For example: +> Use `AddAllActuators()` and `AddLoggingActuator()` to automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). You must set up [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) *before* adding actuators. For example: > > ```csharp > using Steeltoe.Logging.DynamicSerilog; @@ -176,7 +177,7 @@ builder.Services.AddHypermediaActuator().AddLoggersActuator().AddRefreshActuator > builder.Services.AddAllActuators(); > ``` -## Adding additional contributors +## Adding contributors The `health` and `info` endpoints can be extended with custom contributors. For example: @@ -221,7 +222,7 @@ When `RequireAuthorization()` is called without arguments, the default profile i ## Overriding the middleware pipeline setup -All `Add*Actuator` methods provide an overload that takes a boolean `configureMiddleware`, which enables to skip adding middleware to the ASP.NET Core pipeline. +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. ```csharp @@ -242,7 +243,13 @@ app.UseActuatorEndpoints(); // maps the actuator endpoints await app.StartAsync(); ``` -While the order above must not be changed (and it's not recommended to leave out entries), additional middleware can be inserted as appropriate. +### 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 diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index 6f9cc394..bd985b95 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -269,5 +269,5 @@ builder.Services.Configure(options => }); ``` -> [!TIP] +> [!NOTE] > The Zipkin endpoint can also be set with the environment variable `OTEL_EXPORTER_ZIPKIN_ENDPOINT`. From 013ffde21ef2b8a108c111cd2047b8dbccebaea5 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Fri, 28 Feb 2025 14:43:12 -0800 Subject: [PATCH 11/43] change all TIP to NOTE --- api/v4/bootstrap/index.md | 4 ++-- api/v4/configuration/config-server-provider.md | 8 ++++---- api/v4/configuration/random-value-provider.md | 2 +- api/v4/discovery/discovering-services.md | 2 +- api/v4/discovery/initialize-discovery-client.md | 4 ++-- api/v4/discovery/netflix-eureka.md | 6 +++--- api/v4/management/cloud-foundry.md | 2 +- api/v4/management/dbmigrations.md | 2 +- api/v4/management/health.md | 4 ++-- api/v4/management/httpexchanges.md | 2 +- api/v4/management/hypermedia.md | 2 +- api/v4/management/info.md | 6 +++--- api/v4/management/loggers.md | 8 ++++---- api/v4/management/mappings.md | 2 +- api/v4/management/refresh.md | 2 +- api/v4/management/services.md | 2 +- api/v4/management/springbootadmin.md | 4 ++-- api/v4/management/tasks.md | 2 +- api/v4/management/threaddump.md | 2 +- api/v4/security/certificate.md | 10 +++++----- api/v4/security/jwt-bearer.md | 2 +- api/v4/security/redis-key-storage-provider.md | 4 ++-- api/v4/security/sso-open-id.md | 4 ++-- api/v4/tracing/index.md | 4 ++-- api/v4/welcome/common-steps.md | 2 +- 25 files changed, 46 insertions(+), 46 deletions(-) diff --git a/api/v4/bootstrap/index.md b/api/v4/bootstrap/index.md index 81806cc4..609f23b7 100644 --- a/api/v4/bootstrap/index.md +++ b/api/v4/bootstrap/index.md @@ -51,8 +51,8 @@ HashSet assemblyNamesToExclude = [SteeltoeAssemblyNames.ConfigurationCon builder.AddSteeltoe(assemblyNamesToExclude); ``` -> [!TIP] -> The static class `SteeltoeAssemblyNames` enables to easily find the name of any specific assembly to exclude. +> [!NOTE] +> The static class `SteeltoeAssemblyNames` enables you to easily find the name of any specific assembly to exclude. ## Logging inside Configuration Providers diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index 53076482..f91c27a6 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -35,7 +35,7 @@ The following example shows some provider settings that have been put in a JSON * `Spring:Application:Name` configures the "application name" to be `sample`. * `Spring:Cloud:Config:Uri` configures the address of the Config Server. -> [!TIP] +> [!NOTE] > The `Spring:Application:Name` key is also used by various other Steeltoe components. ```json @@ -88,7 +88,7 @@ As mentioned earlier, all settings should start with `Spring:Cloud:Config:`. | `Health:Enabled` | Enable or disable Config Server health check contributor | `true` | | `Health:TimeToLive` | Health check contributor cache time to live, in milliseconds | `300_000` (5 min) | -> [!TIP] +> [!NOTE] > If you use self-signed certificates on Cloud Foundry, you might run into certificate validation issues when pushing an application. > A quick way to work around this is to disable certificate validation until a proper solution can be put in place. @@ -158,7 +158,7 @@ When the `ConfigurationBuilder` builds the configuration, the Config Server clie If there are any errors or problems accessing the server, the application continues to initialize, but the values from the server are not retrieved. If this is not the behavior you want, set `Spring:Cloud:Config:FailFast` to `true`. After that is done, the application fails to start if problems occur during the retrieval. -> [!TIP] +> [!NOTE] > To diagnose startup errors, activate bootstrap logging as described in [Application Bootstrapping](../bootstrap/index.md#logging-inside-configuration-providers). After the configuration has been built, you can access the retrieved data directly by using `IConfiguration`. See the following example: @@ -284,5 +284,5 @@ Aside from PEM files, Steeltoe supports a single file in PKCS#12 format: } ``` -> [!TIP] +> [!NOTE] > A single certificate can be shared with both Config Server and Eureka by using the key `Certificates` instead of `Certificates:ConfigServer`. diff --git a/api/v4/configuration/random-value-provider.md b/api/v4/configuration/random-value-provider.md index 4b52cd4b..ed17681e 100644 --- a/api/v4/configuration/random-value-provider.md +++ b/api/v4/configuration/random-value-provider.md @@ -53,7 +53,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddRandomValueSource(); ``` -> [!TIP] +> [!NOTE] > To generate random values as part of using placeholders, add the random value provider to the builder *before* you add the placeholder resolver. ### Access Random Value Data diff --git a/api/v4/discovery/discovering-services.md b/api/v4/discovery/discovering-services.md index 74dd7a09..4e2857d2 100644 --- a/api/v4/discovery/discovering-services.md +++ b/api/v4/discovery/discovering-services.md @@ -160,7 +160,7 @@ To use this load balancer in service discovery, pass it to the `AddServiceDiscov builder.Services.AddHttpClient().AddServiceDiscovery(); ``` -> [!TIP] +> [!NOTE] > When caching is activated (see above), this load balancer stores the last-used instance index in the cache. > Combining it with a shared Redis cache ensures an even load distribution. diff --git a/api/v4/discovery/initialize-discovery-client.md b/api/v4/discovery/initialize-discovery-client.md index 102aeff2..b5bd68b2 100644 --- a/api/v4/discovery/initialize-discovery-client.md +++ b/api/v4/discovery/initialize-discovery-client.md @@ -37,8 +37,8 @@ builder.Services.AddConfigurationDiscoveryClient(); var app = builder.Build(); ``` -> [!TIP] -> Alternatively, `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration) can be used, which uses reflection to determine +> [!NOTE] +> Alternatively, you can use `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration), which uses reflection to determine > which discovery assemblies are loaded, adding the appropriate clients automatically. ## Client configuration diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 1e11a625..092a0305 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -31,7 +31,7 @@ For a complete understanding of the effects of many of these settings, we recomm In most cases, unless you are confident that you understand the effects of changing the values from their defaults, we recommend that you use the defaults. -> [!TIP] +> [!NOTE] > Since Steeltoe v4, most of these settings can be changed at runtime, which updates the Eureka server accordingly. ### General @@ -226,8 +226,8 @@ or: > [!NOTE] > To support certificate rotation, the configuration keys and the files on disk are automatically monitored for changes. -> [!TIP] -> A single certificate can be shared with both Config Server and Eureka, by using the key "Certificates" instead of "Certificates:Eureka". +> [!NOTE] +> A single certificate can be shared with both Config Server and Eureka, by using the key `Certificates` instead of `Certificates:Eureka`. ### Using custom HTTP headers diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 12c1aa74..81986777 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -47,7 +47,7 @@ builder.Configuration.AddCloudFoundry(); builder.Services.AddCloudFoundryActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/dbmigrations.md b/api/v4/management/dbmigrations.md index 9731a3d8..85403c4e 100644 --- a/api/v4/management/dbmigrations.md +++ b/api/v4/management/dbmigrations.md @@ -36,7 +36,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddDbMigrationsActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/health.md b/api/v4/management/health.md index adfd090f..7bef96b2 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -82,7 +82,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHealthActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. @@ -91,7 +91,7 @@ For example, when a health check fails, the response status code is `503 Service The configuration key `Management:Endpoints:UseStatusCodeFromResponse` can be set to `false`, which makes the health check always respond with status code `200 OK`. Clients can overrule this per request by sending an `X-Use-Status-Code-From-Response` HTTP header with the value `true` or `false`. -> [!TIP] +> [!NOTE] > By default, health contributors for disk space and ping are activated. They can be turned off through configuration: > > ```json diff --git a/api/v4/management/httpexchanges.md b/api/v4/management/httpexchanges.md index c8fe315b..2583c966 100644 --- a/api/v4/management/httpexchanges.md +++ b/api/v4/management/httpexchanges.md @@ -102,7 +102,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHttpExchangesActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/hypermedia.md b/api/v4/management/hypermedia.md index d4c4849b..7aa4666d 100644 --- a/api/v4/management/hypermedia.md +++ b/api/v4/management/hypermedia.md @@ -57,7 +57,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHypermediaActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/info.md b/api/v4/management/info.md index 737036ce..d432bb83 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -37,7 +37,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddInfoActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. @@ -62,7 +62,7 @@ This contributor exposes any values below the `Info` configuration key. For exam } ``` -> [!TIP] +> [!NOTE] > When combined with the [Placeholder Configuration Provider](../configuration/placeholder-provider.md), > compound configuration values can be exposed originating from other places in configuration. @@ -71,7 +71,7 @@ This contributor exposes any values below the `Info` configuration key. For exam Exposes information from the `git.properties` Spring Boot file, if available. Shows information from git, such as branch/tag name, commit hash, and remote. -> [!TIP] +> [!NOTE] > For an example of how to use this contributor within MSBuild using [GitInfo](https://github.com/devlooped/GitInfo), see the [Steeltoe Management sample](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src). ## Sample Output diff --git a/api/v4/management/loggers.md b/api/v4/management/loggers.md index da1f1068..ab74c371 100644 --- a/api/v4/management/loggers.md +++ b/api/v4/management/loggers.md @@ -35,11 +35,11 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddLoggersActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. -> [!TIP] +> [!NOTE] > When `AddLoggersActuator` is called, it tries to register [Dynamic Console Logging](../logging/dynamic-console-logging.md). > If you'd like to use Serilog instead, call `AddDynamicSerilog` *before* `AddLoggersActuator`. @@ -135,7 +135,7 @@ by sending a POST request to `/actuator/loggers/Steeltoe.Management` with the fo } ``` -> [!TIP] +> [!NOTE] > Because the logger category is part of the request URL, avoid using colons in the name to prevent invalid HTTP requests. To verify the change was applied, send a `GET` request to `/actuator/loggers` to see the updated loggers. @@ -203,5 +203,5 @@ The returned `ILogger` instances are wrapped as well, so that the minimum level When changes to `appsettings.json` are saved, existing loggers are updated with the new minimum levels, unless overridden. A reset of an overridden logger reverts to the updated level from `appsettings.json`. -> [!TIP] +> [!NOTE] > The Steeltoe dynamic logging provider can be combined with `BootstrapLoggerFactory` to upgrade loggers after startup. diff --git a/api/v4/management/mappings.md b/api/v4/management/mappings.md index 3d9be6bf..5988e472 100644 --- a/api/v4/management/mappings.md +++ b/api/v4/management/mappings.md @@ -34,7 +34,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddRouteMappingsActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/refresh.md b/api/v4/management/refresh.md index 32035a02..6eb9d32d 100644 --- a/api/v4/management/refresh.md +++ b/api/v4/management/refresh.md @@ -39,7 +39,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddRefreshActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/services.md b/api/v4/management/services.md index 0186d4f1..284305a2 100644 --- a/api/v4/management/services.md +++ b/api/v4/management/services.md @@ -36,7 +36,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddServicesActuator(); ``` -> [!TIP] +> [!NOTE] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators, > which enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/springbootadmin.md b/api/v4/management/springbootadmin.md index 9673347d..d0ec9826 100644 --- a/api/v4/management/springbootadmin.md +++ b/api/v4/management/springbootadmin.md @@ -59,7 +59,7 @@ a few additional steps are needed: For the server to report the app as "UP", you need to add at least the hypermedia and health actuators in `Program.cs`. -> [!TIP] +> [!NOTE] > You can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin) for testing purposes. Putting it all together, your `appsettings.Development.json` file should look like this: @@ -133,5 +133,5 @@ app.MapControllers(); app.Run(); ``` -> [!TIP] +> [!NOTE] > To see all the Spring Boot Admin features in action, replace the `Add*Actuator()` calls in `Program.cs` with `AddAllActuators()` and [expose all endpoints](./using-endpoints.md#exposing-endpoints). diff --git a/api/v4/management/tasks.md b/api/v4/management/tasks.md index cddfc596..12410a9c 100644 --- a/api/v4/management/tasks.md +++ b/api/v4/management/tasks.md @@ -115,7 +115,7 @@ Invoking the command on Cloud Foundry looks similar to this: cf run-task YourAppName "dotnet run -- RunTask=ExampleTaskName" --name ExampleTaskName ``` -> [!TIP] +> [!NOTE] > The command line configuration provider is added by default when using `WebApplication.CreateBuilder(args)`. > If the task does not fire when running from the command line with the `RunTask=` parameter, > verify that the configuration provider has been added for your application. diff --git a/api/v4/management/threaddump.md b/api/v4/management/threaddump.md index 5abd5972..88a96250 100644 --- a/api/v4/management/threaddump.md +++ b/api/v4/management/threaddump.md @@ -15,7 +15,7 @@ Each key must be prefixed with `Management:Endpoints:ThreadDump:`. | `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | | `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -> [!TIP] +> [!NOTE] > In version 4, the configuration key prefix for this endpoint changed from `Management:Endpoints:Dump:` to `Management:Endpoints:ThreadDump:` ## Enable HTTP Access diff --git a/api/v4/security/certificate.md b/api/v4/security/certificate.md index d563d67a..88cee6c5 100644 --- a/api/v4/security/certificate.md +++ b/api/v4/security/certificate.md @@ -78,7 +78,7 @@ builder.Services.AddAuthorizationBuilder() .AddOrgAndSpacePolicies(); ``` -> [!TIP] +> [!NOTE] > Steeltoe configures the certificate forwarding middleware to look for a certificate in the `X-Client-Cert` HTTP header. > To change the HTTP header name used for authorization, include it when registering the policy. For example: `.AddOrgAndSpacePolicies("X-Custom-Certificate-Header")`. @@ -112,8 +112,8 @@ app.UseCertificateAuthorization(); As implied by the name of the extension method `AddOrgAndSpacePolicies` from the previous section on this page, Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints by using the standard ASP.NET Core `Authorize` attribute with these security policies. -> [!TIP] -> If needed, see the Microsoft documentation on [authorization in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/authorization/introduction) for a better understanding of how to use these attributes. +> [!NOTE] +> If needed, see the Microsoft documentation about [authorization in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/authorization/introduction) for a better understanding of how to use these attributes. The following example shows a controller using the security attributes with the included policies: @@ -163,8 +163,8 @@ In order to use app instance identity certificates in a client application, serv For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` named `AddAppInstanceIdentityCertificate`. This method invokes code that handles loading certificates from paths defined in the application's configuration, monitors those file paths and their content for changes, and places the certificate in an HTTP header named `X-Client-Cert` on all outbound requests. -> [!TIP] -> If needed, see the Microsoft documentation on [IHttpClientFactory documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests) for details. +> [!NOTE] +> If needed, see the Microsoft documentation about [IHttpClientFactory](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests) for details. ```csharp using Steeltoe.Security.Authorization.Certificate; diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index 228cfd50..07581b05 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -119,7 +119,7 @@ app.MapDefaultControllerRoute(); app.Run(); ``` -> [!TIP] +> [!NOTE] > In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. ### Securing Endpoints diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index c442e6cb..d89fdec9 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -115,5 +115,5 @@ cf restage sampleApp Once the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`. -> [!TIP] -> Explore the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) for a demonstration on why this provider is useful. +> [!NOTE] +> Refer to the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) for a demonstration on why this provider is useful. diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index a8970d80..aa45712c 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -134,7 +134,7 @@ app.MapDefaultControllerRoute(); app.Run(); ``` -> [!TIP] +> [!NOTE] > In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. ### Securing Endpoints @@ -166,7 +166,7 @@ The preceding example establishes the following security rules: * If a user attempts to access the `Privacy` action and the user is not authenticated, the user is redirected to the OAuth server (such as a UAA Server) to log in. * If an authenticated user attempts to access the `TestGroup` action but does not meet the restrictions established by the referenced policy, the user is denied access. -> [!TIP] +> [!NOTE] > The Steeltoe UAA server has several pre-provisioned user accounts. Sign in with `testuser` and password `password` to access resources secured with `sampleapi.read` > To test with a user that does not have the permission `sampleapi.read`, sign in with the user `customer` and password `password`. > diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index bd985b95..7c416d5b 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -87,7 +87,7 @@ As a replacement for what Steeltoe used to provide for using these samplers, set * `always_on` * `always_off` -> [!TIP] +> [!NOTE] > OpenTelemetry is generally built to follow the [options pattern](https://learn.microsoft.com/dotnet/core/extensions/options). > There are more ways to configure options than demonstrated on this page; these are just examples to help you get started. @@ -166,7 +166,7 @@ builder.Services.Configure(options => }); ``` -> [!TIP] +> [!NOTE] > By default, the ASP.NET Core instrumentation does not filter out any requests. > The alternative approach described can quickly prove unwieldy if there are many patterns to ignore, such as when listing many file types. diff --git a/api/v4/welcome/common-steps.md b/api/v4/welcome/common-steps.md index 15d17c17..2454749c 100644 --- a/api/v4/welcome/common-steps.md +++ b/api/v4/welcome/common-steps.md @@ -17,7 +17,7 @@ You can use the `dotnet` CLI to [build and locally publish](https://learn.micros * Linux: `dotnet publish --framework net8.0 --runtime linux-x64` * macOS: `dotnet publish --framework net8.0 --runtime osx-x64` -> [!TIP] +> [!NOTE] > Since .NET Core 2.0, the `dotnet publish` command automatically runs the NuGet package restore for you. Running `dotnet restore` explicitly is no longer required. ## Cloud Foundry Push Sample From b14a510167bcb01dc26af36db78797063eebf145 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Mon, 3 Mar 2025 10:16:25 -0800 Subject: [PATCH 12/43] full edit management topics(2) + bulk Note wording change --- api/v4/management/cloud-foundry.md | 4 +-- api/v4/management/dbmigrations.md | 4 +-- api/v4/management/env.md | 4 +-- api/v4/management/health.md | 4 +-- api/v4/management/heapdump.md | 4 +-- api/v4/management/httpexchanges.md | 52 +++++++++++++++------------- api/v4/management/hypermedia.md | 28 +++++++-------- api/v4/management/info.md | 33 +++++++++--------- api/v4/management/loggers.md | 48 ++++++++++++------------- api/v4/management/mappings.md | 26 +++++++------- api/v4/management/prometheus.md | 16 ++++----- api/v4/management/refresh.md | 4 +-- api/v4/management/services.md | 4 +-- api/v4/management/threaddump.md | 14 ++++---- api/v4/management/using-endpoints.md | 4 +-- 15 files changed, 126 insertions(+), 123 deletions(-) diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 81986777..64f62dd5 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -48,8 +48,8 @@ builder.Services.AddCloudFoundryActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ### Cross Origin Resource Sharing diff --git a/api/v4/management/dbmigrations.md b/api/v4/management/dbmigrations.md index 85403c4e..9ade7b69 100644 --- a/api/v4/management/dbmigrations.md +++ b/api/v4/management/dbmigrations.md @@ -37,8 +37,8 @@ builder.Services.AddDbMigrationsActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/env.md b/api/v4/management/env.md index e6596b59..42e0d13b 100644 --- a/api/v4/management/env.md +++ b/api/v4/management/env.md @@ -37,8 +37,8 @@ builder.Services.AddEnvironmentActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/health.md b/api/v4/management/health.md index 7bef96b2..d29e13f9 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -83,8 +83,8 @@ builder.Services.AddHealthActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. By default, the health status is reflected in the HTTP response status code. For example, when a health check fails, the response status code is `503 Service Unavailable`. diff --git a/api/v4/management/heapdump.md b/api/v4/management/heapdump.md index 95356248..c229747a 100644 --- a/api/v4/management/heapdump.md +++ b/api/v4/management/heapdump.md @@ -46,5 +46,5 @@ builder.Services.AddHeapDumpActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/httpexchanges.md b/api/v4/management/httpexchanges.md index 2583c966..44d60e3d 100644 --- a/api/v4/management/httpexchanges.md +++ b/api/v4/management/httpexchanges.md @@ -1,8 +1,8 @@ # HTTP Exchanges -The Steeltoe HTTP Exchanges endpoint provides the ability to view the last several requests made of your application. +The Steeltoe HTTP Exchanges endpoint provides the ability to view the last several requests sent to your application. -When you activate this endpoint, an `IHttpExchangesRepository` implementation is registered that stores HTTP request/response information in memory, that can be retrieved by using the endpoint. +When you activate this endpoint, an `IHttpExchangesRepository` implementation is registered; it stores HTTP request/response information in memory, and can be retrieved by using the endpoint. ## Configure Settings @@ -10,29 +10,30 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:HttpExchanges:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `httpexchanges` | -| `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 the endpoint is exposed at. | `GET` | -| `Capacity` | Size of the circular buffer of exchanges. | 100 | -| `IncludeRequestHeaders` | Whether to return headers from the HTTP request. | `true` | -| `RequestHeaders` | An array of HTTP request headers to return unredacted, in addition to the default set. | | -| `IncludeResponseHeaders` | Whether to return headers from the HTTP response. | `true` | -| `ResponseHeaders` | An array of HTTP response headers to return unredacted, in addition to the default set. | | -| `IncludePathInfo` | Whether to return the path from the HTTP request URL. | `true` | -| `IncludeQueryString` | Whether to return the query string parameters from the request URL. | `true` | -| `IncludeUserPrincipal` | Whether to return the username from [`HttpContext.User`](https://learn.microsoft.com/dotnet/api/system.security.claims.claimsprincipal). | `false` | -| `IncludeRemoteAddress` | Whether to return the IP address from the sender. | `false` | -| `IncludeSessionId` | Whether to return the user's session ID. | `false` | -| `IncludeTimeTaken` | Whether to return the request duration. | `true` | -| `Reverse` | Whether to return exchanges in reverse order (newest first). | `true` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `httpexchanges` | +| `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 | `GET` | +| `Capacity` | Size of the circular buffer of exchanges | 100 | +| `IncludeRequestHeaders` | Whether to return headers from the HTTP request | `true` | +| `RequestHeaders` | An array of HTTP request headers to return unredacted, in addition to the default set | | +| `IncludeResponseHeaders` | Whether to return headers from the HTTP response | `true` | +| `ResponseHeaders` | An array of HTTP response headers to return unredacted, in addition to the default set | | +| `IncludePathInfo` | Whether to return the path from the HTTP request URL | `true` | +| `IncludeQueryString` | Whether to return the query string parameters from the request URL | `true` | +| `IncludeUserPrincipal` | Whether to return the username from [`HttpContext.User`](https://learn.microsoft.com/dotnet/api/system.security.claims.claimsprincipal) | `false` | +| `IncludeRemoteAddress` | Whether to return the IP address from the sender | `false` | +| `IncludeSessionId` | Whether to return the user's session ID | `false` | +| `IncludeTimeTaken` | Whether to return the request duration | `true` | +| `Reverse` | Whether to return exchanges in reverse order (newest first) | `true` | All request and response header values are redacted by default, except for the whitelisted entries below. To return additional headers unredacted, add them to the `RequestHeaders` or `ResponseHeaders` arrays. Whitelist of HTTP request headers: + - Accept - Accept-Charset - Accept-Encoding @@ -61,6 +62,7 @@ Whitelist of HTTP request headers: - X-UA-Compatible Whitelist of HTTP response headers: + - Accept-Ranges - Age - Allow @@ -86,10 +88,10 @@ Whitelist of HTTP response headers: ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/httpexchanges`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHttpExchangesActuator` extension method. @@ -103,14 +105,14 @@ builder.Services.AddHttpExchangesActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns an array of exchanges. -The response is always returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/hypermedia.md b/api/v4/management/hypermedia.md index 7aa4666d..9fc6e1ea 100644 --- a/api/v4/management/hypermedia.md +++ b/api/v4/management/hypermedia.md @@ -9,16 +9,16 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Actuator:`. Note this key differs from the convention used by other actuators. | 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 the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `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 | `GET` | > [!NOTE] > This endpoint is exposed automatically because its ID is empty. To reference this actuator in exposure settings, -> first configure a non-empty ID. Because the Path is the same as ID unless specified, set it to empty explicitly: +> start by configuring a non-empty ID. Because the Path is the same as ID unless otherwise specified, set it to empty explicitly: > ```json > { > "Management": { @@ -37,14 +37,14 @@ Each key must be prefixed with `Management:Endpoints:Actuator:`. Note this key d ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator`. > [!NOTE] -> When running on Cloud Foundry, the [Cloud Foundry Actuator](./cloud-foundry.md) should be used instead, -> whose default path is `/cloudfoundryapplication`. +> When running on Cloud Foundry, the [Cloud Foundry Actuator](./cloud-foundry.md) should be used instead. +> Its default path is `/cloudfoundryapplication`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHypermediaActuator` extension method. @@ -58,14 +58,14 @@ builder.Services.AddHypermediaActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of management endpoints, including itself. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/info.md b/api/v4/management/info.md index d432bb83..c111e567 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -1,10 +1,10 @@ # Info -The Steeltoe Info endpoint exposes information about the running application, such as its version and the Steeltoe version in use. +The Steeltoe Info endpoint exposes information about the running application, such as its version and the version of Steeltoe in use. Information is collected from all `IInfoContributor` implementations registered in the application. -Steeltoe includes a couple contributor implementations out of the box that you can use. -Also, and perhaps more importantly, you can write your own. +Steeltoe includes a couple of contributor implementations out of the box that you can use. +You can also write your own implementations. ## Configure Settings @@ -12,19 +12,19 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Info:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `info` | -| `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 the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `info` | +| `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 | `GET` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/info`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddInfoActuator` extension method. @@ -38,8 +38,8 @@ builder.Services.AddInfoActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Built-in Contributors @@ -50,6 +50,7 @@ This contributor exposes file/version info for both the application and the incl ### Configuration This contributor exposes any values below the `Info` configuration key. For example: + ```json { "Info": { @@ -68,15 +69,15 @@ This contributor exposes any values below the `Info` configuration key. For exam ### Git properties -Exposes information from the `git.properties` Spring Boot file, if available. -Shows information from git, such as branch/tag name, commit hash, and remote. +* Exposes information from the `git.properties` Spring Boot file, if available +* Shows information from git, such as branch/tag name, commit hash, and remote > [!NOTE] > For an example of how to use this contributor within MSBuild using [GitInfo](https://github.com/devlooped/GitInfo), see the [Steeltoe Management sample](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src). ## Sample Output -Depending on the registered contributors, this endpoint returns JSON such as this: +Depending on the registered contributors, this endpoint returns JSON similar to this: ```json { diff --git a/api/v4/management/loggers.md b/api/v4/management/loggers.md index ab74c371..e741db73 100644 --- a/api/v4/management/loggers.md +++ b/api/v4/management/loggers.md @@ -10,19 +10,19 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Loggers:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `loggers` | -| `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 the endpoint is exposed at. | `GET`, `POST` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `loggers` | +| `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 | `GET`, `POST` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/loggers`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddInfoActuator` extension method. @@ -36,12 +36,12 @@ builder.Services.AddLoggersActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. > [!NOTE] > When `AddLoggersActuator` is called, it tries to register [Dynamic Console Logging](../logging/dynamic-console-logging.md). -> If you'd like to use Serilog instead, call `AddDynamicSerilog` *before* `AddLoggersActuator`. +> If you'd like to use Serilog instead, call `AddDynamicSerilog` *before* calling `AddLoggersActuator`. ## Retrieving Minimum Log Levels @@ -60,7 +60,7 @@ The response below shows the loggers and their minimum levels for the following ``` To retrieve the currently active loggers and their minimum log levels, send an HTTP `GET` request to `/actuator/loggers`, -which returns the response below: +which returns the following response: ```json { @@ -102,22 +102,22 @@ which returns the response below: } ``` -The response above shows only effective levels, because there are no runtime overrides yet. +The response shows only effective levels, because there are no runtime overrides yet. ## Modifying Minimum Log Levels -Minimum log levels can be changed at runtime by adding the category to the URL of a `POST` request and the minimum level to assign in the request body. +Minimum log levels can be changed at runtime by adding the category to the URL of a `POST` request, and the minimum level to assign in the request body. The category is the fully-qualified name of the logger, which works like a prefix. -For example, changing the minimum log level of `Microsoft.AspNetCore` will affect all loggers whose category starts with -`Microsoft.AspNetCore`, such as `Microsoft.AspNetCore` and `Microsoft.AspNetCore.Cors` (but not `Microsoft.AspNetCoreExtra`). +For example, changing the minimum log level of `Microsoft.AspNetCore` affects all loggers for which the category starts with +`Microsoft.AspNetCore`; for example, `Microsoft.AspNetCore` and `Microsoft.AspNetCore.Cors` (but not `Microsoft.AspNetCoreExtra`). > [!NOTE] > [Spring Boot Admin](https://www.baeldung.com/spring-boot-changing-log-level-at-runtime) and [Tanzu Apps Manager](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/4-0/tpcf/using-actuators.html#manage-log-levels) > provide a UI to change the minimum levels at runtime. For compatibility, the level names used by this actuator differ from the names used by .NET. > > | Actuator level | .NET level | -> | --- | --- | +> | -------------- | ------ | > | `OFF` | `LogLevel.None` | > | `FATAL` | `LogLevel.Critical` | > | `ERROR` | `LogLevel.Error` | @@ -126,7 +126,7 @@ For example, changing the minimum log level of `Microsoft.AspNetCore` will affec > | `DEBUG` | `LogLevel.Debug` | > | `TRACE` | `LogLevel.Trace` | -Using the `appsettings.json` from above, change the minimum log level of the `Steeltoe.Management` category to `TRACE` +Using the `appsettings.json` from earlier, change the minimum log level of the `Steeltoe.Management` category to `TRACE` by sending a POST request to `/actuator/loggers/Steeltoe.Management` with the following request body: ```json @@ -138,9 +138,9 @@ by sending a POST request to `/actuator/loggers/Steeltoe.Management` with the fo > [!NOTE] > Because the logger category is part of the request URL, avoid using colons in the name to prevent invalid HTTP requests. -To verify the change was applied, send a `GET` request to `/actuator/loggers` to see the updated loggers. +To verify that the change was applied, send a `GET` request to `/actuator/loggers` to see the updated loggers. The response below shows that the `Steeltoe.Management` logger (and its descendants) now use a minimum level of `TRACE`. -Furthermore, the `Steeltoe.Management` entry contains both `configuredLevel` and `effectiveLevel`, which means the level can be reset. +In addition, the `Steeltoe.Management` entry contains both `configuredLevel` and `effectiveLevel`, which means the level can be reset. ```json { @@ -185,7 +185,7 @@ Furthermore, the `Steeltoe.Management` entry contains both `configuredLevel` and ## Resettings Minimum Log Levels -To revert back to the original minimum level, send another `POST` request to `/actuator/loggers/Steeltoe.Management`, but with the following request body: +To change back to the original minimum level, send another `POST` request to `/actuator/loggers/Steeltoe.Management`, with the following request body: ```json { @@ -193,14 +193,14 @@ To revert back to the original minimum level, send another `POST` request to `/a } ``` -To verify the change was applied, send a `GET` request to `/actuator/loggers`, which returns the same JSON response as before overriding the minimum levels. +To verify that the change was applied, send a `GET` request to `/actuator/loggers`, which returns the same JSON response as before overriding the minimum levels. ## Configuration Changes Dynamic log levels in Steeltoe are implemented by wrapping an existing `ILoggerProvider` and intercepting calls to its `CreateLogger` method. -The returned `ILogger` instances are wrapped as well, so that the minimum level can be changed at runtime. +The returned `ILogger` instances are also wrapped so that the minimum level can be changed at runtime. -When changes to `appsettings.json` are saved, existing loggers are updated with the new minimum levels, unless overridden. +When changes to `appsettings.json` are saved, existing loggers are updated with the new minimum levels, unless they are overridden. A reset of an overridden logger reverts to the updated level from `appsettings.json`. > [!NOTE] diff --git a/api/v4/management/mappings.md b/api/v4/management/mappings.md index 5988e472..50e77c12 100644 --- a/api/v4/management/mappings.md +++ b/api/v4/management/mappings.md @@ -1,6 +1,6 @@ # Route Mappings -You can use the Steeltoe Route Mappings actuator to retrieve the HTTP endpoints in your app that originate from ASP.NET Minimal APIs, API/MVC Controllers, Razor Pages and Blazor. +You can use the Steeltoe Route Mappings actuator to retrieve the HTTP endpoints in your app that originate from ASP.NET Minimal APIs, API/MVC Controllers, Razor Pages, and Blazor. ## Configure Settings @@ -8,20 +8,20 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Mappings:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `mappings` | -| `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 the endpoint is exposed at. | `GET` | -| `IncludeActuators` | Whether to include actuator endpoints in the response. | `true` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `mappings` | +| `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 | `GET` | +| `IncludeActuators` | Whether to include actuator endpoints in the response | `true` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/mappings`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddRouteMappingsActuator` extension method. @@ -35,14 +35,14 @@ builder.Services.AddRouteMappingsActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of route mappings and their parameters. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index d44a8475..629011b0 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -18,22 +18,22 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Prometheus:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `prometheus` | -| `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 the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `prometheus` | +| `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 | `GET` | > [!NOTE] > The `AllowedVerbs` setting is inherited from Steeltoe's `EndpointOptions`, but is not intended to work for the Prometheus exporter, which is only registered to respond to `GET` requests. ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/prometheus`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddPrometheusActuator` extension method. diff --git a/api/v4/management/refresh.md b/api/v4/management/refresh.md index 6eb9d32d..8dce4418 100644 --- a/api/v4/management/refresh.md +++ b/api/v4/management/refresh.md @@ -40,8 +40,8 @@ builder.Services.AddRefreshActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/services.md b/api/v4/management/services.md index 284305a2..32bb8f13 100644 --- a/api/v4/management/services.md +++ b/api/v4/management/services.md @@ -37,8 +37,8 @@ builder.Services.AddServicesActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/threaddump.md b/api/v4/management/threaddump.md index 88a96250..ae607688 100644 --- a/api/v4/management/threaddump.md +++ b/api/v4/management/threaddump.md @@ -9,11 +9,11 @@ Each key must be prefixed with `Management:Endpoints:ThreadDump:`. | Key | Description | Default | | --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `threaddump` | -| `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 the endpoint is exposed at. | `GET` | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `threaddump` | +| `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 | `GET` | > [!NOTE] > In version 4, the configuration key prefix for this endpoint changed from `Management:Endpoints:Dump:` to `Management:Endpoints:ThreadDump:` @@ -37,8 +37,8 @@ builder.Services.AddThreadDumpActuator(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output diff --git a/api/v4/management/using-endpoints.md b/api/v4/management/using-endpoints.md index d469bbc3..57ac1c08 100644 --- a/api/v4/management/using-endpoints.md +++ b/api/v4/management/using-endpoints.md @@ -151,8 +151,8 @@ builder.Services.AddAllActuators(); ``` > [!NOTE] -> It is recommended that you use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime using configuration. +> 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: From 9e799958465474d42742fdfe792ac90beae891dc Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Mon, 3 Mar 2025 14:01:27 -0800 Subject: [PATCH 13/43] full edit management topics(3) --- api/v4/management/cloud-foundry.md | 40 +++++++-------- api/v4/management/health.md | 2 +- api/v4/management/prometheus.md | 74 +++++++++++++++------------- api/v4/management/refresh.md | 22 ++++----- api/v4/management/services.md | 18 +++---- api/v4/management/springbootadmin.md | 46 ++++++++++------- api/v4/management/tasks.md | 10 ++-- api/v4/management/threaddump.md | 10 ++-- 8 files changed, 118 insertions(+), 104 deletions(-) diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 64f62dd5..5e4a0453 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -5,11 +5,11 @@ Integration with [Tanzu Apps Manager](https://techdocs.broadcom.com/us/en/vmware When used, this endpoint enables the following additional functionality on Cloud Foundry: * A variant of the [hypermedia](./hypermedia.md) endpoint is registered at `/cloudfoundryapplication`. -* All endpoints are additionally mapped under the base path `/cloudfoundryapplication`. +* All endpoints are also mapped under the base path `/cloudfoundryapplication`. * [Authentication and authorization](#security) for your Cloud Foundry environment is added to the request pipeline. > [!NOTE] -> The Cloud Foundry integration will not work unless the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured. +> The Cloud Foundry integration works only when the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured. ## Configure Settings @@ -17,24 +17,24 @@ Typically, no additional configuration is needed. However, the following table d Each key must be prefixed with `Management:Endpoints:CloudFoundry`. | 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 the endpoint is exposed at. | `GET` | -| `ValidateCertificates` | Whether to validate server certificates. | `true` | -| `ApplicationId` | The ID of the application used in permission checks. | | -| `CloudFoundryApi` | The URL of the Cloud Foundry API. | | +| --- | ----------- | ------- | +| `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 | `GET` | +| `ValidateCertificates` | Whether to validate server certificates | `true` | +| `ApplicationId` | The ID of the application used in permission checks | | +| `CloudFoundryApi` | The URL of the Cloud Foundry API | | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/cloudfoundryapplication`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. -To add the actuator to the service container, add a [CORS](#cross-origin-resource-sharing) policy, register security middleware and map its route, use the `AddCloudFoundryActuator` extension method. +To add the actuator to the service container, add a [CORS](#cross-origin-resource-sharing) policy, register security middleware and map its route, and use the `AddCloudFoundryActuator` extension method. Add the following code to `Program.cs` to use the actuator endpoint: @@ -53,10 +53,10 @@ builder.Services.AddCloudFoundryActuator(); ### Cross Origin Resource Sharing -When viewing an application in Apps Manager, HTTP requests are sent directly to application instances with the bearer token of the logged-in user attached. +When viewing an application in Apps Manager, HTTP requests are sent directly to application instances, with the bearer token of the logged-in user attached. The nature of this integration requires the use of Cross Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). -The policy defined in Steeltoe intends to limit sharing to the minimum required for the endpoints to function, however there is no way for Steeltoe to discover or even guess at what the origin of an Apps Manager instance could be. -As such, the default policy will allow any origin, unless the policy is customized. You should consider [customizing the CORS policy](./using-endpoints.md#customizing-the-cors-policy) to be more specific. +The policy defined in Steeltoe intends to limit sharing to the minimum required for the endpoints to function; however, there is no way for Steeltoe to discover or infer what the origin of an Apps Manager instance could be. +As such, the default policy allows any origin, unless the policy is customized. You should consider [customizing the CORS policy](./using-endpoints.md#customizing-the-cors-policy) to be more specific. ## Security @@ -65,7 +65,7 @@ The Cloud Foundry security middleware requires a valid UAA access token to be pr Additionally, the security middleware evaluates the token to determine whether the authenticated user has permission to access the management endpoint. > [!NOTE] -> The Cloud Foundry security middleware is only active when your application is running on Cloud Foundry. +> The Cloud Foundry security middleware is active only when your application is running on Cloud Foundry. ## External access @@ -77,5 +77,5 @@ For this reason, all endpoints are exposed by default at `/cloudfoundryapplicati In addition, the endpoints may be secured by whatever security mechanism the application itself uses. For more details, see [securing actuators](./using-endpoints.md#securing-endpoints). > [!CAUTION] -> Applying an authorization policy on `/actuator` will also impact `/cloudfoundryapplication`, which will break the integration with Apps Manager. -> In order to prevent public access to `/actuator` when running on Cloud Foundry, consider configuring actuators to [use an alternate port](./using-endpoints.md#configure-global-settings). +> Applying an authorization policy on `/actuator` also has an impact on `/cloudfoundryapplication`, which then breaks the integration with Apps Manager. +> To prevent public access to `/actuator` when running on Cloud Foundry, consider configuring actuators to [use an alternate port](./using-endpoints.md#configure-global-settings). diff --git a/api/v4/management/health.md b/api/v4/management/health.md index d29e13f9..aebf6e1a 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -152,7 +152,7 @@ When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `Whe ## Health Groups -If you need to check application health based on a subset of health contributors, you can specify the name of the grouping and a comma-separated list of contributors to include: +If you want to check application health based on a subset of health contributors, you can specify the name of the grouping and a comma-separated list of contributors to include: ```json { diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index 629011b0..2baa7cf3 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -6,11 +6,11 @@ The Steeltoe Prometheus endpoint configures the [OpenTelemetry Prometheus Export The Prometheus endpoint does not automatically instrument your application, but does make it easy to export metrics in the Prometheus metrics format, which can be used by tools like [Prometheus Server](https://prometheus.io/) and the [Metric Registrar for Tanzu Platform for Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/metric-registrar-index.html). -The [Steeltoe Management samples](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src/ActuatorWeb/README.md) can help you understand how to use this tool. +See the [Steeltoe Management samples](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src/ActuatorWeb/README.md) for more information about using this tool. ## Add NuGet Reference -To use the Prometheus endpoint, you need to add a reference to the `Steeltoe.Management.Prometheus` NuGet package. +To use the Prometheus endpoint, add a reference to the `Steeltoe.Management.Prometheus` NuGet package. ## Configure Settings @@ -26,7 +26,7 @@ Each key must be prefixed with `Management:Endpoints:Prometheus:`. | `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | > [!NOTE] -> The `AllowedVerbs` setting is inherited from Steeltoe's `EndpointOptions`, but is not intended to work for the Prometheus exporter, which is only registered to respond to `GET` requests. +> The `AllowedVerbs` setting is inherited from the Steeltoe `EndpointOptions`, but is not intended to work for the Prometheus exporter, which is only registered to respond to `GET` requests. ## Enable HTTP Access @@ -49,7 +49,7 @@ builder.Services.AddPrometheusActuator(); ### Configuring the request pipeline for Prometheus In addition to the options described in [using endpoints](./using-endpoints.md), `AddPrometheusActuator` exposes an `Action?` that can be used to configure the branched request pipeline that is used in the underlying OpenTelemetry package. -This pipeline would need to be configured if, as an example, you are configuring an authorization policy. +This pipeline must be configured if, as an example, you are configuring an authorization policy. ```csharp builder.Services.AddPrometheusActuator(true, pipeline => pipeline.UseAuthorization()); @@ -57,51 +57,57 @@ builder.Services.AddPrometheusActuator(true, pipeline => pipeline.UseAuthorizati ## Instrumentation -In order for the Prometheus endpoint to return metrics, the application and relevant libraries need to be instrumented. -This page will cover the basics for elements that previous versions of Steeltoe configured automatically. -Please refer to the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net/instrumentation/) for more detailed information. +For the Prometheus endpoint to return metrics, the application and relevant libraries must be instrumented. +This topic covers the basics for elements that previous versions of Steeltoe configured automatically. +Refer to the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net/instrumentation/) for more detailed information. ### ASP.NET Core -To instrument ASP.NET Core for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. +To instrument ASP.NET Core for metrics: -Next, add the instrumentation to the `MeterProviderBuilder`: +1. Add a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. -```csharp -using OpenTelemetry.Metrics; +1. Add the instrumentation to the `MeterProviderBuilder`: -builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddAspNetCoreInstrumentation()); -``` + ```csharp + using OpenTelemetry.Metrics; + + builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddAspNetCoreInstrumentation()); + ``` -[Learn more about ASP.NET Core instrumentation for OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore) +For more information about ASP.NET Core instrumentation for OpenTelemetry, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore). ### HttpClient -To instrument `HttpClient`s for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. +To instrument `HttpClient`s for metrics: -Next, add the instrumentation to the `MeterProviderBuilder`: +1. Add a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. -```csharp -using OpenTelemetry.Metrics; +2. Add the instrumentation to the `MeterProviderBuilder`: -builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddHttpClientInstrumentation()); -``` + ```csharp + using OpenTelemetry.Metrics; -[Learn more about HttpClient instrumentation for OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http) + builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddHttpClientInstrumentation()); + ``` + +For more information about HttpClient instrumentation for OpenTelemetry, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http). ### .NET Runtime -To instrument the .NET Runtime for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.Runtime` NuGet package. +To instrument the .NET Runtime for metrics: -Next, add the instrumentation to the `MeterProviderBuilder`: +1. Add a reference to the `OpenTelemetry.Instrumentation.Runtime` NuGet package. -```csharp -using OpenTelemetry.Metrics; +1. Add the instrumentation to the `MeterProviderBuilder`: -builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddRuntimeInstrumentation()); -``` + ```csharp + using OpenTelemetry.Metrics; + + builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddRuntimeInstrumentation()); + ``` -[Learn more about Runtime Instrumentation for OpenTelemetry .NET](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Runtime) +For more information about Runtime Instrumentation for OpenTelemetry .NET, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Runtime). ### Prometheus Server @@ -111,7 +117,7 @@ As an example, the following `prometheus.yml` file configures metric scraping fo ```yml global: - scrape_interval: 15s # Set the scrape interval to every 15 seconds. The default is every 1 minute. + scrape_interval: 15 s # Set the scrape interval to every 15 seconds. The default is every 1 minute. evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute. # scrape_timeout is set to the global default (10s). scrape_configs: @@ -138,10 +144,10 @@ To emit custom metrics in Cloud Foundry, use [Metric Registrar](https://techdocs > [!CAUTION] > Authenticated endpoints are not supported with Metric Registrar. -> For this scenario, configure actuators to [use an alternate port](./using-endpoints.md#configure-global-settings) and use that private network port to offer the metrics. +> For this scenario, configure actuators to use an [alternate port](./using-endpoints.md#configure-global-settings) and use that private network port to offer the metrics. -The examples below expect that actuators are mapped to an alternate port (8091 in this case). -The specific port that is used is not important to Steeltoe, it only matters that the binding and Steeltoe configurations match. +The following examples assume that actuators are mapped to an alternate port (8091 in this case). +The specific port is not important to Steeltoe, it only matters that the binding and Steeltoe configurations match. #### Metrics Registrar Plugin @@ -169,13 +175,13 @@ cf bind-service APP-NAME SERVICE-NAME This endpoint returns information about the instrumented application metrics and their values. -If no instrumentation has been included, the response will be very short, like this: +If no instrumentation has been included, the response is very short: ```text # EOF ``` -With the addition of [.NET Runtime instrumentation](#net-runtime), the response will be like this: +With the addition of [.NET Runtime instrumentation](#net-runtime), the response is similar to the following: ```text # TYPE process_runtime_dotnet_gc_collections_count_total counter diff --git a/api/v4/management/refresh.md b/api/v4/management/refresh.md index 8dce4418..ac575a82 100644 --- a/api/v4/management/refresh.md +++ b/api/v4/management/refresh.md @@ -9,24 +9,24 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Refresh:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `refresh` | -| `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 the endpoint is exposed at. | `POST` | -| `ReturnConfiguration` | Whether to return the configuration after refresh. | `true` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `refresh` | +| `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 | `POST` | +| `ReturnConfiguration` | Whether to return the configuration after refresh | `true` | > [!NOTE] -> Despite being *possible* to configure this endpoint to respond to `GET` requests, +> Despite it being *possible* to configure this endpoint to respond to `GET` requests, > this is discouraged because it is not a [Safe HTTP Method](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP). ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/refresh`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddRefreshActuator` extension method. @@ -47,7 +47,7 @@ builder.Services.AddRefreshActuator(); This endpoint returns an array of keys obtained from `IConfiguration`. -The response will always be returned as JSON, like this: +The response always returns as JSON: ```json [ diff --git a/api/v4/management/services.md b/api/v4/management/services.md index 32bb8f13..ad2b6a8a 100644 --- a/api/v4/management/services.md +++ b/api/v4/management/services.md @@ -8,22 +8,22 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Services:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `beans` | -| `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 the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `beans` | +| `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 | `GET` | > [!NOTE] > The `ID` of this endpoint defaults to `beans` for compatibility with the [beans actuator from Spring](https://docs.spring.io/spring-boot/api/rest/actuator/beans.html). ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/beans`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddServicesActuator` extension method. @@ -44,7 +44,7 @@ builder.Services.AddServicesActuator(); This endpoint returns the contents of `IServiceCollection`. -The response will always be returned as JSON, like this: +The response is always returned as JSON, like this: ```json { diff --git a/api/v4/management/springbootadmin.md b/api/v4/management/springbootadmin.md index d0ec9826..6bd99a18 100644 --- a/api/v4/management/springbootadmin.md +++ b/api/v4/management/springbootadmin.md @@ -22,14 +22,14 @@ builder.Services.AddSpringBootAdminClient(); The following table describes the configuration settings that you can apply to the client. Each key must be prefixed with `Spring:Boot:Admin:Client:`. -| Key | Description | Default | -| --- | --- | --- | -| `Url` | The URL of the Spring Boot Admin server. | | -| `ApplicationName` | The name of the Steeltoe app being registered. | computed | -| `BasePath` | Base path to find endpoints for integration. | computed | -| `ValidateCertificates` | Whether server certificates should be validated. | `true` | -| `ConnectionTimeoutMS` | Connection timeout (in milliseconds). | `100_000` | -| `Metadata` | Dictionary of metadata to use when registering. | | +| Key | Description | Default | +| ----- | ----------- | ------- | +| `Url` | The URL of the Spring Boot Admin server | | +| `ApplicationName` | The name of the Steeltoe app being registered | computed | +| `BasePath` | The base path to find endpoints for integration | computed | +| `ValidateCertificates` | Whether server certificates should be validated | `true` | +| `ConnectionTimeoutMS` | Connection timeout (in milliseconds) | `100_000` | +| `Metadata` | Dictionary of metadata to use when registering | | ## Connecting to dockerized Spring Boot Admin Server @@ -38,31 +38,35 @@ a few additional steps are needed: - Register your app using `host.docker.internal` - Once your app has registered itself with Spring Boot Admin Server, the server tries to connect to your app + After your app has registered itself with Spring Boot Admin Server, the server tries to connect to your app and send requests to its actuator endpoints. This fails when your app registers itself using `localhost`, because the server runs in a docker container that has its own network. - Instead, you need to register using the special `host.docker.internal` address, which enables the server inside the container + Instead, you must register using the special `host.docker.internal` address, which enables the server inside the container to connect to your app outside the container. - Bind your app to a wildcard address By default, your app listens only on `localhost`, which is not accessible from the Spring Boot Admin Server running in a container. To make the app accessible, bind it to a wildcard address, which allows it to listen on all available network interfaces. - This can be done by updating the `launchSettings.json` file. + To do this, update the `launchSettings.json` file. - Use HTTP instead of HTTPS - The server doesn't trust the self-signed certificate used by your app, so you need to use HTTP instead of HTTPS. + The server doesn't trust the self-signed certificate used by your app, so you must use HTTP instead of HTTPS. This requires removing `app.UseHttpsRedirection()` from your `Program.cs` file. - Register additional actuator endpoints - For the server to report the app as "UP", you need to add at least the hypermedia and health actuators in `Program.cs`. + For the server to report the app as "UP," you must add at least the hypermedia and health actuators in `Program.cs`. > [!NOTE] -> You can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin) for testing purposes. +> For testing, you can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin). -Putting it all together, your `appsettings.Development.json` file should look like this: +Putting it all together, your config files contain the contents shown in the following: + +### appsettings.Development.json + +In `appsettings.Development.json`: ```json { @@ -84,7 +88,9 @@ Putting it all together, your `appsettings.Development.json` file should look li } ``` -With the following contents in `launchsettings.json`: +### launchsettings.json + +In `launchsettings.json`: ```json { @@ -104,7 +110,9 @@ With the following contents in `launchsettings.json`: ``` > [!NOTE] -> If you'd like your app to listen on a different port number, replace `5258` in both files above with the desired port. +> If you want your app to listen on a different port number, replace `5258` in both files above with the desired port. + +### Program.cs And the following code in `Program.cs`: @@ -125,7 +133,7 @@ builder.Services.AddControllers(); var app = builder.Build(); -// In order to avoid trust issues with self-signed certificates, do not automatically redirect to https. +// To avoid trust issues with self-signed certificates, do not automatically redirect to https. //app.UseHttpsRedirection(); app.MapControllers(); @@ -134,4 +142,4 @@ app.Run(); ``` > [!NOTE] -> To see all the Spring Boot Admin features in action, replace the `Add*Actuator()` calls in `Program.cs` with `AddAllActuators()` and [expose all endpoints](./using-endpoints.md#exposing-endpoints). +> To see all the Spring Boot Admin features in action, replace the `Add*Actuator()` calls in `Program.cs` with `AddAllActuators()` and expose all endpoints. See [Exposing endpoints](./using-endpoints.md#exposing-endpoints). diff --git a/api/v4/management/tasks.md b/api/v4/management/tasks.md index 12410a9c..79852153 100644 --- a/api/v4/management/tasks.md +++ b/api/v4/management/tasks.md @@ -58,7 +58,7 @@ builder.Services.AddTask("ExampleTaskName"); > [!NOTE] > To register as a singleton or transient service, use the overload that additionally takes a `ServiceLifetime` parameter. -In case task instantiation requires additional logic, a task instance can be specified as well: +If task instantiation requires additional logic, a task instance can be specified as well: ```csharp using Steeltoe.Management.Tasks; @@ -85,7 +85,7 @@ builder.Services.AddTask("ExampleTaskName", (serviceProvider, taskName) => ## Executing a Task -Once your task has been defined and added to the service container, the last step is to enable a means of executing the task. +After your task has been defined and added to the service container, the last step is to enable a means of executing the task. In your `Program.cs` file, replace the call to `app.Run()` with `await app.RunWithTasksAsync()`: ```csharp @@ -100,15 +100,15 @@ await app.RunWithTasksAsync(CancellationToken.None); ## Specify Task to Execute -Once all the setup steps have been completed, any invocation of your application with a configuration value for the `RunTask` key +After all the setup steps have been completed, any invocation of your application with a configuration value for the `RunTask` key runs that task (and shuts down) instead of starting the web application: ``` dotnet run -- RunTask=ExampleTaskName ``` -As a matter of best practice, we encourage you to provide the `RunTask` value only via a command-line parameter. -However, due to the way .NET configuration works, it does not matter which configuration provider is used to provide the task name. +As a matter of best practice, it is recommended that you provide the `RunTask` value only using a command-line parameter. +However, due to the way .NET configuration works, it doesn't matter which configuration provider is used to provide the task name. Invoking the command on Cloud Foundry looks similar to this: ``` diff --git a/api/v4/management/threaddump.md b/api/v4/management/threaddump.md index ae607688..1307510f 100644 --- a/api/v4/management/threaddump.md +++ b/api/v4/management/threaddump.md @@ -1,6 +1,6 @@ # Thread Dump -The Steeltoe Thread Dump endpoint can be used to generate a snapshot of information about all the threads in your application. That snapshot includes several bits of information for each thread, including the thread's state, a stack trace, any monitor locks held by the thread, any monitor locks the thread is waiting on, and other details. +The Steeltoe Thread Dump endpoint can be used to generate a snapshot of information about all the threads in your application. That snapshot includes several bits of information for each thread, including the thread state, a stack trace, any monitor locks held by the thread, any monitor locks the thread is waiting for, and other details. ## Configure Settings @@ -8,7 +8,7 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:ThreadDump:`. | Key | Description | Default | -| --- | --- | --- | +| --- | ----------- | ------- | | `Enabled` | Whether the endpoint is enabled | `true` | | `ID` | The unique ID of the endpoint | `threaddump` | | `Path` | The relative path at which the endpoint is exposed | same as `ID` | @@ -20,10 +20,10 @@ Each key must be prefixed with `Management:Endpoints:ThreadDump:`. ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/threaddump`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddThreadDumpActuator` extension method. @@ -44,7 +44,7 @@ builder.Services.AddThreadDumpActuator(); This endpoint returns a list of threads with their state and stack trace. -The response will always be returned as JSON, like this: +The response always returned as JSON: ```json { From 8f2d1b7d51d6bded7b3b3eb8f7a245e71ff730a2 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Mon, 3 Mar 2025 14:41:00 -0800 Subject: [PATCH 14/43] full edit file share topics --- api/v4/fileshares/index.md | 4 ++-- api/v4/fileshares/usage.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/v4/fileshares/index.md b/api/v4/fileshares/index.md index 5bdc23be..d20fbd9b 100644 --- a/api/v4/fileshares/index.md +++ b/api/v4/fileshares/index.md @@ -1,5 +1,5 @@ # Windows Network File Shares -Steeltoe's `WindowsNetworkFileShare` class provides a simplified experience for interacting with SMB file shares by making [P/Invoke calls](https://learn.microsoft.com/cpp/dotnet/how-to-call-native-dlls-from-managed-code-using-pinvoke) to underlying Windows APIs, specifically to `mpr.dll`. For more background on SMB, see the [Microsoft SMB Protocol documentation](https://learn.microsoft.com/windows/win32/fileio/microsoft-smb-protocol-and-cifs-protocol-overview). +The Steeltoe `WindowsNetworkFileShare` class provides a simplified experience for interacting with SMB file shares by making [P/Invoke calls](https://learn.microsoft.com/cpp/dotnet/how-to-call-native-dlls-from-managed-code-using-pinvoke) to underlying Windows APIs, specifically to `mpr.dll`. For more information about SMB, see the [Microsoft SMB Protocol documentation](https://learn.microsoft.com/windows/win32/fileio/microsoft-smb-protocol-and-cifs-protocol-overview). -Network shares are not the most cloud-native way to deal with files. For new development, consider exploring message queues, caches, blob stores, and NoSQL stores. The alternatives offer greater resiliency and decoupling from backing services. That said, sometimes the alternatives are not viable. For .NET applications deployed to Microsoft Windows Servers, Steeltoe provides a stepping stone towards cloud-native in the form of the `WindowsNetworkFileShare`. For applications deployed to Linux hosts on the Tanzu Platform, [volume services](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/6.0/tas-for-vms/enable-vol-services.html) are available. +Network shares are not the most cloud-native way to deal with files. For new development, consider exploring message queues, caches, blob stores, and NoSQL stores. The alternatives offer greater resiliency and decoupling from backing services. That said, sometimes the alternatives are not viable. For .NET applications deployed to Microsoft Windows Servers, Steeltoe provides a stepping stone towards cloud-native deployment in the form of the `WindowsNetworkFileShare`. For applications deployed to Linux hosts on the Tanzu Platform, [volume services](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/enable-vol-services.html) are available. diff --git a/api/v4/fileshares/usage.md b/api/v4/fileshares/usage.md index becff280..c61895d6 100644 --- a/api/v4/fileshares/usage.md +++ b/api/v4/fileshares/usage.md @@ -1,10 +1,10 @@ -# Usage +# Using Network File Share Before starting with Steeltoe's Windows Network File Share library, you should already have a plan for interacting with the file system. Steeltoe only manages the connection to the file share. ## Add NuGet References -To use the `WindowsNetworkFileShare` class, you need to add a reference to the `Steeltoe.Common.Net` NuGet package. +To use the `WindowsNetworkFileShare` class, add a reference to the `Steeltoe.Common.Net` NuGet package. ## Managing the Connection @@ -36,9 +36,9 @@ using (new WindowsNetworkFileShare(@"\\server\path", new NetworkCredential("user ### Managing Credentials -Credentials are generally required for interacting with SMB shares. `WindowsNetworkFileShare` does not have an opinion on where those credentials are stored. However, as a general guideline, storing credentials with your application's code or standard configuration is not recommended. Consider using the [CredHub Service Broker](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/6.0/tas-for-vms/credhub-index.html) for storing and retrieving your credentials. +Credentials are generally required for interacting with SMB shares. `WindowsNetworkFileShare` does not have an opinion on where those credentials are stored. However, as a general guideline, storing credentials with your application's code or standard configuration is not recommended. Consider using the [CredHub Service Broker](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/credhub-service-broker/services/credhub-sb/index.html) for storing and retrieving your credentials. -When used in conjunction with the Cloud Foundry Configuration Provider, you can access the values as follows: +When used with the Cloud Foundry Configuration Provider, you can access the values as follows: ```shell dotnet add package Steeltoe.Configuration.CloudFoundry From 87ac38ec4eb1bf008d02ce15cb63d2dd7a672bbe Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Tue, 4 Mar 2025 12:33:42 -0800 Subject: [PATCH 15/43] full edit Security topics + some consistency changes --- api/v4/connectors/redis.md | 7 +- api/v4/management/prometheus.md | 4 +- api/v4/management/tasks.md | 2 +- api/v4/security/certificate.md | 56 ++++++------- api/v4/security/index.md | 3 + api/v4/security/jwt-bearer.md | 78 ++++++++++-------- api/v4/security/redis-key-storage-provider.md | 31 +++---- api/v4/security/sso-open-id.md | 81 ++++++++++--------- 8 files changed, 146 insertions(+), 116 deletions(-) diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index a13976a1..1f2e4394 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -1,7 +1,12 @@ -# Redis +# Redis/Valkey This connector simplifies accessing [Redis](https://redis.io/) databases. + +> [!NOTE] +> Redis has been updated to [Valkey](https://valkey.io/topics/migration/). + It supports the following .NET drivers: + - [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis), which provides an `IConnectionMultiplexer`. - [Microsoft.Extensions.Caching.StackExchangeRedis](https://www.nuget.org/packages/Microsoft.Extensions.Caching.StackExchangeRedis), which provides an `IDistributedCache`. diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index 2baa7cf3..47e76137 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -153,7 +153,7 @@ The specific port is not important to Steeltoe, it only matters that the binding Install the metrics-registrar plugin and use it to register your endpoint: -```shell +```bash cf install-plugin -r CF-Community "metric-registrar" cf register-metrics-endpoint APP-NAME /actuator/prometheus --internal-port 8091 ``` @@ -166,7 +166,7 @@ cf register-metrics-endpoint APP-NAME /actuator/prometheus --internal-port 8091 The result of using the metrics registrar plugin is a user-provided service, which can also be created and bound manually. -```shell +```bash cf create-user-provided-service APP-NAME -l secure-endpoint://:8091/actuator/prometheus cf bind-service APP-NAME SERVICE-NAME ``` diff --git a/api/v4/management/tasks.md b/api/v4/management/tasks.md index 79852153..00507776 100644 --- a/api/v4/management/tasks.md +++ b/api/v4/management/tasks.md @@ -111,7 +111,7 @@ As a matter of best practice, it is recommended that you provide the `RunTask` v However, due to the way .NET configuration works, it doesn't matter which configuration provider is used to provide the task name. Invoking the command on Cloud Foundry looks similar to this: -``` +```bash cf run-task YourAppName "dotnet run -- RunTask=ExampleTaskName" --name ExampleTaskName ``` diff --git a/api/v4/security/certificate.md b/api/v4/security/certificate.md index 88cee6c5..7117a7a9 100644 --- a/api/v4/security/certificate.md +++ b/api/v4/security/certificate.md @@ -5,31 +5,31 @@ Certificate Authentication, also known as Mutual TLS, is a way for a client and This library is a supplement to [ASP.NET Core Certificate Authentication](https://learn.microsoft.com/aspnet/core/security/authentication/certauth), adding functionality that helps you use [Cloud Foundry Instance Identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) and authorization policies based on certificate data. Additionally, resources are included for automatically generating certificates for local development that resemble what is found on the platform. -## Usage +## Using Mutual TLS in ASP.NET Core -In order to use this provider, the following steps are required: +To use this provider, the following steps are required: -1. Add NuGet package reference -1. Add identity certificates to the configuration -1. Add and use the security provider in the application -1. Secure your endpoints -1. Attach certificate to requests to secured endpoints +1. Add NuGet package reference. +1. Add identity certificates to the configuration. +1. Add and use the security provider in the application. +1. Secure your endpoints. +1. Attach certificate to requests to secured endpoints. ### Add NuGet Reference > [!NOTE] -> This step is required on all applications that are sending or receiving certificate-authorized requests. +> This step is required for all applications that are sending or receiving certificate-authorized requests. -To use Certificate Authorization, you need to add a reference to the `Steeltoe.Security.Authorization.Certificate` NuGet package. +To use Certificate Authorization, add a reference to the `Steeltoe.Security.Authorization.Certificate` NuGet package. ### Add Identity Certificates to Configuration > [!NOTE] -> This step is required on all applications that are sending or receiving certificate-authorized requests. +> This step is required for all applications that are sending or receiving certificate-authorized requests. In a Cloud Foundry environment, instance identity certificates are automatically provisioned (and rotated on a regular basis) for each application instance. Steeltoe provides the extension method `AddAppInstanceIdentityCertificate` to find the location of the certificate files from the environment variables `CF_INSTANCE_CERT` and `CF_INSTANCE_KEY`. -When running outside of Cloud Foundry, this method will automatically generate similar certificates. +When running outside of Cloud Foundry, this method automatically generates similar certificates. Use the optional parameters to coordinate `orgId` and/or `spaceId` between your applications to facilitate communication when running outside of Cloud Foundry. This code adds the certificate paths to the configuration for use later (and generates the instance identity certificate when running outside Cloud Foundry): @@ -44,25 +44,25 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddAppInstanceIdentityCertificate(new Guid(orgId), new Guid(spaceId)); ``` -When running locally, the code shown above will create a chain of self-signed certificates and the application instance identity certificate will have a subject containing an OrgId of `a8fef16f-94c0-49e3-aa0b-ced7c3da6229` and a SpaceId of `122b942a-d7b9-4839-b26e-836654b9785f`. +When running locally, the preceding code sample creates a chain of self-signed certificates. The application instance identity certificate is created with a subject containing an OrgId of `a8fef16f-94c0-49e3-aa0b-ced7c3da6229` and a SpaceId of `122b942a-d7b9-4839-b26e-836654b9785f`. A root certificate and intermediate certificate are created on disk one level above the current project in a directory named `GeneratedCertificates`. -The root and intermediate certificates will automatically be shared between applications housed within the same solution, so that the applications will be able to trust each other. +The root and intermediate certificates are automatically shared between applications housed within the same solution, so that the applications can trust each other. ### Add and use Certificate Authentication > [!NOTE] -> This section is only required on applications that are receiving certificate-authorized requests. +> This section is required only on applications that are receiving certificate-authorized requests. Several steps need to happen before certificate authorization policies can be used to secure resources: -1. Configuration values need to be bound into named `CertificateOptions` -1. Certificate files need to be monitored for changes (to stay up to date when certificates are rotated) -1. Certificate forwarding needs to be configured (so that ASP.NET reads the certificate out of an HTTP Header) -1. Authentication services need to be added -1. Authorization services and policies need to be added -1. Middleware needs to be activated +1. Bind configuration values into named `CertificateOptions`. +2. Monitor certificate files for changes (to stay up to date when certificates are rotated). +3. Configure certificate forwarding (so that ASP.NET reads the certificate from an HTTP Header). +4. Add authentication services. +5. Add authorization services and policies. +6. Activate middleware. -Fortunately, all of the requirements can be satisfied with a handful of extension methods: +Fortunately, all of these requirements can be satisfied with a handful of extension methods: ```csharp using Steeltoe.Security.Authorization.Certificate; @@ -108,12 +108,12 @@ app.UseCertificateAuthorization(); ### Securing Endpoints > [!NOTE] -> This step is only required on applications that are receiving certificate-authorized requests. +> This step is required only on applications that are receiving certificate-authorized requests. -As implied by the name of the extension method `AddOrgAndSpacePolicies` from the previous section on this page, Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints by using the standard ASP.NET Core `Authorize` attribute with these security policies. +As implied by the name of the extension method `AddOrgAndSpacePolicies` (from the previous section in this topic), Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints using the standard ASP.NET Core `Authorize` attribute with these security policies. > [!NOTE] -> If needed, see the Microsoft documentation about [authorization in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/authorization/introduction) for a better understanding of how to use these attributes. +> For more information about authorization in ASP.NET Core, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/security/authorization/introduction). The following example shows a controller using the security attributes with the included policies: @@ -153,18 +153,18 @@ In the preceding example, when an incoming request is made to the `SameOrgCheck` ### Communicating with Secured Services -In order to use app instance identity certificates in a client application, services need to be configured, but nothing needs to be activated in the ASP.NET Core request pipeline. +To use app instance identity certificates in a client application, services must be configured, but nothing needs to be activated in the ASP.NET Core request pipeline. #### IHttpClientFactory integration > [!NOTE] -> This step is only required on applications that are sending certificate-authorized requests. +> This step is required only on applications that are sending certificate-authorized requests. -For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` named `AddAppInstanceIdentityCertificate`. +For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` called `AddAppInstanceIdentityCertificate`. This method invokes code that handles loading certificates from paths defined in the application's configuration, monitors those file paths and their content for changes, and places the certificate in an HTTP header named `X-Client-Cert` on all outbound requests. > [!NOTE] -> If needed, see the Microsoft documentation about [IHttpClientFactory](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests) for details. +> For more information about IHttpClientFactory, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). ```csharp using Steeltoe.Security.Authorization.Certificate; diff --git a/api/v4/security/index.md b/api/v4/security/index.md index 32ba3f60..9e8ef834 100644 --- a/api/v4/security/index.md +++ b/api/v4/security/index.md @@ -11,3 +11,6 @@ Choose from the following options when using Cloud Foundry security integration: In addition to authentication and authorization providers, Steeltoe security offers: * [A security provider for using Redis on Cloud Foundry with ASP.NET Core Data Protection Key Ring storage](redis-key-storage-provider.md) + +> [!NOTE] +> Redis has been updated to [Valkey](https://valkey.io/topics/migration/). diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index 07581b05..0bbb289c 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -2,15 +2,18 @@ This library is a supplement to ASP.NET Core Security, adding functionality that helps you use Cloud Foundry Security services such as [Single Sign-On for VMware Tanzu](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/index.html) or a [UAA Server](https://github.com/cloudfoundry/uaa) for authentication and authorization using JSON Web Tokens (JWT) in ASP.NET Core web applications. -The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) can help you understand how to use this tool. +For more information, see also the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). -General guidance on JWT is beyond the scope of this document and can be found in many other sources (for example, see [Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token) or [JWT IO](https://jwt.io/)). +General guidance for use of JWT is beyond the scope of this document. For information, see: -For the documentation of the underlying Microsoft Jwt Bearer Authentication library, visit the [official documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-jwt-bearer-authentication). +* [JWT IO](https://jwt.io/) +* [Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token) -## Usage +For information about the underlying Microsoft Jwt Bearer Authentication library, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-jwt-bearer-authentication). -Steps involved in using this library: +## Using JWT in ASP.NET Core + +To use this library: 1. Add NuGet references. 1. Configure settings for the security provider. @@ -20,15 +23,16 @@ Steps involved in using this library: ### Add NuGet References -To use the provider, you need to add a reference to the `Steeltoe.Security.Authentication.JwtBearer` NuGet package. +To use the provider, add: -Also add a reference to `Steeltoe.Configuration.CloudFoundry`, so that Cloud Foundry service bindings can be read by Steeltoe. +* a reference to the `Steeltoe.Security.Authentication.JwtBearer` NuGet package +* a reference to `Steeltoe.Configuration.CloudFoundry` (so that Cloud Foundry service bindings can be read by Steeltoe) ### Configure Settings -Since Steeltoe's JWT Bearer library configures Microsoft's JWT Bearer implementation, all available settings can be found in [`Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions). +The Steeltoe JWT Bearer library configures the Microsoft JWT Bearer implementation, so all supported settings are available in [`Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions). -`JwtBearerOptions` is bound to configuration values found under `Authentication:Schemes:Bearer`. The following example `appsettings.json` shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): +`JwtBearerOptions` is bound to configuration values available in `Authentication:Schemes:Bearer`. The following example `appsettings.json` shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): ```json { @@ -59,7 +63,7 @@ builder.Configuration.AddCloudFoundryServiceBindings(); #### Local UAA -A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: +A UAA server, (such as [UAA Server for Steeltoe](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: ```json { @@ -78,12 +82,12 @@ A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/Steel ``` > [!IMPORTANT] -> If you wish to use the Steeltoe UAA server without modification, some application configuration options will be limited. -> The Steeltoe UAA Server configuration can be found in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L111). +> If you want to use the Steeltoe UAA server without modification, some application configuration options will be limited. +> The Steeltoe UAA Server configuration is available in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L111). ### Add and use JWT Bearer Authentication -Since the majority of the JWT Bearer functionality is provided by Microsoft's libraries, the only difference when using Steeltoe will be the addition of calling `ConfigureJwtBearerForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: +Most of the JWT Bearer functionality is provided by the Microsoft libraries, so the only difference when using Steeltoe is the addition of calling `ConfigureJwtBearerForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: ```csharp using Microsoft.AspNetCore.Authentication.JwtBearer; @@ -102,7 +106,8 @@ builder.Services.AddAuthorizationBuilder() .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); ``` -Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, with the following code: +The order of operations is important: +Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, as shown in the following example. ```csharp var app = builder.Build(); @@ -120,11 +125,11 @@ app.Run(); ``` > [!NOTE] -> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. +> In this sample code, `app.UseForwardedHeaders` is used so that any links generated within the application are compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. ### Securing Endpoints -Once the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: +After the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: ```csharp using Microsoft.AspNetCore.Authorization; @@ -146,29 +151,30 @@ public class SampleController : ControllerBase In the preceding example, if an incoming GET request is made to the `/api/sample` endpoint and the request does not contain a valid JWT bearer token for a user with a `scope` claim equal to `sampleapi.read`, the request is rejected. -Review the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for a demonstration of using a user's access token to interact with downstream APIs, focusing on these locations: +See the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples using a user's access token to interact with downstream APIs, focusing on these locations: -- [Configure ASP.NET Core to save the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/appsettings.json#L15) -- [Get the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/Controllers/HomeController.cs#L60) -- [Include the token in a downstream request](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/ApiClients/JwtAuthorizationApiClient.cs#L24) +* [Configure ASP.NET Core to save the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/appsettings.json#L15) +* [Get the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/Controllers/HomeController.cs#L60) +* [Include the token in a downstream request](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/ApiClients/JwtAuthorizationApiClient.cs#L24) ### Single Sign-On for VMware Tanzu -When using Single Sign-On for VMware Tanzu, you will need to identify the service plan to be used before creating a service instance of that plan. -If you do not have an existing service plan, a platform operator may need to create a new plan for you. -The operator should refer to the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html) for information on how to configure plans for developer use. +When using Single Sign-On for VMware Tanzu, you must identify the service plan to be used before you create a service instance of that plan. +If you do not have an existing service plan, a platform operator might need to create a new plan for you. +For information about service plans for use by developers, see the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). -Once you have identified the service plan that will be used, create a service instance: +After you have identified the service plan to use, create a service instance: -```shell +```bash cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE ``` #### Bind and configure with app manifest -Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. Review the Single Sign-On documentation for [configuring an app manifest](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). +Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. +For information about configuring an app manifest, see the [Single Sign-On documentation](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). -Consider this example manifest that names the application, buildpack and configures several properties for the SSO binding: +Consider this example manifest that names the application and buildpack, and configures properties for the SSO binding: ```yml applications: @@ -186,9 +192,10 @@ applications: #### Bind and configure manually -Alternatively, you can manually bind the instance, restage the app with the Cloud Foundry CLI and later configure the SSO binding yourself with the web interface: +Alternatively, you can bind the instance manually and restage the app with the Cloud Foundry CLI. +Then you can configure the SSO binding with the web interface: -```shell +```bash # Bind service to your app cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE @@ -196,21 +203,24 @@ cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE cf restage MY_APPLICATION ``` -For further information, refer to the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). +For details and instructions, see: + +* the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or +* the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) ### UAA Server -If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA as an alternative. +If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA. -There is no service broker available to manage service instances or bindings for UAA, so a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) must be used to hold the credentials. +There is no service broker available to manage service instances or bindings for UAA, so you must have a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) to hold the credentials. -The following command is an example of how the binding could be created: +This command is an example of how the service instance can be created: ```shell cf cups MY_SERVICE_INSTANCE -p '{"auth_domain": "https://uaa.login.sys.cf-app.com","grant_types": [ "authorization_code", "client_credentials" ],"client_secret": "SOME_CLIENT_SECRET","client_id": "SOME_CLIENT_ID"}' ``` -And the command below is an example of how to bind the service instance to the app: +And to bind the service instance to the app: ```shell cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index d89fdec9..11497706 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -1,15 +1,18 @@ -# Redis Key Storage Provider +# Redis/Valkey Key Storage Provider The Redis Key Storage Provider is commonly used when secured data needs to be shared between two or more instances of the same application. +> [!NOTE] +> Redis has been updated to [Valkey](https://valkey.io/topics/migration/). + By default, the [data protection system in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/data-protection/introduction) stores cryptographic keys on the local file system. Even when not used by the application directly, these cryptographic keys are used for systems like [session state](https://learn.microsoft.com/aspnet/core/fundamentals/app-state#session-state) storage. By using the Steeltoe Redis key storage provider, you can easily reconfigure the data protection service to store these keys in Redis instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). -The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) can help you understand how and why to use this tool. +For more information, see the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md). -## Usage +## Using the Redis/Valkey Storage Provider To use this provider: @@ -18,17 +21,17 @@ To use this provider: 1. Initialize the Steeltoe Connector at startup. 1. Configure the data protection system to persist keys in the Redis database. 1. Add the Cloud Foundry configuration provider. -1. Create a Redis service instance and bind it to your application. +1. Create a Redis/Valkey service instance and bind it to your application. ### Add NuGet References -To use the provider, you need to add a reference to the `Steeltoe.Security.DataProtection.Redis` NuGet package. +To use the provider, add a reference to the `Steeltoe.Security.DataProtection.Redis` NuGet package. -If you are using Cloud Foundry service bindings, you will also need to add a reference to `Steeltoe.Configuration.CloudFoundry`. +If you are using Cloud Foundry service bindings, you must also add a reference to `Steeltoe.Configuration.CloudFoundry`. ### Configure connection string -You must configure a connection string in order to use Redis. +You must configure a connection string to use Redis. The following example `appsettings.Development.json` uses a local Redis server listening on the default Redis port: ```json @@ -47,7 +50,7 @@ The following example `appsettings.Development.json` uses a local Redis server l ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.Redis; @@ -60,7 +63,7 @@ builder.AddRedis(); There are several steps required to configure key storage in Redis: -- Add data protection (while the services are added automatically, this step is required in order to access the builder). +- Add data protection (while the services are added automatically, this step is required for accessing the builder). - Set the key persistence location to Redis. - Set an application name so all instances of the application can see the same data. @@ -75,7 +78,7 @@ builder.Services.AddDataProtection().PersistKeysToRedis().SetApplicationName("re > [!NOTE] > At this point, the keys used by the `DataProtection` framework are stored in the bound Redis service. -> No additional steps are _required_, but you can also [use data protection in your application](https://learn.microsoft.com/aspnet/core/security/data-protection/consumer-apis/overview). +> No additional steps are _required_, but you can also use [data protection](https://learn.microsoft.com/aspnet/core/security/data-protection/consumer-apis/overview) in your application. ### Add Cloud Foundry Configuration @@ -91,7 +94,7 @@ builder.AddCloudFoundryConfiguration(); ### Cloud Foundry -To use the Redis data protection key ring provider on Cloud Foundry, [use a supported Redis service](../connectors/redis.md#cloud-foundry) to create and bind an instance of Redis to your application. +To use the Redis data protection key ring provider on Cloud Foundry, use a supported [Redis service](../connectors/redis.md#cloud-foundry) to create and bind an instance of Redis to your application. You can complete these steps using the Cloud Foundry command line, as follows: @@ -109,11 +112,11 @@ cf bind-service sampleApp sampleRedisService cf restage sampleApp ``` +After the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`. + > [!NOTE] > The preceding commands are for the Redis service provided by Tanzu Platform for Cloud Foundry. > If you use a different service, you have to adjust the `create-service` command. -Once the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`. - > [!NOTE] -> Refer to the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) for a demonstration on why this provider is useful. +> For more information, see the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md). diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index aa45712c..6839ed77 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -1,17 +1,19 @@ # Single Sign-On with OpenID Connect -OpenID Connect is commonly used when users should be able to interact with a collection of applications using a single set of credentials for authentication and authorization. +OpenID Connect is commonly used when users need to be able to interact with a collection of applications using a single set of credentials for authentication and authorization. This library is a supplement to ASP.NET Core Security's OpenID Connect library (`Microsoft.AspNetCore.Authentication.OpenIdConnect`), adding functionality that helps you use Cloud Foundry Security services such as [Single Sign-On for VMware Tanzu](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/index.html) or [User Account and Authentication (UAA) Server](https://github.com/cloudfoundry/uaa). -General guidance on OpenID Connect is beyond the scope of this document and can be found in many other sources (for example, see [OpenID](https://openid.net/developers/how-connect-works/)). -For the documentation of the underlying Microsoft OpenID Connect library, visit the [official documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-oidc-web-authentication). +General guidance on the use of OpenID Connect is beyond the scope of this document; these resources are recommended: -The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) can help you understand how to use this library. +* [OpenID](https://openid.net/developers/how-connect-works/) +* [Microsoft OpenID Connect library](https://learn.microsoft.com/aspnet/core/security/authentication/configure-oidc-web-authentication) -## Usage +For more information about how to use this library, see the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). -Steps involved in using this library: +## Using the OpenID Connect Library + +To use the OpenID Connect Library: 1. Add NuGet references. 1. Configure settings for the security provider. @@ -21,15 +23,16 @@ Steps involved in using this library: ### Add NuGet References -To use this package, you will need to add a reference to the NuGet package `Steeltoe.Security.Authentication.OpenIdConnect`. +To use this package, add references to: -Also add a reference to `Steeltoe.Configuration.CloudFoundry`, so that Cloud Foundry service bindings can be read by Steeltoe. +* the NuGet package `Steeltoe.Security.Authentication.OpenIdConnect` +* `Steeltoe.Configuration.CloudFoundry` (so that Cloud Foundry service bindings can be read by Steeltoe) ### Configure Settings -Since Steeltoe's OpenID Connect library configures Microsoft's OpenID Connect implementation, all available settings can be found in [`Microsoft.AspNetCore.Authentication.OpenIdConnect.OpenIdConnectOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions) +The Steeltoe OpenID Connect library configures the Microsoft OpenID Connect implementation, so all supported settings are available in [`Microsoft.AspNetCore.Authentication.OpenIdConnect.OpenIdConnectOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions). -`OpenIdConnectOptions` is bound to configuration values found under `Authentication:Schemes:OpenIdConnect`. The following example `appsettings.json` shows how to declare a list of permissions that should be requested for users: +`OpenIdConnectOptions` is bound to configuration values found under `Authentication:Schemes:OpenIdConnect`. The following example `appsettings.json` shows how to declare a list of permissions that should be requested for users. ```json { @@ -46,7 +49,7 @@ Since Steeltoe's OpenID Connect library configures Microsoft's OpenID Connect im #### Cloud Foundry Service Bindings -The Steeltoe package `Steeltoe.Configuration.CloudFoundry` reads Single Sign-On credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft's OpenID Connect to read. Add the configuration provider to your application with this code: +The Steeltoe package `Steeltoe.Configuration.CloudFoundry` reads Single Sign-On credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft OpenID Connect to read. Add the configuration provider to your application as shown in the following example. ```csharp using Steeltoe.Configuration.CloudFoundry; @@ -61,7 +64,7 @@ builder.Configuration.AddCloudFoundryServiceBindings(); #### Local UAA -A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)) can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: +A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)) can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but after it is set up, you can configure your `appsettings.Development.json` to work with a local UAA server using code similar to the following example: ```json { @@ -80,13 +83,13 @@ A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/Steel ``` > [!IMPORTANT] -> If you wish to use the Steeltoe UAA server without modification, some application configuration options will be very limited. -> Because the OpenID Connect authentication flow requires user redirection to known locations, the client `steeltoesamplesclient` is expected to listen at , so you will need to update launchSettings.json accordingly. -> The Steeltoe UAA Server configuration can be found in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L116). +> If you want to use the Steeltoe UAA server without modification, some application configuration options will be very limited. +> Because the OpenID Connect authentication flow requires user redirection to known locations, the client `steeltoesamplesclient` is expected to listen at , so you must update `launchSettings.json` accordingly. +> The Steeltoe UAA Server configuration is located in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L116). ### Add and use OpenID Connect -Since the majority of the OpenID Connect functionality is provided by Microsoft's libraries, the only difference when using Steeltoe will be the addition of calling `ConfigureOpenIdConnectForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: +Most of the OpenID Connect functionality is provided by the Microsoft libraries, so the only difference when using Steeltoe is that you must also call `ConfigureOpenIdConnectForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: ```csharp using Microsoft.AspNetCore.Authentication.Cookies; @@ -115,7 +118,8 @@ builder.Services.AddAuthorizationBuilder() .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); ``` -Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, with the following code: +The order of operations is important: +Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, as shown in the following example. ```csharp using Microsoft.AspNetCore.HttpOverrides; @@ -135,11 +139,11 @@ app.Run(); ``` > [!NOTE] -> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. +> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application are compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. ### Securing Endpoints -Once the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: +After the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: ```csharp using Microsoft.AspNetCore.Authorization; @@ -170,25 +174,26 @@ The preceding example establishes the following security rules: > The Steeltoe UAA server has several pre-provisioned user accounts. Sign in with `testuser` and password `password` to access resources secured with `sampleapi.read` > To test with a user that does not have the permission `sampleapi.read`, sign in with the user `customer` and password `password`. > -> You may want to explore the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples of additional basic functionality such as signing out of the application. +> See the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples of additional basic functionality, such as signing out of the application. ### Single Sign-On for VMware Tanzu -When using Single Sign-On for VMware Tanzu, you will need to identify the service plan to be used before creating a service instance of that plan. +When using Single Sign-On for VMware Tanzu, you must identify the service plan to be used before creating a service instance of that plan. If you do not have an existing service plan, a platform operator may need to create a new plan for you. -The operator should refer to the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html) for information on how to configure plans for developer use. +For the operator resource, see the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). This guide contains information about how to configure plans for developer use. -Once you have identified the service plan that will be used, create a service instance: +After you have identified the service plan to use, create a service instance: -```shell +```bash cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE ``` #### Bind and configure with app manifest -Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. Review the Single Sign-On documentation for [configuring an app manifest](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). +Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. +For information about configuring an app manifest, see the [Single Sign-On documentation](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). -Consider this example manifest that names the application, buildpack and configures several properties for the SSO binding: +Consider this example manifest that names the application and buildpack, and configures properties for the SSO binding: ```yml applications: @@ -207,9 +212,10 @@ applications: #### Bind and configure manually -Alternatively, you can manually bind the instance, restage the app with the Cloud Foundry CLI and later configure the SSO binding yourself with the web interface: +Alternatively, you can bind the instance manually and restage the app with the Cloud Foundry CLI. +Then you can configure the SSO binding with the web interface: -```shell +```bash # Bind service to your app cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE @@ -217,24 +223,27 @@ cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE cf restage MY_APPLICATION ``` -For further information, such as instructions on using the web interface, refer to the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). +For more information, see: + +* [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) +* [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). ### UAA Server -If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA as an alternative. +If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA. -There is no service broker available to manage service instances or bindings for UAA, so a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) should be used to hold the credentials. +There is no service broker available to manage service instances or bindings for UAA, so you must have a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) to hold the credentials. -This command is an example of how the binding could be created: +This command is an example of how the service instance can be created: -```shell +```bash cf cups MY_SERVICE_INSTANCE -p '{"auth_domain": "https://uaa.login.sys.cf-app.com","grant_types": [ "authorization_code", "client_credentials" ],"client_secret": "SOME_CLIENT_SECRET","client_id": "SOME_CLIENT_ID"}' ``` -And this command is an example of how to bind the service instance to the app: +And to bind the service instance to the app: -```shell +```bash cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE ``` -For additional information, refer to the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). +For additional information, see the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). From 35e6328290c0543cca4db4219983463d15dd29dc Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Wed, 5 Mar 2025 13:23:02 -0800 Subject: [PATCH 16/43] full edit connector topics (1) --- api/v4/connectors/extensibility.md | 2 +- api/v4/connectors/index.md | 4 +- api/v4/connectors/microsoft-sql-server.md | 92 +++++++++--------- api/v4/connectors/mysql.md | 108 ++++++++++++---------- api/v4/connectors/postgresql.md | 86 +++++++++-------- api/v4/connectors/rabbitmq.md | 20 ++-- api/v4/connectors/usage.md | 66 ++++++------- api/v4/toc.yml | 4 +- 8 files changed, 201 insertions(+), 181 deletions(-) diff --git a/api/v4/connectors/extensibility.md b/api/v4/connectors/extensibility.md index 47e8bfe0..7e8cc99c 100644 --- a/api/v4/connectors/extensibility.md +++ b/api/v4/connectors/extensibility.md @@ -1,6 +1,6 @@ # Extensibility -Connectors were redesigned from scratch in Steeltoe v4. At the time of writing, extensibility is not yet available. +Connectors were redesigned in Steeltoe v4, and extensibility is not yet available. We intend to address this gap in the near future. Please follow along and add any input you may have on [this issue](https://github.com/SteeltoeOSS/Steeltoe/issues/1154). See [Advanced settings](usage.md#advanced-settings) to customize the built-in Connectors. diff --git a/api/v4/connectors/index.md b/api/v4/connectors/index.md index e9b6b56b..4e580110 100644 --- a/api/v4/connectors/index.md +++ b/api/v4/connectors/index.md @@ -6,7 +6,7 @@ Connectors are primarily a bonding layer between your infrastructure and your ap Connectors don't directly manipulate the connection to backing services, but do contain logic for turning raw credentials into formatted connection strings and also provide health monitoring tools. -Get started with the [basic concepts](usage.md) or go directly to any supported technology: +Get started with the basic concepts in [Usage](usage.md) or go directly to any supported technology: - [MySQL](mysql.md) - [Microsoft SQL Server](microsoft-sql-server.md) @@ -14,4 +14,4 @@ Get started with the [basic concepts](usage.md) or go directly to any supported - [RabbitMQ](rabbitmq.md) - [MongoDB](mongodb.md) - [CosmosDB](cosmosdb.md) -- [Redis](redis.md) +- [Redis/Valkey](redis.md) diff --git a/api/v4/connectors/microsoft-sql-server.md b/api/v4/connectors/microsoft-sql-server.md index 6143765c..49cbe3ac 100644 --- a/api/v4/connectors/microsoft-sql-server.md +++ b/api/v4/connectors/microsoft-sql-server.md @@ -2,15 +2,17 @@ This connector simplifies accessing [Microsoft SQL Server](https://www.microsoft.com/sql-server) databases. It supports the following .NET drivers: -- [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient), which provides an ADO.NET `DbConnection`. -- [System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient), which provides an ADO.NET `DbConnection`. -- [Microsoft.EntityFrameworkCore.SqlServer](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.SqlServer), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient), which provides an ADO.NET `DbConnection` +- [System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient), which provides an ADO.NET `DbConnection` +- [Microsoft.EntityFrameworkCore.SqlServer](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.SqlServer), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md). + +## Using the Microsoft SQL Server Connector To use this connector: + 1. Create a SQL Server instance or use [SQL Server Express LocalDB](https://learn.microsoft.com/sql/database-engine/configure-windows/sql-server-express-localdb). 1. Add NuGet references to your project. 1. Configure your connection string in `appsettings.json`. @@ -26,7 +28,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for SQL Server are documented [here](https://learn.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring#remarks). +The available connection string parameters for SQL Server are documented in the [Microsoft documentation](https://learn.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring#remarks). The following example `appsettings.json` uses SQL Server Express LocalDB: @@ -86,61 +88,65 @@ public class HomeController : Controller ### Use Entity Framework Core -Start by defining your `DbContext` class: -```csharp -public class AppDbContext : DbContext -{ - public DbSet SampleEntities => Set(); +Follow this procedure: - public AppDbContext(DbContextOptions options) - : base(options) +1. Define your `DbContext` class: + + ```csharp + public class AppDbContext : DbContext { + public DbSet SampleEntities => Set(); + + public AppDbContext(DbContextOptions options) + : base(options) + { + } } -} -public class SampleEntity -{ - public long Id { get; set; } - public string? Text { get; set; } -} -``` + public class SampleEntity + { + public long Id { get; set; } + public string? Text { get; set; } + } + ``` -Next, call the `UseSqlServer()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: +1. Call the `UseSqlServer()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: -```csharp -using Steeltoe.Connectors.EntityFrameworkCore.SqlServer; -using Steeltoe.Connectors.SqlServer; + ```csharp + using Steeltoe.Connectors.EntityFrameworkCore.SqlServer; + using Steeltoe.Connectors.SqlServer; -var builder = WebApplication.CreateBuilder(args); -builder.AddSqlServer(); + var builder = WebApplication.CreateBuilder(args); + builder.AddSqlServer(); -builder.Services.AddDbContext( - (serviceProvider, options) => options.UseSqlServer(serviceProvider)); -``` + builder.Services.AddDbContext( + (serviceProvider, options) => options.UseSqlServer(serviceProvider)); + ``` -Once you have configured and added your `DbContext` to the service container, +1. After you have configured and added your `DbContext` to the service container, you can inject it and use it in a controller or view: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.EntityFrameworkCore; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.EntityFrameworkCore; -public class HomeController : Controller -{ - public async Task Index([FromServices] AppDbContext appDbContext) - { - List entities = await appDbContext.SampleEntities.ToListAsync(); - return View(entities); - } -} -``` + public class HomeController : Controller + { + public async Task Index([FromServices] AppDbContext appDbContext) + { + List entities = await appDbContext.SampleEntities.ToListAsync(); + return View(entities); + } + } + ``` A complete sample app that uses Entity Framework Core with SQL Server is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/SqlServerEFCore. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index 00774ec4..d805a6c5 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -2,14 +2,15 @@ This connector simplifies accessing [MySQL](https://www.mysql.com/) databases. It supports the following .NET drivers: -- [MySqlConnector](https://www.nuget.org/packages/MySqlConnector), which provides an ADO.NET `DbConnection`. -- [MySql.Data](https://www.nuget.org/packages/MySql.Data), which provides an ADO.NET `DbConnection`. -- [Pomelo.EntityFrameworkCore.MySql](https://www.nuget.org/packages/Pomelo.EntityFrameworkCore.MySql), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -- [MySql.EntityFrameworkCore](https://www.nuget.org/packages/MySql.EntityFrameworkCore), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [MySqlConnector](https://www.nuget.org/packages/MySqlConnector), which provides an ADO.NET `DbConnection` +- [MySql.Data](https://www.nuget.org/packages/MySql.Data), which provides an ADO.NET `DbConnection` +- [Pomelo.EntityFrameworkCore.MySql](https://www.nuget.org/packages/Pomelo.EntityFrameworkCore.MySql), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support +- [MySql.EntityFrameworkCore](https://www.nuget.org/packages/MySql.EntityFrameworkCore), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -## Usage +The remainder of this page assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md). + +## Using the MySQL connector To use this connector: @@ -21,16 +22,20 @@ To use this connector: ### Add NuGet References -To use this connector, add a NuGet reference to `Steeltoe.Connectors`. If you're using Entity Framework Core, add a +To use this connector, add a NuGet reference to `Steeltoe.Connectors`. +If you're using Entity Framework Core, add a NuGet reference to `Steeltoe.Connectors.EntityFrameworkCore` instead. Also add a NuGet reference to one of the .NET drivers listed above, as you would if you were not using Steeltoe. ### Configure connection string -The available connection string parameters for MySQL are documented [here](https://mysqlconnector.net/connection-options/) and [here](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connection-parameters-base). +For the available connection string parameters for MySQL, see: + +* [MySQL Connector documentation](https://mysqlconnector.net/connection-options/) +* [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connection-parameters-base) -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container from the earlier example: ```json { @@ -48,7 +53,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` as shown here to initialize the Connector: ```csharp using Steeltoe.Connectors.MySql; @@ -90,65 +95,68 @@ A complete sample app that uses `MySqlConnection` is provided at https://github. ### Use Entity Framework Core -Start by defining your `DbContext` class: -```csharp -public class AppDbContext : DbContext -{ - public DbSet SampleEntities => Set(); +Follow this procedure: - public AppDbContext(DbContextOptions options) - : base(options) +1. Define your `DbContext` class: + + ```csharp + public class AppDbContext : DbContext { + public DbSet SampleEntities => Set(); + + public AppDbContext(DbContextOptions options) + : base(options) + { + } } -} -public class SampleEntity -{ - public long Id { get; set; } - public string? Text { get; set; } -} -``` + public class SampleEntity + { + public long Id { get; set; } + public string? Text { get; set; } + } + ``` -Next, call the `UseMySql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: +1. Call the `UseMySql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: -```csharp -using Steeltoe.Connectors.EntityFrameworkCore.MySql; -using Steeltoe.Connectors.MySql; + ```csharp + using Steeltoe.Connectors.EntityFrameworkCore.MySql; + using Steeltoe.Connectors.MySql; -var builder = WebApplication.CreateBuilder(args); -builder.AddMySql(); + var builder = WebApplication.CreateBuilder(args); + builder.AddMySql(); -builder.Services.AddDbContext( - (serviceProvider, options) => options.UseMySql(serviceProvider)); -``` + builder.Services.AddDbContext( + (serviceProvider, options) => options.UseMySql(serviceProvider)); + ``` -Once you have configured and added your `DbContext` to the service container, +1. After you have configured and added your `DbContext` to the service container, you can inject it and use it in a controller or view: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.EntityFrameworkCore; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.EntityFrameworkCore; -public class HomeController : Controller -{ - public async Task Index([FromServices] AppDbContext appDbContext) + public class HomeController : Controller { - List entities = await appDbContext.SampleEntities.ToListAsync(); - return View(entities); + public async Task Index([FromServices] AppDbContext appDbContext) + { + List entities = await appDbContext.SampleEntities.ToListAsync(); + return View(entities); + } } -} -``` + ``` A complete sample app that uses Entity Framework Core with MySQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySqlEFCore. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware SQL with MySQL for Tanzu Application Service](https://docs.vmware.com/en/VMware-SQL-with-MySQL-for-Tanzu-Application-Service/3.0/mysql-for-tas/index.html) -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for GCP](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-GCP/1.2/csb-gcp/GUID-index.html) +- [VMware Tanzu for MySQL on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-for-mysql-on-cloud-foundry/3-3/mysql-for-tpcf/about_mysql_vms.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) +- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) -You can create and bind an instance to your application by using the Cloud Foundry CLI: +You can create and bind an instance to your application using the Cloud Foundry CLI: ```bash # Create MySQL service @@ -164,6 +172,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the Bitnami [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index 541b3d46..88cb3f7d 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -26,9 +26,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for PostgreSQL are documented [here](https://www.npgsql.org/doc/connection-string-parameters.html). +The available connection string parameters for PostgreSQL are described in the [Npgsql documentation](https://www.npgsql.org/doc/connection-string-parameters.html). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container from the previous example: ```json { @@ -46,7 +46,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.PostgreSql; @@ -88,62 +88,66 @@ A complete sample app that uses `NpgsqlConnection` is provided at https://github ### Use Entity Framework Core -Start by defining your `DbContext` class: -```csharp -public class AppDbContext : DbContext -{ - public DbSet SampleEntities => Set(); +Follow these instructions: + +1. Define your `DbContext` class: - public AppDbContext(DbContextOptions options) - : base(options) + ```csharp + public class AppDbContext : DbContext { + public DbSet SampleEntities => Set(); + + public AppDbContext(DbContextOptions options) + : base(options) + { + } } -} -public class SampleEntity -{ - public long Id { get; set; } - public string? Text { get; set; } -} -``` + public class SampleEntity + { + public long Id { get; set; } + public string? Text { get; set; } + } + ``` -Next, call the `UseNpgsql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: +1. Call the `UseNpgsql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: -```csharp -using Steeltoe.Connectors.EntityFrameworkCore.PostgreSql; -using Steeltoe.Connectors.PostgreSql; + ```csharp + using Steeltoe.Connectors.EntityFrameworkCore.PostgreSql; + using Steeltoe.Connectors.PostgreSql; -var builder = WebApplication.CreateBuilder(args); -builder.AddPostgreSql(); + var builder = WebApplication.CreateBuilder(args); + builder.AddPostgreSql(); -builder.Services.AddDbContext( - (serviceProvider, options) => options.UseNpgsql(serviceProvider)); -``` + builder.Services.AddDbContext( + (serviceProvider, options) => options.UseNpgsql(serviceProvider)); + ``` -Once you have configured and added your `DbContext` to the service container, +1. After you have configured and added your `DbContext` to the service container, you can inject it and use it in a controller or view: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.EntityFrameworkCore; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.EntityFrameworkCore; -public class HomeController : Controller -{ - public async Task Index([FromServices] AppDbContext appDbContext) + public class HomeController : Controller { - List entities = await appDbContext.SampleEntities.ToListAsync(); - return View(entities); + public async Task Index([FromServices] AppDbContext appDbContext) + { + List entities = await appDbContext.SampleEntities.ToListAsync(); + return View(entities); + } } -} -``` + ``` A complete sample app that uses Entity Framework Core with PostgreSQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSqlEFCore. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for GCP](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-GCP/1.2/csb-gcp/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) +- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: @@ -161,6 +165,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the Bitnami [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index 396aac46..1b2dbfc2 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -2,11 +2,12 @@ This connector simplifies accessing [RabbitMQ](https://www.rabbitmq.com/) message brokers. It supports the following .NET drivers: + - [RabbitMQ.Client](https://www.nuget.org/packages/RabbitMQ.Client), which provides an `IConnection`. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +The remainder of this page assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. -## Usage +## Using the RabbitMQ connector To use this connector: @@ -24,9 +25,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for RabbitMQ are documented [here](https://www.rabbitmq.com/uri-spec.html). +The available connection string parameters for RabbitMQ are described in the [RabbitMQ documentation](https://www.rabbitmq.com/uri-spec.html). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container from earlier: ```json { @@ -44,7 +45,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.RabbitMQ; @@ -87,9 +88,10 @@ A complete sample app that uses `IConnection` is provided at https://github.com/ ## Cloud Foundry This Connector supports the following service brokers: -- [VMware RabbitMQ for Tanzu Application Service](https://docs.vmware.com/en/VMware-RabbitMQ-for-Tanzu-Application-Service/2.2/tanzu-rmq/GUID-index.html) -You can create and bind an instance to your application by using the Cloud Foundry CLI: +- [VMware Tanzu RabbitMQ on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-rabbitmq-on-cloud-foundry/10-0/tanzu-rabbitmq-cloud-foundry/index.html) + +You can create and bind an instance to your application using the Cloud Foundry CLI: ```bash # Create RabbitMQ service @@ -105,6 +107,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the Bitnami [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/usage.md b/api/v4/connectors/usage.md index b190ba9d..f32be898 100644 --- a/api/v4/connectors/usage.md +++ b/api/v4/connectors/usage.md @@ -1,19 +1,19 @@ -## Overview +# Overview -Steeltoe Connectors provide access to both low-level connection strings and higher-level driver-specific .NET +Steeltoe Connectors provide access to both low-level connection strings and higher-level, driver-specific .NET connection/client instances. Local connection strings are merged with settings from the cloud. [Health checks](../management/health.md) are registered for use with Steeltoe Management Actuators. Additional extension methods are provided for integration with Entity Framework Core. -This page covers the basic concepts of Connectors, how they work, and how to use them. -The rest of the pages cover information that is specific to the various .NET drivers. +This topic covers the basic concepts of Connectors, how they work, and how to use them. +The remaining Connectors topics cover information specific to the various .NET drivers. -### Connection strings +## Connection strings -At its core, a Steeltoe Connector reads a connection string from appsettings and exposes it via the +A Steeltoe Connector reads a connection string from `appsettings` and exposes it through the [ASP.NET Options pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options). -For example, given the next `appsettings.json`: +For example, given the following `appsettings.json`: ```json { @@ -30,8 +30,8 @@ For example, given the next `appsettings.json`: } ``` -and NuGet references to `Steeltoe.Connectors` and [Npgsql](https://www.nuget.org/packages/Npgsql), -the code fragment below reads the PostgreSQL connection string and prints it. +And NuGet references to `Steeltoe.Connectors` and [Npgsql](https://www.nuget.org/packages/Npgsql), +the following code fragment reads the PostgreSQL connection string and prints it. ```csharp using Microsoft.Extensions.Options; @@ -46,7 +46,7 @@ var options = app.Services.GetRequiredService>(); Console.WriteLine(options.Value.ConnectionString); ``` -This outputs: +The output is: ``` Host=localhost;Database=steeltoe;Username=steeltoe;Password=steeltoe;Log Parameters=True @@ -55,32 +55,33 @@ Host=localhost;Database=steeltoe;Username=steeltoe;Password=steeltoe;Log Paramet Notice that the parameter names are slightly different in the printed output. This is because Steeltoe relies on the [DbConnectionStringBuilder](https://learn.microsoft.com/dotnet/api/system.data.common.dbconnectionstringbuilder) of the [PostgreSQL .NET driver](https://www.npgsql.org/doc/api/Npgsql.NpgsqlConnectionStringBuilder.html), which normalizes the parameter names. -The advantage of this approach is that you're free to use any driver-specific connection string parameters, +The advantage of this approach is that you can use any driver-specific connection string parameters, without the need for Steeltoe to understand them first. > [!NOTE] > Earlier versions of Steeltoe assigned default values (such as "localhost") for required connection string parameters that were not specified -in configuration. This is no longer the case. In practice, this means you'll need to configure a connection string in most cases to run locally. +in configuration. This is no longer the case. In practice, this means that to run locally, you must configure a connection string in most cases. ### Cloud-hosted applications When your app is running in Cloud Foundry or Kubernetes, the Connector enriches the local connection string from `appsettings.json` -by merging any cloud-provided parameters into it. The resulting connection string is exposed via the Options pattern in the -same way as described above. +by merging any cloud-provided parameters into it. The resulting connection string is exposed through the Options pattern in the +same way as described in the previous section. The Connector automatically detects when merging is needed: + - When running in Cloud Foundry, it reads the connection parameters from the JSON in the `VCAP_SERVICES` environment variable. For more information on `VCAP_SERVICES`, see the [Cloud Foundry documentation](https://docs.cloudfoundry.org/services/binding-credentials.html). - When running in Kubernetes, it reads the secret files from the directory that the `SERVICE_BINDING_ROOT` environment variable points to. For more information on `SERVICE_BINDING_ROOT`, see the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -### Named connection strings +## Named connection strings -Multiple service bindings can be accessed using named options. Just replace "Default" in your `appsettings.json` with the name +Multiple service bindings can be accessed using named options. Replace `Default` in your `appsettings.json` with the name of the service binding. -For example, the next `appsettings.json` file contains two named connection strings: +For example, the following `appsettings.json` file contains two named connection strings that can be accessed in the code fragment that follows the `appsettings.json`: ```json { @@ -101,8 +102,6 @@ For example, the next `appsettings.json` file contains two named connection stri } ``` -which can be accessed using the code fragment below. - ```csharp using Microsoft.Extensions.Options; using Steeltoe.Connectors.PostgreSql; @@ -117,22 +116,22 @@ Console.WriteLine(optionsMonitor.Get("MyServiceOne").ConnectionString); Console.WriteLine(optionsMonitor.Get("MyServiceTwo").ConnectionString); ``` -This outputs: +This is the output: ``` Host=host1;Database=db1;Username=user1;Password=pass1;Include Error Detail=True Host=host1;Database=db2;Username=user2;Password=pass2;Log Parameters=True ``` -When using cloud hosting, the local connection string names need to match the service binding names in the cloud for proper +When using cloud hosting, the local connection string names must match the service binding names in the cloud for proper merging to take place. -However, for convenience, if you have a single named service binding in the cloud, you can just use "Default" locally. -This is useful if you don't know the cloud-hosted service binding name upfront while developing your application. +However, for convenience, if you have a single named service binding in the cloud, you can use `Default` locally. +This is useful if you don't know the cloud-hosted service binding name upfront as you are developing your application. ## Connection/client instances -On top of the exposed connection string, a Steeltoe Connector provides a factory to obtain driver-specific connection/client instances. +In addition to the exposed connection string, a Steeltoe Connector provides a factory to obtain driver-specific connection/client instances. The example below uses the same `appsettings.json` file from before, but obtains a connection from the factory: @@ -162,7 +161,7 @@ using NpgsqlConnection connectionOne = connectorOne.GetConnection(); connectionOne.Open(); ``` -Per named service, `ConnectorFactory` either returns a new connection/client instance each time or caches the first one, +`ConnectorFactory` either returns a new connection/client instance each time or caches the first one, based on documented best practices for the specific .NET driver. ## Legacy host builders @@ -173,7 +172,8 @@ If you're using the legacy [IHostBuilder](https://learn.microsoft.com/aspnet/cor [IWebHostBuilder](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host), you need to call two methods instead. For example, when using MySQL with `IWebHostBuilder`, add a NuGet reference to -[MySqlConnector](https://www.nuget.org/packages/MySqlConnector) and call both `ConfigureMySql()` and `AddMySql()`: +[MySqlConnector](https://www.nuget.org/packages/MySqlConnector) and call both `ConfigureMySql()` and `AddMySql()` +as shown in the following example: ```csharp using Microsoft.AspNetCore; @@ -203,7 +203,7 @@ internal static class Program To use the merged connection string with Entity Framework Core, add a NuGet reference to `Steeltoe.Connectors.EntityFrameworkCore` and call the corresponding `Use*` Steeltoe method, in addition to adding the Connector to the host builder as shown before. -For example, given the next `appsettings.json`: +For example, given the following `appsettings.json` example: ```json { @@ -249,7 +249,7 @@ public class AppDbContext : DbContext } ``` -This outputs: +This is the output: ``` Data Source=(localdb)\mssqllocaldb;Initial Catalog=ExampleDB;Pooling=True @@ -271,7 +271,7 @@ builder.Services.AddDbContext( ## Advanced settings -Usage of the ASP.NET Options pattern by Steeltoe Connectors enables configuring them using custom code. +Using the ASP.NET Options pattern by Steeltoe Connectors allows you to configure them using custom code. For example, the code below adds the application name to the MongoDB connection URL at runtime: @@ -293,9 +293,9 @@ builder.Services.Configure(options => }); ``` -The Steeltoe Connector extension methods provide overloads to influence how they work. This enables to hook in custom logic -to construct the connection/client instance and override its lifetime. Or override if and how health checks are registered. -See the documentation on `ConnectorConfigureOptionsBuilder` and `ConnectorAddOptionsBuilder` for details. +The Steeltoe Connector extension methods provide overloads to influence how they work. This allows you to hook in custom logic +to construct the connection/client instance and override its lifetime, or to override whether and how health checks are registered. +See the documentation about `ConnectorConfigureOptionsBuilder` and `ConnectorAddOptionsBuilder` for details. The example below overrides the creation of the Redis `ConnectionMultiplexer` instance and turns off health checks: @@ -327,7 +327,7 @@ builder.AddRedis(null, addOptions => ``` The Steeltoe Connector extension methods for Entity Framework Core take an optional parameter to configure the driver-specific -settings. But because Steeltoe has no compile-time reference to the drivers, you need to upcast its parameter first. +settings. But because Steeltoe has no compile-time reference to the drivers, you must upcast its parameter first. The next example activates the retry policy on the SQL Server provider for Entity Framework Core: diff --git a/api/v4/toc.yml b/api/v4/toc.yml index dc5e8416..18cbb283 100644 --- a/api/v4/toc.yml +++ b/api/v4/toc.yml @@ -92,7 +92,7 @@ topicHref: fileshares/ items: - topicHref: fileshares/usage.md - name: Usage + name: Using Network File Share - name: Security topicHref: security/ items: @@ -108,7 +108,7 @@ topicHref: connectors/ items: - topicHref: connectors/usage.md - name: Usage + name: Overview - topicHref: connectors/extensibility.md name: Extensibility - topicHref: connectors/mysql.md From f45262fdc0eb5503b446946e8feb42ebd8157472 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Wed, 5 Mar 2025 14:05:26 -0800 Subject: [PATCH 17/43] full edit connector topics (2) --- api/v4/connectors/cosmosdb.md | 101 +++++++++++++++++--------------- api/v4/connectors/mongodb.md | 22 +++---- api/v4/connectors/mysql.md | 5 +- api/v4/connectors/postgresql.md | 4 +- api/v4/connectors/rabbitmq.md | 4 +- api/v4/connectors/redis.md | 30 +++++----- api/v4/toc.yml | 2 +- 7 files changed, 89 insertions(+), 79 deletions(-) diff --git a/api/v4/connectors/cosmosdb.md b/api/v4/connectors/cosmosdb.md index 351130a0..0fefc984 100644 --- a/api/v4/connectors/cosmosdb.md +++ b/api/v4/connectors/cosmosdb.md @@ -2,11 +2,12 @@ This connector simplifies accessing [Azure CosmosDB](https://azure.microsoft.com/products/cosmos-db/) databases. It supports the following .NET drivers: -- [Microsoft.Azure.Cosmos](https://www.nuget.org/packages/Microsoft.Azure.Cosmos), which provides a `CosmosClient`. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [Microsoft.Azure.Cosmos](https://www.nuget.org/packages/Microsoft.Azure.Cosmos), which provides a `CosmosClient` -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the CosmosDB connector To use this connector: @@ -24,7 +25,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The CosmosDB connection string can be obtained as described [here](https://learn.microsoft.com/azure/cosmos-db/nosql/how-to-dotnet-get-started#retrieve-your-account-connection-string). +The CosmosDB connection string can be obtained as described in the [Microsoft documentation](https://learn.microsoft.com/azure/cosmos-db/nosql/how-to-dotnet-get-started#retrieve-your-account-connection-string). The following example `appsettings.json` uses the emulator: @@ -43,12 +44,12 @@ The following example `appsettings.json` uses the emulator: } ``` -Notice this configuration file contains the database name, in addition to the connection string. This value is exposed +Notice that this configuration file contains the database name, in addition to the connection string. This value is exposed as `CosmosDbOptions.Database`. ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.CosmosDb; @@ -59,71 +60,75 @@ builder.AddCosmosDb(); ### Use CosmosClient -Start by defining a class that contains container data: -```csharp -using Newtonsoft.Json; +Follow this procedure: -public class SampleObject -{ - [JsonProperty(PropertyName = "id")] - public string Id { get; set; } +1. Define a class that contains container data: - public string? Text { get; set; } -} -``` + ```csharp + using Newtonsoft.Json; -To obtain a `CosmosClient` instance in your application, inject the Steeltoe factory in a controller or view: + public class SampleObject + { + [JsonProperty(PropertyName = "id")] + public string Id { get; set; } -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.Azure.Cosmos; -using Microsoft.Azure.Cosmos.Linq; -using Steeltoe.Connectors; -using Steeltoe.Connectors.CosmosDb; + public string? Text { get; set; } + } + ``` -public class HomeController : Controller -{ - public async Task Index( - [FromServices] ConnectorFactory connectorFactory) - { - var connector = connectorFactory.Get(); - CosmosClient client = connector.GetConnection(); +1. To obtain a `CosmosClient` instance in your application, inject the Steeltoe factory in a controller or view: - Container container = client.GetContainer(connector.Options.Database, "TestContainer"); - List sampleObjects = new(); + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.Azure.Cosmos; + using Microsoft.Azure.Cosmos.Linq; + using Steeltoe.Connectors; + using Steeltoe.Connectors.CosmosDb; - await foreach (SampleObject sampleObject in GetAllAsync(container)) + public class HomeController : Controller + { + public async Task Index( + [FromServices] ConnectorFactory connectorFactory) { - sampleObjects.Add(sampleObject); - } + var connector = connectorFactory.Get(); + CosmosClient client = connector.GetConnection(); - return View(sampleObjects); - } + Container container = client.GetContainer(connector.Options.Database, "TestContainer"); + List sampleObjects = new(); - private async IAsyncEnumerable GetAllAsync(Container container) - { - using FeedIterator iterator = - container.GetItemLinqQueryable().ToFeedIterator(); + await foreach (SampleObject sampleObject in GetAllAsync(container)) + { + sampleObjects.Add(sampleObject); + } - while (iterator.HasMoreResults) + return View(sampleObjects); + } + + private async IAsyncEnumerable GetAllAsync(Container container) { - FeedResponse response = await iterator.ReadNextAsync(); + using FeedIterator iterator = + container.GetItemLinqQueryable().ToFeedIterator(); - foreach (SampleObject sampleObject in response) + while (iterator.HasMoreResults) { - yield return sampleObject; + FeedResponse response = await iterator.ReadNextAsync(); + + foreach (SampleObject sampleObject in response) + { + yield return sampleObject; + } } } } -} -``` + ``` A complete sample app that uses `CosmosClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/CosmosDb. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index c38d8554..6ee3fdae 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -2,11 +2,12 @@ This connector simplifies accessing [MongoDB](https://www.mongodb.com/) databases. It supports the following .NET drivers: -- [MongoDB.Driver](https://www.nuget.org/packages/MongoDB.Driver), which provides an `IMongoClient`. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [MongoDB.Driver](https://www.nuget.org/packages/MongoDB.Driver), which provides an `IMongoClient` -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the MongoDB connector To use this connector: @@ -24,9 +25,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for MongoDB are documented [here](https://www.mongodb.com/docs/manual/reference/connection-string/). +The available connection string parameters for MongoDB are described in the [MongoDB documentation](https://www.mongodb.com/docs/manual/reference/connection-string/). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container used earlier: ```json { @@ -43,12 +44,12 @@ The following example `appsettings.json` uses the docker container from above: } ``` -Notice this configuration file contains the database name, in addition to the connection string. This value is exposed +Notice that this configuration file contains the database name, in addition to the connection string. This value is exposed as `MongoDbOptions.Database`. ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.MongoDb; @@ -101,7 +102,8 @@ A complete sample app that uses `IMongoClient` is provided at https://github.com ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: @@ -119,6 +121,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index d805a6c5..26fc94ad 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -8,7 +8,7 @@ It supports the following .NET drivers: - [Pomelo.EntityFrameworkCore.MySql](https://www.nuget.org/packages/Pomelo.EntityFrameworkCore.MySql), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support - [MySql.EntityFrameworkCore](https://www.nuget.org/packages/MySql.EntityFrameworkCore), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -The remainder of this page assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md). +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md). ## Using the MySQL connector @@ -152,6 +152,7 @@ A complete sample app that uses Entity Framework Core with MySQL is provided at ## Cloud Foundry This Connector supports the following service brokers: + - [VMware Tanzu for MySQL on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-for-mysql-on-cloud-foundry/3-3/mysql-for-tpcf/about_mysql_vms.html) - [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) - [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) @@ -172,6 +173,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index 88cb3f7d..54b9baff 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -7,7 +7,7 @@ It supports the following .NET drivers: The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). -## Usage +## Using the PostgreSQL connector To use this connector: @@ -165,6 +165,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index 1b2dbfc2..8c0a905d 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -5,7 +5,7 @@ It supports the following .NET drivers: - [RabbitMQ.Client](https://www.nuget.org/packages/RabbitMQ.Client), which provides an `IConnection`. -The remainder of this page assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. ## Using the RabbitMQ connector @@ -107,6 +107,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index 1f2e4394..331c20ca 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -7,12 +7,12 @@ This connector simplifies accessing [Redis](https://redis.io/) databases. It supports the following .NET drivers: -- [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis), which provides an `IConnectionMultiplexer`. -- [Microsoft.Extensions.Caching.StackExchangeRedis](https://www.nuget.org/packages/Microsoft.Extensions.Caching.StackExchangeRedis), which provides an `IDistributedCache`. +- [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis), which provides an `IConnectionMultiplexer` +- [Microsoft.Extensions.Caching.StackExchangeRedis](https://www.nuget.org/packages/Microsoft.Extensions.Caching.StackExchangeRedis), which provides an `IDistributedCache` -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. -## Usage +## Using the Redis Connector To use this connector: @@ -30,9 +30,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for Redis are documented [here](https://stackexchange.github.io/StackExchange.Redis/Configuration.html). +The available connection string parameters for Redis are described in [StackExchange.Redis](https://stackexchange.github.io/StackExchange.Redis/Configuration.html). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container used earlier: ```json { @@ -50,7 +50,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.Redis; @@ -86,7 +86,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IConnectionMultiplexer` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. +For a complete sample app that uses `IConnectionMultiplexer`, see https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. ### Use IDistributedCache @@ -114,14 +114,16 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IDistributedCache` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. +For a complete sample app that uses `IDistributedCache`, see https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. ## Cloud Foundry This Connector supports the following service brokers: -- [Redis for VMware Tanzu Application Service](https://docs.vmware.com/en/Redis-for-VMware-Tanzu-Application-Service/3.1/redis-tanzu-application-service/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for GCP](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-GCP/1.2/csb-gcp/GUID-index.html) + +- [Redis for VMware Tanzu Application Service](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/redis-for-tanzu-application-service/3-5/redis-for-tas/index.html) +- [Tanzu for Valkey on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-for-valkey-on-cloud-foundry/4-0/valkey-on-cf/index.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) +- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: @@ -139,6 +141,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/toc.yml b/api/v4/toc.yml index 18cbb283..55373f95 100644 --- a/api/v4/toc.yml +++ b/api/v4/toc.yml @@ -124,7 +124,7 @@ - topicHref: connectors/cosmosdb.md name: CosmosDB - topicHref: connectors/redis.md - name: Redis + name: Redis/Valkey - name: Service Discovery topicHref: discovery/ items: From 0e66efa5e207c7a56eb6ab4c133d8a216f81e728 Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Thu, 6 Mar 2025 09:27:26 -0800 Subject: [PATCH 18/43] full edit Service Discovery topics --- api/v4/discovery/configuration-based.md | 19 +- api/v4/discovery/hashicorp-consul.md | 159 +++++++------- api/v4/discovery/index.md | 16 +- .../discovery/initialize-discovery-client.md | 22 +- api/v4/discovery/netflix-eureka.md | 201 +++++++++--------- 5 files changed, 211 insertions(+), 206 deletions(-) diff --git a/api/v4/discovery/configuration-based.md b/api/v4/discovery/configuration-based.md index bcad67fd..c59ba387 100644 --- a/api/v4/discovery/configuration-based.md +++ b/api/v4/discovery/configuration-based.md @@ -1,19 +1,19 @@ # Configuration-based discovery client -The simplest form of service discovery is by storing the list of app instances in .NET configuration. +The simplest form of service discovery is implemented by storing the list of app instances in the .NET configuration. ## Configuration settings An app instance in configuration contains the following keys: | Key | Description | -| --- | --- | --- | -| `ServiceId` | The app friendly name. | -| `Host` | The hostname or IP address of the service instance. | -| `Port` | The port number the service instance is listening on. | -| `IsSecure` | Whether to use HTTP or HTTPS to access the service instance. | +| --- | ----------- | +| `ServiceId` | The app friendly name | +| `Host` | The hostname or IP address of the service instance | +| `Port` | The port number the service instance is listening on | +| `IsSecure` | Whether to use HTTP or HTTPS to access the service instance | -For example, the `appsettings.json` file below adds one instance of "billingService" and two instances of "shippingService". +For example, the `appsettings.json` file shown here adds one instance of `billingService` and two instances of `shippingService`. ```json { @@ -42,8 +42,9 @@ For example, the `appsettings.json` file below adds one instance of "billingServ } ``` -Using the above configuration, sending an HTTP request to `http://shippingService/api?id=123` with Steeltoe service discovery -activated would send the request to either: +Using the preceding configuration, sending an HTTP request to `http://shippingService/api?id=123` with Steeltoe service discovery +activated sends the request to either: + - `https://one.internal.shipping.company.com:888/api?id=123` - `https://two.internal.shipping.company.com:999/api?id=123` diff --git a/api/v4/discovery/hashicorp-consul.md b/api/v4/discovery/hashicorp-consul.md index a1e021f6..73ae9382 100644 --- a/api/v4/discovery/hashicorp-consul.md +++ b/api/v4/discovery/hashicorp-consul.md @@ -1,15 +1,15 @@ # HashiCorp Consul discovery client -The Steeltoe Consul discovery client lets an application register/unregister itself with a Consul server +The Steeltoe Consul discovery client allows an application to register and unregister itself with a Consul server and provides querying for service instances registered by other applications. -Once activated, the client registers the currently running app with Consul and starts a background thread that +After it is activated, the client registers the currently running app with Consul and starts a background thread that periodically sends a TTL heartbeat to the Consul server (this is optional). -The client fetches no service registrations until asked for, and doesn't cache them. +The client doesn't fetch service registrations until they are asked for, and it doesn't cache them. -## Usage +## Using HashiCorp Consul discovery client -To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Consul` and initialize it from your `Program.cs`: +To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Consul` and initialize it from `Program.cs`. ```csharp var builder = WebApplication.CreateBuilder(args); @@ -22,85 +22,88 @@ var app = builder.Build(); ## Configuration settings -To get the Steeltoe discovery client to properly communicate with the Consul server, you need to provide -a few configuration settings. There are several sections you may need to configure. +To get the Steeltoe discovery client to properly communicate with the Consul server, there are various settings and sections to configure. What you provide depends on whether you want your application to register the running app and/or whether it also needs to query for other apps. -The first section pertains to configuring the information needed to connect to the Consul server. -All of these settings should start with `Consul:`. +The first section is for configuring the information needed to connect to the Consul server. +All of these settings must start with `Consul:`. + +| Key | Description | Default | +| ------ | ----------- | ------- | +| `Host` | Hostname or IP address of the Consul server | `localhost` | +| `Port` | Port number the Consul server is listening on | `8500` | +| `Scheme` | Scheme to connect with the Consul server (`http` or `https`) | `http` | +| `Datacenter` | The datacenter name passed in each request to the server | | +| `Token` | Authentication token passed in each request to the server | | +| `WaitTime` | The maximum duration for a blocking request | | +| `Username` | Username for HTTP authentication | | +| `Password` | Password for HTTP authentication | | +| `Discovery:Enabled` | Whether to enable the Consul client | `true` | + +The second section (optional) pertains to registering the running app. +All of these settings must start with `Consul:Discovery:`. + +| Key | Description | Default | +| ---------- | ----------- | ------- | +| `Register` | Whether to register the running app as a service instance | `true` | +| `FailFast` | Throw an exception (instead of logging an error) if registration fails | `true` | +| `Retry:Enabled` | Whether to try again when registering the running app fails | `false` | +| `Retry:MaxAttempts` | Maximum number of registration attempts (if retries are enabled) | `6` | +| `Retry:InitialInterval` | The time to wait (in milliseconds) after the first registration failure | `1000` | +| `Retry:Multiplier` | The factor to use when incrementing the next interval | `1.1` | +| `Retry:MaxInterval` | Upper bound (in milliseconds) for intervals | `2000` | +| `Deregister` | Whether to de-register the running app on shutdown | `true` | +| `ServiceName` | Friendly name with which to register the running app | computed | +| `Scheme` | Scheme with which to register the running app (`http` or `https`) | `http` | +| `HostName` | Hostname with which to register the running app (if `PreferIPAddress` is `false`) | computed | +| `IPAddress` | IP address with which to register the running app (if `PreferIPAddress` is `true`) | computed | +| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress` | `false` | +| `PreferIPAddress` | Register the running app with IP address instead of hostname | `false` | +| `Port` | Port number with which to register the running app | | +| `UseAspNetCoreUrls` | Register with the port number ASP.NET Core is listening on | `true` | +| `InstanceId` | The unique ID under which to register the running app | computed | +| `Tags` | Array of tags used when registering the running app | | +| `Meta` | Metadata key/value pairs used when registering the running app | see [Configuring metadata](#configuring-metadata)| +| `InstanceGroup` | Metadata `group` value to use when registering the running app | | +| `InstanceZone` | Metadata zone value to use when registering the running app | | +| `DefaultZoneMetadataName` | Metadata key name for `InstanceZone` | `zone` | +| `RegisterHealthCheck` | Whether to enable periodic health checking for the running app | `true` | +| `HealthCheckCriticalTimeout` | Duration after which Consul deregisters the running app when in state `critical` [^1] | `30m` | +| `Heartbeat:Enabled` | Whether the running app periodically sends TTL (time-to-live) heartbeats [^1] | `true` | +| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy; used with `Heartbeat:TtlUnit` | every `30` seconds | +| `Heartbeat:TtlUnit` | Unit for `TtlValue` (`ms`, `s`, `m` or `h`) | `s` (seconds) | +| `Heartbeat:IntervalRatio` | Rate at which the running app sends TTL heartbeats, relative to `TtlValue` with `TtlUnit` | `0.66` | +| `HealthCheckPath` | Relative URL to the health endpoint of the running app [^2] | `/actuator/health` | +| `HealthCheckUrl` | Absolute URL to the health endpoint of the running app (overrides `HealthCheckPath`) [^2] | | +| `HealthCheckTlsSkipVerify` | Whether Consul should skip TLS verification for HTTP health checks [^2] | `false` | +| `HealthCheckInterval` | How often Consul should perform HTTP health checks [^2] | `10s` | +| `HealthCheckTimeout` | The timeout Consul should use for HTTP health checks [^2] | `10s` | + +[^1]: This setting only affects operation when `RegisterHealthCheck` is `true` + +[^2]: This setting only affects operation when `RegisterHealthCheck` is `true` and `Heartbeat:Enabled` is `false` + +This section pertains to querying for app instances. +All of these settings must start with `Consul:Discovery:`. | Key | Description | Default | -| --- | --- | --- | -| `Host` | Hostname or IP address of the Consul server. | `localhost` | -| `Port` | Port number the Consul server is listening on. | `8500` | -| `Scheme` | Scheme to connect with the Consul server (`http` or `https`). | `http` | -| `Datacenter` | The datacenter name passed in each request to the server. | | -| `Token` | Authentication token passed in each request to the server. | | -| `WaitTime` | The maximum duration for a blocking request. | | -| `Username` | Username for HTTP authentication. | | -| `Password` | Password for HTTP authentication. | | -| `Discovery:Enabled` | Whether to enable the Consul client. | `true` | - -The second section you may need to specify pertains to registering the running app. -All of these settings should start with `Consul:Discovery:`. +| --- | ----------- | ------- | +| `DefaultQueryTag` | The tag to filter on when querying for service instances | | +| `QueryPassing` | Filter on health status passing when querying for service instances | `true` | -| Key | Description | Default | -| --- | --- | --- | -| `Register` | Whether to register the running app as a service instance. | `true` | -| `FailFast` | Throw an exception (instead of logging an error) if registration fails. | `true` | -| `Retry:Enabled` | Whether to try again when registering the running app fails. | `false` | -| `Retry:MaxAttempts` | Maximum number of registration attempts (if retries are enabled). | `6` | -| `Retry:InitialInterval` | The time to wait (in milliseconds) after the first registration failure. | `1000` | -| `Retry:Multiplier` | The factor to increment the next interval with. | `1.1` | -| `Retry:MaxInterval` | Upper bound (in milliseconds) for intervals. | `2000` | -| `Deregister` | Whether to de-register the running app on shutdown. | `true` | -| `ServiceName` | Friendly name to register the running app with. | computed | -| `Scheme` | Scheme to register the running app with (`http` or `https`). | `http` | -| `HostName` | Hostname to register the running app with (if `PreferIPAddress` is `false`). | computed | -| `IPAddress` | IP address to register the running app with (if `PreferIPAddress` is `true`). | computed | -| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress`. | `false` | -| `PreferIPAddress` | Register the running app with IP address instead of hostname. | `false` | -| `Port` | Port number to register the running app with. | | -| `UseAspNetCoreUrls` | Register with the port number ASP.NET Core is listening on. | `true` | -| `InstanceId` | The unique ID to register the running app under. | computed | -| `Tags` | Array of tags used when registering the running app. | | -| `Meta` | Metadata key/value pairs used when registering the running app. | see [Configuring metadata](#configuring-metadata)| -| `InstanceGroup` | Metadata `group` value to use when registering the running app. | | -| `InstanceZone` | Metadata zone value to use when registering the running app. | | -| `DefaultZoneMetadataName` | Metadata key name for `InstanceZone`. | `zone` | -| `RegisterHealthCheck` | Whether to enable periodic health checking for the running app. | `true` | -| `HealthCheckCriticalTimeout` | Duration after which Consul deregisters the running app when in state `critical`. [^1] | `30m` | -| `Heartbeat:Enabled` | Whether the running app periodically sends TTL (time-to-live) heartbeats. [^1] | `true` | -| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy. | `30` | -| `Heartbeat:TtlUnit` | Unit for `TtlValue` (`ms`, `s`, `m` or `h`) | `s` | -| `Heartbeat:IntervalRatio` | Rate at which the running app sends TTL heartbeats, relative to `TtlValue` with `TtlUnit`. | `0.66` | -| `HealthCheckPath` | Relative URL to the health endpoint of the running app. [^2] | `/actuator/health` | -| `HealthCheckUrl` | Absolute URL to the health endpoint of the running app (overrides `HealthCheckPath`). [^2] | | -| `HealthCheckTlsSkipVerify` | Whether Consul should skip TLS verification for HTTP health checks. [^2] | `false` | -| `HealthCheckInterval` | How often Consul should perform an HTTP health check. [^2] | `10s` | -| `HealthCheckTimeout` | The timeout Consul should use for an HTTP health check. [^2] | `10s` | - -[^1]: This setting only has effect when `RegisterHealthCheck` is `true` -[^2]: This setting only has effect when `RegisterHealthCheck` is `true` and `Heartbeat:Enabled` is `false` - -The last section pertains to querying for app instances. -All of these settings should start with `Consul:Discovery:`. - -| Key | Description | Default | -| --- | --- | --- | -| `DefaultQueryTag` | The tag to filter on when querying for service instances. | | -| `QueryPassing` | Filter on health status 'passing' when querying for service instances. | `true` | +For more information about these settings, see the Consul documentation: -For a deeper understanding of these settings, see the Consul documentation on -[registering services](https://developer.hashicorp.com/consul/api-docs/agent/service#register-service), -[health setup during registration](https://developer.hashicorp.com/consul/api-docs/agent/check#register-check) and -[filtering service instances](https://developer.hashicorp.com/consul/api-docs/health). +* [Registering services](https://developer.hashicorp.com/consul/api-docs/agent/service#register-service), +* [Health setup during registration](https://developer.hashicorp.com/consul/api-docs/agent/check#register-check) and +* [Filtering service instances](https://developer.hashicorp.com/consul/api-docs/health). ### Configuring metadata Steeltoe sends metadata (string-based key/value pairs) when registering the currently running app. -Additional metadata can be added in configuration, for example: +Additional metadata can be added in configuration. + +For example: ```json { @@ -117,13 +120,13 @@ Additional metadata can be added in configuration, for example: By default, the following metadata is added: -| Key | Value | -| - | - | -| `group` | Value from `Consul:Discovery:InstanceGroup` | -| Value from `Consul:Discovery:DefaultZoneMetadataName` | Value from `Consul:Discovery:InstanceZone` | +| Key | Value | +| ---------| ----- | +| `group` | Value from `Consul:Discovery:InstanceGroup` | +| Value from `Consul:Discovery:DefaultZoneMetadataName` | Value from `Consul:Discovery:InstanceZone` | | `secure` | Value at `Consul:Discovery:Scheme` equals `https` | ## Health Contributor -The `Steeltoe.Discovery.Consul` package includes an `IHealthContributor` that verifies the Consul server is reachable. +The `Steeltoe.Discovery.Consul` package includes an `IHealthContributor` that verifies that the Consul server is reachable. This health contributor is automatically added to the service container. diff --git a/api/v4/discovery/index.md b/api/v4/discovery/index.md index 7c141264..06fa2bb9 100644 --- a/api/v4/discovery/index.md +++ b/api/v4/discovery/index.md @@ -2,21 +2,21 @@ Service Discovery enables the use of friendly names for the microservices your app depends on. These microservices typically register themselves at startup to a discovery server, which acts as a central registry. -Each time your app connects to such a microservice, the friendly name is resolved to the actual scheme/host/port by querying the discovery server. +Each time your app connects to a microservice like this, the friendly name is resolved to the actual scheme/host/port by querying the discovery server. -A discovery server can track multiple instances for a single friendly name, which enables your app to load-balance over them. +A discovery server can track multiple instances for a single friendly name, which enables your app to load-balance across instances. It also tracks whether your microservice instances are still alive, using health checks and/or keep-alives. While service discovery enables changing infrastructure without affecting your app, its real power lies in scalability. Discovery servers can typically be run in a cluster to eliminate the single point of failure. -And because they monitor the liveliness of your microservice instances, you can easily scale them up and down. +And because they monitor the live-ness of your microservice instances, you can easily scale them up and down. Steeltoe facilitates both registration and querying of discovery servers by providing various implementations of `IDiscoveryClient`. To resolve friendly names, Steeltoe provides implementations of `ILoadBalancer`, which rely on `IDiscoveryClient`. -To use service discovery, you need to: +To use service discovery: -- Add the appropriate NuGet package references to your project -- Register the desired discovery client(s) in the dependency container -- Configure the chosen discovery client(s) for registration and/or consumption -- Activate the provided `HttpClient`/`HttpClientFactory` facilities to resolve friendly names +1. Add the appropriate NuGet package references to your project. +1. Register the desired discovery client(s) in the dependency container. +1. Configure the chosen discovery client(s) for registration and/or consumption. +1. Activate the provided `HttpClient`/`HttpClientFactory` facilities to resolve friendly names. diff --git a/api/v4/discovery/initialize-discovery-client.md b/api/v4/discovery/initialize-discovery-client.md index b5bd68b2..b65c9747 100644 --- a/api/v4/discovery/initialize-discovery-client.md +++ b/api/v4/discovery/initialize-discovery-client.md @@ -3,20 +3,20 @@ This section describes how to activate the Steeltoe discovery client(s), which is a prerequisite for resolving friendly names. Your app can use multiple clients, but is limited to a single instance per server type. -Fundamentally, several things need to happen: +Fundamentally, you have to follow these steps: -1. Add NuGet package references to your project -1. Register the desired discovery client(s) in the dependency container -1. Configure the discovery client(s) -1. Optional: enable debug logging +1. Add NuGet package references to your project. +1. Register the desired discovery client(s) in the dependency container. +1. Configure the discovery client(s). +1. Optional: enable debug logging. ## Add NuGet packages -To get started with Steeltoe Discovery, add a reference to the package(s) containing the discovery technology you may wish to use. +To get started with Steeltoe Discovery, add a reference to the package(s) containing the discovery technology you might want to use. Each package also includes all the relevant dependencies. | Package | Description | -| --- | --- | +| ------- | ----------- | | `Steeltoe.Discovery.Configuration` | Query app instances stored in .NET configuration | | `Steeltoe.Discovery.Consul` | Use [HashiCorp Consul](https://www.consul.io/) server | | `Steeltoe.Discovery.Eureka` | Use [Spring Cloud Eureka](https://projects.spring.io/spring-cloud/docs/1.0.3/spring-cloud.html#spring-cloud-eureka-server) server | @@ -24,7 +24,7 @@ Each package also includes all the relevant dependencies. ## ServiceCollection extension methods After installing the NuGet package(s), the next step is to add the Steeltoe discovery client(s) to the service container. -Update your `Program.cs` as shown below: +Update your `Program.cs` as shown here: ```csharp var builder = WebApplication.CreateBuilder(args); @@ -39,17 +39,17 @@ var app = builder.Build(); > [!NOTE] > Alternatively, you can use `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration), which uses reflection to determine -> which discovery assemblies are loaded, adding the appropriate clients automatically. +> which discovery assemblies are loaded, and adding the appropriate clients automatically. ## Client configuration Discovery clients need to be explicitly configured to fetch application instances and/or register your app with the discovery server. -See the sub-page for the discovery technology of choice on how to set it up. +See the sub-page for the discovery technology of choice for instructions about how to set it up. ## Enable debug logging Sometimes, you may want to turn on debug logging for service discovery. -To do so, you can modify the `appsettings.json` file and turn on debug logging for the Steeltoe components. +To turn on debug logging, modify the `appsettings.json` file and turn on debug logging for the Steeltoe components. The following example shows a typical `appsettings.json` file: diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 092a0305..e7b9d0d3 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -1,14 +1,14 @@ # Netflix Eureka discovery client -The Steeltoe Eureka discovery client lets an application register/unregister itself with a Eureka server +The Steeltoe Eureka discovery client allows an application to register and unregister itself with a Eureka server and provides querying for service instances registered by other applications. -Once activated, the client begins to operate in the background, both registering and renewing service registrations, +After it is activated, the client begins to operate in the background, both registering and renewing service registrations, sending periodic heartbeats to the Eureka server, and also periodically fetching the service registry from the server. -## Usage +## Using Netflix Eureka discovery client -To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Eureka` and initialize it from your `Program.cs`: +To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Eureka` and initialize it from `Program.cs`. ```csharp var builder = WebApplication.CreateBuilder(args); @@ -21,8 +21,7 @@ var app = builder.Build(); ## Configuration settings -To get the Steeltoe discovery client to properly communicate with the Eureka server, you need to provide -a few configuration settings. There are several sections you may need to configure. +To get the Steeltoe discovery client to properly communicate with the Eureka server, there are several sections you may need to configure. What you provide depends on whether you want your application to register the running app and/or whether it needs to query for other apps. @@ -32,99 +31,98 @@ In most cases, unless you are confident that you understand the effects of chang we recommend that you use the defaults. > [!NOTE] -> Since Steeltoe v4, most of these settings can be changed at runtime, which updates the Eureka server accordingly. +> Since Steeltoe v4, most of these settings can be changed at runtime, and the Eureka server is updated accordingly. ### General -The following table describes the configuration settings that control the overall behavior of the client. -All of these settings should start with `Eureka:Client:`. - -| Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether to enable the Eureka client. | `true` | -| `ServiceUrl` | Comma-delimited list of Eureka server endpoints. | `http://localhost:8761/eureka/` | -| `AccessTokenUri` | URL to obtain OAuth2 access token from, before connecting to the Eureka server. | | -| `ClientId` | Client ID for obtaining an access token. | | -| `ClientSecret` | Secret for obtaining an access token. | | -| `Validate_Certificates` | Whether the client validates server certificates. | `true` | -| `EurekaServer:ShouldGZipContent` | Whether to auto-decompress responses from the Eureka server. | `true` | -| `EurekaServer:RetryCount` | Number of times to retry Eureka server requests. | `2` | -| `EurekaServer:ConnectTimeoutSeconds` | How long to wait (in seconds) before a connection to the Eureka server times out. | `5` | -| `EurekaServer:ProxyHost` | Proxy hostname used in contacting the Eureka server. | | -| `EurekaServer:ProxyPort` | Proxy port number used in contacting the Eureka server. | | -| `EurekaServer:ProxyUserName` | Proxy username used in contacting the Eureka server. | | -| `EurekaServer:ProxyPassword` | Proxy password used in contacting the Eureka server. | | -| `Health:Enabled` | Whether to activate an `IHealthContributor` that verifies connectivity to the Eureka server. | `true` | +The following table describes the configuration settings that control the behavior of the client. +All of these settings must start with `Eureka:Client:`. + +| Key | Description | Default | +| --------- | ----------- | ------- | +| `Enabled` | Whether to enable the Eureka client | `true` | +| `ServiceUrl` | Comma-delimited list of Eureka server endpoints | `http://localhost:8761/eureka/` | +| `AccessTokenUri` | URL at which to obtain OAuth2 access token, before connecting to the Eureka server | | +| `ClientId` | Client ID for obtaining an access token | | +| `ClientSecret` | Secret for obtaining an access token | | +| `Validate_Certificates` | Whether the client validates server certificates | `true` | +| `EurekaServer:ShouldGZipContent` | Whether to auto-decompress responses from the Eureka server | `true` | +| `EurekaServer:RetryCount` | Number of times to retry Eureka server requests | `2` | +| `EurekaServer:ConnectTimeoutSeconds` | How long to wait (in seconds) before a connection to the Eureka server times out | `5` | +| `EurekaServer:ProxyHost` | Proxy hostname used in contacting the Eureka server | | +| `EurekaServer:ProxyPort` | Proxy port number used in contacting the Eureka server | | +| `EurekaServer:ProxyUserName` | Proxy username used in contacting the Eureka server | | +| `EurekaServer:ProxyPassword` | Proxy password used in contacting the Eureka server | | +| `Health:Enabled` | Whether to activate an `IHealthContributor` that verifies connectivity to the Eureka server | `true` | ### Registration The configuration settings below pertain to registering the currently running app as a service instance in Eureka. -All of these settings should start with `Eureka:Client:`. +All of these settings must start with `Eureka:Client:`. | Key | Description | Default | -| --- | --- | --- | -| `ShouldRegisterWithEureka` | Whether to register the running app as a service instance. | `true` | -| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, in order to determine the status of the running app to report back to Eureka (see section below). | `true` | +| --- | ----------- | ------- | +| `ShouldRegisterWithEureka` | Whether to register the running app as a service instance | `true` | +| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see following section) | `true` | Additionally, the table below lists the configuration settings that control *how* to register the instance. -All of these settings should start with `Eureka:Instance:`. +All of these settings must start with `Eureka:Instance:`. | Key | Description | Default | -| --- | --- | --- | -| `InstanceId` | Unique ID (within the scope of the app name) of the instance to be registered with Eureka. | computed | -| `AppName` | Name of the application to be registered with Eureka. | computed | -| `AppGroup` | Name of the application group to be registered with Eureka. | | -| `MetadataMap` | Name/value pairs associated with the instance. | computed | -| `HostName` | Hostname on which the instance is registered. | computed | -| `IPAddress` | IP address on which the instance is registered. | computed | -| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress`. | `false` | -| `PreferIPAddress` | Whether to register with `IPAddress` instead of `HostName`. | `false` | -| `VipAddress` | Comma-delimited list of VIP addresses for the instance. | computed | -| `SecureVipAddress` | Comma-delimited list of secure VIP addresses for the instance. | computed | -| `Port` | Non-secure port number on which the instance should receive traffic. | computed | -| `NonSecurePortEnabled` | Whether the non-secure port should be enabled. [^1] | computed | -| `SecurePort` | Secure port on which the instance should receive traffic. | computed | -| `SecurePortEnabled` | Whether the secure port should be enabled. [^1] | computed | -| `RegistrationMethod` | How to register on Cloud Foundry. Can be `route`, `direct`, or `hostname`. [^2] | | -| `InstanceEnabledOnInit` | Whether the instance should take traffic as soon as it is registered. [^3] | `true` | -| `LeaseRenewalIntervalInSeconds` | How often (in seconds) the client sends heartbeats to Eureka to indicate that it is still alive. | `30` | -| `LeaseExpirationDurationInSeconds` | Time (in seconds) that the Eureka server waits since it received the last heartbeat before it marks the instance as down. | `90` | -| `StatusPageUrlPath` | Relative path to the status page for the instance. [^4] | `/info` | -| `StatusPageUrl` | Absolute URL to the status page for the instance (overrides `StatusPageUrlPath`). | computed | -| `HomePageUrlPath` | Relative path to the home page URL for the instance. | `/` | -| `HomePageUrl` | Absolute URL to the home page for the instance (overrides `HomePageUrlPath`). | computed | -| `HealthCheckUrlPath` | Relative path to the health check endpoint of the instance. [^4] | `/health` | -| `HealthCheckUrl` | Absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`). | computed | -| `SecureHealthCheckUrl` | Secure absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`). | computed | -| `AsgName` | AWS auto-scaling group name associated with the instance. | | -| `DataCenterInfo` | Data center the instance is deployed to (`Netflix`, `Amazon` or `MyOwn`). | MyOwn | - -[^1]: When both non-secure and secure ports are enabled, the secure port is preferred during service discovery. -[^2]: Specify `direct` to use container-to-container networking on Cloud Foundry. Specify `hostname` to force using `HostName`. -[^3]: When set to `false`, call `EurekaApplicationInfoManager.UpdateInstance()` after initialization to mark the instance as up. -[^4]: Add a NuGet package reference to `Steeltoe.Management.Endpoint` to use its `health` and `info` actuator paths. - -The values for `Port` and `SecurePort`, and whether they are enabled, are automatically determined from the ASP.NET address bindings. [^1] -See [8 ways to set the URLs for an ASP.NET Core app](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/) +| --- | ----------- | ------- | +| `InstanceId` | Unique ID (within the scope of the app name) of the instance to be registered with Eureka | computed | +| `AppName` | Name of the application to be registered with Eureka | computed | +| `AppGroup` | Name of the application group to be registered with Eureka | | +| `MetadataMap` | Name/value pairs associated with the instance | computed | +| `HostName` | Hostname on which the instance is registered | computed | +| `IPAddress` | IP address on which the instance is registered | computed | +| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress` | `false` | +| `PreferIPAddress` | Whether to register with `IPAddress` instead of `HostName` | `false` | +| `VipAddress` | Comma-delimited list of VIP addresses for the instance | computed | +| `SecureVipAddress` | Comma-delimited list of secure VIP addresses for the instance | computed | +| `Port` | Non-secure port number on which the instance should receive traffic | computed | +| `NonSecurePortEnabled` | Whether the non-secure port should be enabled [^1] | computed | +| `SecurePort` | Secure port on which the instance should receive traffic | computed | +| `SecurePortEnabled` | Whether the secure port should be enabled [^1] | computed | +| `RegistrationMethod` | How to register on Cloud Foundry. Can be `route`, `direct`, or `hostname` [^2] | | +| `InstanceEnabledOnInit` | Whether the instance should take traffic as soon as it is registered [^3] | `true` | +| `LeaseRenewalIntervalInSeconds` | How often (in seconds) the client sends heartbeats to Eureka to indicate that it is still alive | `30` | +| `LeaseExpirationDurationInSeconds` | Time (in seconds) that the Eureka server waits after receiving the last heartbeat before it marks the instance as down | `90` | +| `StatusPageUrlPath` | Relative path to the status page for the instance [^4] | `/info` | +| `StatusPageUrl` | Absolute URL to the status page for the instance (overrides `StatusPageUrlPath`) | computed | +| `HomePageUrlPath` | Relative path to the home page URL for the instance | `/` | +| `HomePageUrl` | Absolute URL to the home page for the instance (overrides `HomePageUrlPath`) | computed | +| `HealthCheckUrlPath` | Relative path to the health check endpoint of the instance [^4] | `/health` | +| `HealthCheckUrl` | Absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`) | computed | +| `SecureHealthCheckUrl` | Secure absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`) | computed | +| `AsgName` | AWS auto-scaling group name associated with the instance | | +| `DataCenterInfo` | Data center the instance is deployed to (`Netflix`, `Amazon`, or `MyOwn`) | `MyOwn` | + +[^1]: When both non-secure and secure ports are enabled, the secure port is preferred during service discovery. The values for `Port` and `SecurePort`, and whether they are enabled, are automatically determined from the ASP.NET address bindings. See [8 ways to set the URLs for an ASP.NET Core app](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/) for how to influence them using environment variables. - It is also possible to use dynamic port bindings (by setting the port number to `0` in ASP.NET). In that case, Steeltoe adds a random number (outside the valid port range) to the `InstanceId` to make it unique. -Once the app has fully started, the assigned port numbers are updated in Eureka, but the `InstanceId` does not change. +After the app has fully started, the assigned port numbers are updated in Eureka, but the `InstanceId` does not change. + +[^2]: Specify `direct` to use container-to-container networking on Cloud Foundry. Specify `hostname` to force using `HostName`. + +[^3]: When set to `false`, call `EurekaApplicationInfoManager.UpdateInstance()` after initialization to mark the instance as up. + +[^4]: Add a NuGet package reference to `Steeltoe.Management.Endpoint` to use its `health` and `info` actuator paths. ### Querying -The configuration settings that pertain to querying the Eureka registry for apps (used by the load balancers during service discovery) are listed below. -All of these settings should start with `Eureka:Client:`. +The configuration settings that pertain to querying the Eureka registry for apps (used by the load balancers during service discovery) are shown in the table. +All of these settings must start with `Eureka:Client:`. | Key | Description | Default | -| --- | --- | --- | -| `ShouldFetchRegistry` | Whether to periodically fetch registry information from the Eureka server. | `true` | -| `RegistryFetchIntervalSeconds` | How often (in seconds) to fetch registry information from the Eureka server. | `30` | -| `ShouldFilterOnlyUpInstances` | Whether to include only instances with UP status after fetching the list of applications. | `true` | -| `ShouldDisableDelta` | Whether to fetch the full registry each time or fetch only deltas. | `false` | -| `RegistryRefreshSingleVipAddress` | Whether to only fetch registry information for the specified VIP address. | `false` | -| `Health:MonitoredApps` | Comma-delimited list of applications in Eureka this app depends on (see section below). | | +| --- | ----------- | ------- | +| `ShouldFetchRegistry` | Whether to periodically fetch registry information from the Eureka server | `true` | +| `RegistryFetchIntervalSeconds` | How often (in seconds) to fetch registry information from the Eureka server | every `30` seconds | +| `ShouldFilterOnlyUpInstances` | Whether to include only instances with UP status after fetching the list of applications | `true` | +| `ShouldDisableDelta` | Whether to fetch the full registry each time (`true`) or fetch only deltas (`false`) | `false` | +| `RegistryRefreshSingleVipAddress` | Whether to fetch registry information only for the specified VIP address | `false` | +| `Health:MonitoredApps` | Comma-delimited list of applications in Eureka that this app depends on (see following section) | | ## Configuring health contributors @@ -136,7 +134,7 @@ compute the health of the connection. This contributor is automatically activated, but can be turned off by setting `Eureka:Client:Health:Enabled` to `false`. The second contributor that you can enable is the `EurekaApplicationsHealthContributor`. -By default, this contributor is not enabled, so you must add it to the service container yourself: +By default, this contributor is not enabled, so you must add it to the service container explicitly: ```csharp builder.Services.AddSingleton(); @@ -144,10 +142,11 @@ builder.Services.AddSingleton(); appManager.UpdateInstance(newStatus: null, newOverriddenStatus: null, @@ -195,10 +192,10 @@ appManager.UpdateInstance(newStatus: null, newOverriddenStatus: null, }); ``` -> [!WARN] -> Once metadata has been updated from code, later metadata changes in configuration are ignored. - -In general, additional metadata does not change the behavior of applications, unless they are made aware of +> [!CAUTION] +> After metadata has been updated from code, later metadata changes in configuration are ignored. +> +> In general, additional metadata does not change the behavior of applications, unless the apps are made aware of the meaning of the metadata. ## Configuring mutual TLS @@ -213,7 +210,9 @@ add the path to your certificate file(s) to `appsettings.json`. For example: } } ``` + or: + ```json "Certificates": { "Eureka": { @@ -227,14 +226,16 @@ or: > To support certificate rotation, the configuration keys and the files on disk are automatically monitored for changes. > [!NOTE] -> A single certificate can be shared with both Config Server and Eureka, by using the key `Certificates` instead of `Certificates:Eureka`. +> A single certificate can be shared with both Config Server and Eureka by using the key `Certificates`, instead of `Certificates:Eureka`. ### Using custom HTTP headers -The communication with Eureka server uses the `HttpClientFactory` [pattern](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests), -which makes it aware of DNS changes over time and enables to tweak the handler pipeline. +The communication with Eureka server uses the `HttpClientFactory` pattern, +which makes it aware of DNS changes over time and enables it to tweak the handler pipeline. For more information, +see the [Microsoft documentation](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests). + +To send a custom HTTP header with every request, create a `DelegatingHandler` and add it to the pipeline. -To send a custom HTTP header with every request, create a `DelegatingHandler` and add it to the pipeline: ```csharp builder.Services.AddEurekaDiscoveryClient(); builder.Services.AddTransient(); @@ -258,4 +259,4 @@ public sealed class ExtraRequestHeaderDelegatingHandler : DelegatingHandler ``` > [!NOTE] -> To send an extra header to the OAuth2 endpoint, replace `"Eureka"` with `"AccessTokenForEureka"` in the example above. +> To send an extra header to the OAuth2 endpoint, replace `"Eureka"` with `"AccessTokenForEureka"` in the preceding example. From d1e55e3491c0a6dbb3f8f512d5f4b901e0656a9f Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Thu, 6 Mar 2025 12:04:47 -0800 Subject: [PATCH 19/43] full edit Initializr topics --- api/v4/initializr/index.md | 17 +++++---- api/v4/initializr/initializr-service.md | 21 +++++------ api/v4/initializr/initializr-web.md | 48 ++++++++++++------------- 3 files changed, 45 insertions(+), 41 deletions(-) diff --git a/api/v4/initializr/index.md b/api/v4/initializr/index.md index 2f19084f..01425fa0 100644 --- a/api/v4/initializr/index.md +++ b/api/v4/initializr/index.md @@ -2,12 +2,15 @@ An Initializr jumpstarts .NET development by generating projects based on project metadata. Metadata may include, among other properties, a project name, a namespace, and a list of dependencies. -At the core of an Initializr is the _[InitializrService](https://github.com/SteeltoeOSS/InitializrService)_. -_InitializrService_ provides several REST/HTTP endpoints, which includes an endpoint to generate projects, and an endpoint to provide smart clients the metadata needed to construct user interfaces. +At the core of an Initializr is the [Steeltoe InitializrService](https://github.com/SteeltoeOSS/InitializrService). +InitializrService provides several REST/HTTP endpoints, and includes: -It is possible to have a fully functioning Initializr deployment by simply deploying the _InitializrService_. -A more user-friendly deployment may include a user interface, such as a web frontend or an IDE plugin. -A deployment may also leverage a _[Spring Cloud Config Server](https://cloud.spring.io/spring-cloud-config/multi/multi__spring_cloud_config_server.html)_ to access a configuration store. -As an example, the [Steeltoe Initializr deployment](https://start.steeltoe.io) includes _[InitializrWeb](https://github.com/SteeltoeOSS/InitializrWeb)_ for a friendly user experience and a _Spring Cloud Config Server_ using a GitHub-maintained configuration. +* an endpoint to generate projects, and +* an endpoint to provide smart clients the metadata needed to construct user interfaces -_InitializrWeb_ is the reference UI for the Steeltoe Initializr and is an example of a smart client. It uses project metadata from the _InitializrService_ to populate its web controls with, for example, supported .NET target frameworks and Steeltoe versions. +It is possible to have a fully functioning Initializr deployment by simply deploying the InitializrService. +A more user-friendly deployment might include a user interface, such as a web frontend or an IDE plug-in. +A deployment may also use a [Spring Cloud Config Server](https://cloud.spring.io/spring-cloud-config/multi/multi__spring_cloud_config_server.html) to access a configuration store. +As an example, the [Steeltoe Initializr deployment](https://start.steeltoe.io) includes [InitializrWeb](https://github.com/SteeltoeOSS/InitializrWeb) for a friendly user experience and a Spring Cloud Config Server using a GitHub-maintained configuration. + +InitializrWeb is the reference UI for the Steeltoe Initializr and is an example of a smart client. It uses project metadata from the InitializrService to populate its web controls with, for example, supported .NET target frameworks and Steeltoe versions. diff --git a/api/v4/initializr/initializr-service.md b/api/v4/initializr/initializr-service.md index 786233d3..72216b13 100644 --- a/api/v4/initializr/initializr-service.md +++ b/api/v4/initializr/initializr-service.md @@ -1,6 +1,6 @@ # InitializrService -The _InitializrService_ provides 4 REST/HTTP endpoints: +The InitializrService provides four REST/HTTP endpoints: * `api/` * `api/about` @@ -10,7 +10,7 @@ The _InitializrService_ provides 4 REST/HTTP endpoints: ## `api/` `api/` accepts `GET` requests and returns a help document. -The document includes available parameters (and their defaults) and dependencies, as well as CLI samples. +The document includes available parameters (and their defaults) and dependencies, plus CLI samples. ```bash # sample: view help doc @@ -30,7 +30,7 @@ The URI templates take a set of parameters to customize the result of a request. ## `api/about` -`api/about` accepts `GET` requests and returns the _InitialzrService_ "About" information. +`api/about` accepts `GET` requests and returns the InitializrService "About" information. ```bash # sample: view "About" document @@ -46,11 +46,11 @@ $ http -p b https://start.steeltoe.io/api/about ## `api/config` -`api/config` accepts `GET` requests and returns _InitializrService_ configuration. -The returned document includes *all* configuration which can include superfluous details. -Sub-endpoints are available allowing more targeted responses. +`api/config` accepts `GET` requests and returns InitializrService configuration. +The returned document includes *all* configuration, which can include superfluous details. +Sub-endpoints are available, allowing more targeted responses. -`api/config/projectMetadata` can be used by smart clients, such as the _InitializrWeb_, to assist in creating user interfaces. +`api/config/projectMetadata` can be used by smart clients, such as the InitializrWeb, to assist in creating user interfaces. The following endpoints can be used by CLI users to browse project configuration options: @@ -105,10 +105,11 @@ $ http https://start.steeltoe.io/api/config/dependencies | jq '.[] .values[] .id `api/project` accepts `GET` and `POST` requests and returns a project as an archive. -Projects are configured by using HTTP parameters, such as `name` for the project name and `steeltoeVersion` for the Steeltoe version. -The parameter `dependencies` is a little different than other parameters in that it is set to a comma-separated list of dependency IDs. +Projects are configured using HTTP parameters, such as `name` for the project name and `steeltoeVersion` for the Steeltoe version. +The parameter `dependencies` is different than other parameters in that it is set to a comma-separated list of dependency IDs. -_Note: to get a list of parameters and dependencies, send a `GET` request to `api/`._ +> [!NOTE] +> To get a list of parameters and dependencies, send a `GET` request to `api/`. ```bash # sample: generate a .NET Core App 3.1 project with actuator endpoints and a Redis backend: diff --git a/api/v4/initializr/initializr-web.md b/api/v4/initializr/initializr-web.md index a847def1..13708d58 100644 --- a/api/v4/initializr/initializr-web.md +++ b/api/v4/initializr/initializr-web.md @@ -1,14 +1,14 @@ # InitializrWeb -_InitializrWeb_ is a web frontend for an Initializr deployment. -It uses _InitializrApi_-provided project metadata to populate its interface for easy perusal and selection by an end user. -After selecting desired project parameters, an end user uses _InitializrWeb_ to submit project generation requests to the _InitializrApi_. +InitializrWeb is a web frontend for an Initializr deployment. +It uses InitializrApi-provided project metadata to populate its interface for easy perusal and selection by an end user. +After selecting desired project parameters, an end user uses InitializrWeb to submit project generation requests to the InitializrApi. ## Overview ![Steeltoe Initializr](./images/default.png) -The interface is made up of 4 areas: +The interface is made up of four areas: * project configuration area * project action area (bottom) @@ -17,45 +17,45 @@ The interface is made up of 4 areas: The remainder of this document focuses on the project configuration and action areas. -## Configuration +## Project configuration -The configuration area exposes 5 project properties to the end user: +The configuration area exposes five project properties to the end user: -* name -* C# namespace -* application name -* description -* Steeltoe version -* .NET target framework -* .NET template -* dependencies +* **Name** +* **Namespace**: C# namespace +* **Application**: application name +* **Description** +* **Steeltoe**: Steeltoe version +* **.NET Framework**: .NET target framework +* **.NET template** +* **Dependencies** -## Actions +## Project actions -The actions area provides 3 project actions to the end user: +The actions area provides three project actions to the end user: -* generate -* explore -* share +* **Generate** +* **Explore** +* **Share** ### Generate -Clicking "Generate" submits the current configuration to the _InitializrApi_ to generate a project archive. -The resultant project archive is a Zip file named based on the project name. +Clicking **Generate** submits the current configuration to the InitializrApi to generate a project archive. +The resultant project archive is a Zip file with a name based on the project name. ![Steeltoe Initializr generate](images/generate.png) ### Explore -Clicking "Explore" submits the current configuration to the _InitializrApi_ to generate a project archive. +Clicking **Explore** submits the current configuration to the InitializrApi to generate a project archive. The resultant project archive is expanded in the UI so that the end user can explore the project. ![Steeltoe Initializr explore](images/explore.png) ### Share -Clicking "Share" displays a URL that represents the current project configuration. +Clicking **Share** displays a URL that represents the current project configuration. It can be shared with other developers or saved in a bookmark. -Note that the URL is specific to _InitializrWeb_ and cannot be used directly with the _InitializrApi_. +Note that the URL is specific to InitializrWeb and cannot be used directly with the InitializrApi. ![Steeltoe Initializr share](images/share.png) From f46516b57fed9c836968a1e8c2557f131dbe918f Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Thu, 6 Mar 2025 17:24:04 -0600 Subject: [PATCH 20/43] fix pipeline, stray spaces and rogue comma --- .github/workflows/build-and-stage.yml | 4 ++-- api/v4/configuration/config-server-provider.md | 2 +- api/v4/discovery/hashicorp-consul.md | 2 +- api/v4/discovery/index.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build-and-stage.yml b/.github/workflows/build-and-stage.yml index 45a6e38e..4cd13c33 100644 --- a/.github/workflows/build-and-stage.yml +++ b/.github/workflows/build-and-stage.yml @@ -135,10 +135,10 @@ jobs: name: Build and push documentation image needs: [ change-detection, build-push-docfx, build-push-metadata ] environment: - name: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || (github.ref_name == 'anita' && 'anita' || vars.STAGING_SLOT_NAME) }} + name: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || vars.STAGING_SLOT_NAME }} url: ${{ steps.deploy-to-webapp.outputs.webapp-url }} env: - SLOT_NAME: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || (github.ref_name == 'anita' && 'anita' || vars.STAGING_SLOT_NAME) }} + SLOT_NAME: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || vars.STAGING_SLOT_NAME }} runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index f91c27a6..c10af9e7 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -188,7 +188,7 @@ Alternatively, you can create a class to hold your configuration data and then u builder.Services.AddOptions().BindConfiguration("example"); ``` -1, Now you can gain access to the data in your `Controller` or `View` through dependency injection. The following example shows how to do this: +1. Now you can gain access to the data in your `Controller` or `View` through dependency injection. The following example shows how to do this: ```csharp using Microsoft.AspNetCore.Mvc; diff --git a/api/v4/discovery/hashicorp-consul.md b/api/v4/discovery/hashicorp-consul.md index 73ae9382..d1373867 100644 --- a/api/v4/discovery/hashicorp-consul.md +++ b/api/v4/discovery/hashicorp-consul.md @@ -1,6 +1,6 @@ # HashiCorp Consul discovery client -The Steeltoe Consul discovery client allows an application to register and unregister itself with a Consul server +The Steeltoe Consul discovery client allows an application to register and unregister itself with a Consul server and provides querying for service instances registered by other applications. After it is activated, the client registers the currently running app with Consul and starts a background thread that diff --git a/api/v4/discovery/index.md b/api/v4/discovery/index.md index 06fa2bb9..a5944cae 100644 --- a/api/v4/discovery/index.md +++ b/api/v4/discovery/index.md @@ -18,5 +18,5 @@ To use service discovery: 1. Add the appropriate NuGet package references to your project. 1. Register the desired discovery client(s) in the dependency container. -1. Configure the chosen discovery client(s) for registration and/or consumption. +1. Configure the chosen discovery client(s) for registration and/or consumption. 1. Activate the provided `HttpClient`/`HttpClientFactory` facilities to resolve friendly names. From af36f17ae7f0faa7124cba82067c6d45406dfb53 Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Thu, 13 Mar 2025 10:19:38 -0500 Subject: [PATCH 21/43] Apply suggestions from code review --- api/v4/configuration/cloud-foundry-provider.md | 6 +++--- api/v4/configuration/spring-boot-provider.md | 4 ++-- api/v4/discovery/configuration-based.md | 2 +- api/v4/security/jwt-bearer.md | 2 +- api/v4/security/sso-open-id.md | 4 ++-- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/api/v4/configuration/cloud-foundry-provider.md b/api/v4/configuration/cloud-foundry-provider.md index b08d8e42..2ab4157a 100644 --- a/api/v4/configuration/cloud-foundry-provider.md +++ b/api/v4/configuration/cloud-foundry-provider.md @@ -13,9 +13,9 @@ You should have a good understanding of how the [.NET Configuration System](http To use the Steeltoe Cloud Foundry provider: 1. Add the appropriate NuGet package reference to your project. -2. Add the provider to the host builder or configuration builder. -3. Configure Cloud Foundry option classes by binding configuration data to them. -4. Inject and use `IConfiguration` or `IOptions<>` to access configuration data. +1. Add the provider to the host builder or configuration builder. +1. Configure Cloud Foundry option classes by binding configuration data to them. +1. Inject and use `IConfiguration` or `IOptions<>` to access configuration data. ### Add NuGet Reference diff --git a/api/v4/configuration/spring-boot-provider.md b/api/v4/configuration/spring-boot-provider.md index e3fc9161..7ab649a2 100644 --- a/api/v4/configuration/spring-boot-provider.md +++ b/api/v4/configuration/spring-boot-provider.md @@ -12,8 +12,8 @@ You should have a good understanding of how the [.NET Configuration System](http To use the Steeltoe Spring Boot provider: 1. Add the appropriate NuGet package reference to your project. -2. Add the provider to the Configuration Builder. -3. Access keys from the `IConfiguration`. +1. Add the provider to the Configuration Builder. +1. Access keys from the `IConfiguration`. ### Add NuGet Reference diff --git a/api/v4/discovery/configuration-based.md b/api/v4/discovery/configuration-based.md index c59ba387..7a59d2ec 100644 --- a/api/v4/discovery/configuration-based.md +++ b/api/v4/discovery/configuration-based.md @@ -1,6 +1,6 @@ # Configuration-based discovery client -The simplest form of service discovery is implemented by storing the list of app instances in the .NET configuration. +The simplest form of service discovery is implemented by storing the list of app instances in .NET configuration. ## Configuration settings diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index 0bbb289c..a6c1bf1c 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -9,7 +9,7 @@ General guidance for use of JWT is beyond the scope of this document. For inform * [JWT IO](https://jwt.io/) * [Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token) -For information about the underlying Microsoft Jwt Bearer Authentication library, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-jwt-bearer-authentication). +For information about the underlying Microsoft JWT Bearer Authentication library, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-jwt-bearer-authentication). ## Using JWT in ASP.NET Core diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index 6839ed77..8be372ca 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -23,9 +23,9 @@ To use the OpenID Connect Library: ### Add NuGet References -To use this package, add references to: +To use this package, add NuGet package references to: -* the NuGet package `Steeltoe.Security.Authentication.OpenIdConnect` +* `Steeltoe.Security.Authentication.OpenIdConnect` * `Steeltoe.Configuration.CloudFoundry` (so that Cloud Foundry service bindings can be read by Steeltoe) ### Configure Settings From 185fce2e9d14c6c2ae9d3eb55ef5913f5d6d7287 Mon Sep 17 00:00:00 2001 From: Anita Flegg Date: Thu, 13 Mar 2025 09:50:52 -0700 Subject: [PATCH 22/43] Update api/v4/management/prometheus.md Co-authored-by: Tim Hess --- api/v4/management/prometheus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index 47e76137..9df2b9a0 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -117,7 +117,7 @@ As an example, the following `prometheus.yml` file configures metric scraping fo ```yml global: - scrape_interval: 15 s # Set the scrape interval to every 15 seconds. The default is every 1 minute. + scrape_interval: 15s # Set the scrape interval to every 15 seconds. The default is every 1 minute. evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute. # scrape_timeout is set to the global default (10s). scrape_configs: From 773305d8e65af594c53c6bb281e58a74c7f79d78 Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Wed, 26 Mar 2025 14:36:10 -0500 Subject: [PATCH 23/43] Apply suggestions from code review Co-authored-by: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> --- api/v4/connectors/cosmosdb.md | 4 ++-- api/v4/connectors/microsoft-sql-server.md | 2 +- api/v4/connectors/mongodb.md | 2 +- api/v4/connectors/mysql.md | 4 ++-- api/v4/connectors/postgresql.md | 6 +++--- api/v4/connectors/redis.md | 4 ++-- api/v4/connectors/usage.md | 2 +- api/v4/discovery/configuration-based.md | 2 +- api/v4/discovery/hashicorp-consul.md | 6 +++--- .../discovery/initialize-discovery-client.md | 4 ++-- api/v4/discovery/netflix-eureka.md | 6 +++--- api/v4/fileshares/usage.md | 2 +- api/v4/initializr/index.md | 2 +- api/v4/logging/dynamic-serilog-logging.md | 2 +- api/v4/management/cloud-foundry.md | 2 +- api/v4/management/health.md | 14 +++++++------- api/v4/management/heapdump.md | 2 +- api/v4/management/info.md | 3 +-- api/v4/management/prometheus.md | 4 ++-- api/v4/management/using-endpoints.md | 2 +- api/v4/security/certificate.md | 8 ++++---- api/v4/security/index.md | 2 +- api/v4/security/jwt-bearer.md | 18 +++++++++--------- api/v4/security/redis-key-storage-provider.md | 8 ++++---- api/v4/security/sso-open-id.md | 8 ++++---- api/v4/toc.yml | 2 +- api/v4/tracing/index.md | 18 +++++++++--------- 27 files changed, 69 insertions(+), 70 deletions(-) diff --git a/api/v4/connectors/cosmosdb.md b/api/v4/connectors/cosmosdb.md index 0fefc984..a869e5f5 100644 --- a/api/v4/connectors/cosmosdb.md +++ b/api/v4/connectors/cosmosdb.md @@ -60,7 +60,7 @@ builder.AddCosmosDb(); ### Use CosmosClient -Follow this procedure: +To retrieve data from CosmosDB in your app, follow the steps below: 1. Define a class that contains container data: @@ -128,7 +128,7 @@ A complete sample app that uses `CosmosClient` is provided at https://github.com This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-10/csb-azure/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: diff --git a/api/v4/connectors/microsoft-sql-server.md b/api/v4/connectors/microsoft-sql-server.md index 49cbe3ac..069fb195 100644 --- a/api/v4/connectors/microsoft-sql-server.md +++ b/api/v4/connectors/microsoft-sql-server.md @@ -88,7 +88,7 @@ public class HomeController : Controller ### Use Entity Framework Core -Follow this procedure: +To retrieve data from SQL Server in your app using Entity Framework Core, use the following steps: 1. Define your `DbContext` class: diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index 6ee3fdae..069830df 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -27,7 +27,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would The available connection string parameters for MongoDB are described in the [MongoDB documentation](https://www.mongodb.com/docs/manual/reference/connection-string/). -The following example `appsettings.json` uses the docker container used earlier: +The following example `appsettings.json` uses the docker container mentioned earlier: ```json { diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index 26fc94ad..3a91e8c8 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -95,7 +95,7 @@ A complete sample app that uses `MySqlConnection` is provided at https://github. ### Use Entity Framework Core -Follow this procedure: +To retrieve data from MySQL in your app using Entity Framework Core, use the following steps: 1. Define your `DbContext` class: @@ -154,7 +154,7 @@ A complete sample app that uses Entity Framework Core with MySQL is provided at This Connector supports the following service brokers: - [VMware Tanzu for MySQL on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-for-mysql-on-cloud-foundry/3-3/mysql-for-tpcf/about_mysql_vms.html) -- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-9/csb-azure/index.html) - [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) You can create and bind an instance to your application using the Cloud Foundry CLI: diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index 54b9baff..889657b5 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -5,7 +5,7 @@ It supports the following .NET drivers: - [Npgsql](https://www.nuget.org/packages/Npgsql), which provides an ADO.NET `DbConnection`. - [Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +The remainder of this topic assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). ## Using the PostgreSQL connector @@ -88,7 +88,7 @@ A complete sample app that uses `NpgsqlConnection` is provided at https://github ### Use Entity Framework Core -Follow these instructions: +To retrieve data from PostgreSQL in your app using Entity Framework Core, use the following steps: 1. Define your `DbContext` class: @@ -146,7 +146,7 @@ A complete sample app that uses Entity Framework Core with PostgreSQL is provide This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-9/csb-azure/index.html) - [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index 331c20ca..fca18dbf 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -122,8 +122,8 @@ This Connector supports the following service brokers: - [Redis for VMware Tanzu Application Service](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/redis-for-tanzu-application-service/3-5/redis-for-tas/index.html) - [Tanzu for Valkey on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-for-valkey-on-cloud-foundry/4-0/valkey-on-cf/index.html) -- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) -- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) +- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-5/csb-gcp/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: diff --git a/api/v4/connectors/usage.md b/api/v4/connectors/usage.md index f32be898..16d49747 100644 --- a/api/v4/connectors/usage.md +++ b/api/v4/connectors/usage.md @@ -271,7 +271,7 @@ builder.Services.AddDbContext( ## Advanced settings -Using the ASP.NET Options pattern by Steeltoe Connectors allows you to configure them using custom code. +Steeltoe Connectors use the ASP.NET Options pattern, which allows you to configure connections using custom code. For example, the code below adds the application name to the MongoDB connection URL at runtime: diff --git a/api/v4/discovery/configuration-based.md b/api/v4/discovery/configuration-based.md index 7a59d2ec..268cafb7 100644 --- a/api/v4/discovery/configuration-based.md +++ b/api/v4/discovery/configuration-based.md @@ -1,6 +1,6 @@ # Configuration-based discovery client -The simplest form of service discovery is implemented by storing the list of app instances in .NET configuration. +The simplest way to use service discovery is by storing the list of app instances in .NET configuration. ## Configuration settings diff --git a/api/v4/discovery/hashicorp-consul.md b/api/v4/discovery/hashicorp-consul.md index d1373867..0fed3bc2 100644 --- a/api/v4/discovery/hashicorp-consul.md +++ b/api/v4/discovery/hashicorp-consul.md @@ -64,15 +64,15 @@ All of these settings must start with `Consul:Discovery:`. | `UseAspNetCoreUrls` | Register with the port number ASP.NET Core is listening on | `true` | | `InstanceId` | The unique ID under which to register the running app | computed | | `Tags` | Array of tags used when registering the running app | | -| `Meta` | Metadata key/value pairs used when registering the running app | see [Configuring metadata](#configuring-metadata)| +| `Meta` | Metadata key/value pairs used when registering the running app | see [Configuring metadata](#configuring-metadata) | | `InstanceGroup` | Metadata `group` value to use when registering the running app | | | `InstanceZone` | Metadata zone value to use when registering the running app | | | `DefaultZoneMetadataName` | Metadata key name for `InstanceZone` | `zone` | | `RegisterHealthCheck` | Whether to enable periodic health checking for the running app | `true` | | `HealthCheckCriticalTimeout` | Duration after which Consul deregisters the running app when in state `critical` [^1] | `30m` | | `Heartbeat:Enabled` | Whether the running app periodically sends TTL (time-to-live) heartbeats [^1] | `true` | -| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy; used with `Heartbeat:TtlUnit` | every `30` seconds | -| `Heartbeat:TtlUnit` | Unit for `TtlValue` (`ms`, `s`, `m` or `h`) | `s` (seconds) | +| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy | `30` | +| `Heartbeat:TtlUnit` | Unit for `TtlValue` (`ms`, `s`, `m` or `h`) | `s` | | `Heartbeat:IntervalRatio` | Rate at which the running app sends TTL heartbeats, relative to `TtlValue` with `TtlUnit` | `0.66` | | `HealthCheckPath` | Relative URL to the health endpoint of the running app [^2] | `/actuator/health` | | `HealthCheckUrl` | Absolute URL to the health endpoint of the running app (overrides `HealthCheckPath`) [^2] | | diff --git a/api/v4/discovery/initialize-discovery-client.md b/api/v4/discovery/initialize-discovery-client.md index b65c9747..86791a96 100644 --- a/api/v4/discovery/initialize-discovery-client.md +++ b/api/v4/discovery/initialize-discovery-client.md @@ -12,7 +12,7 @@ Fundamentally, you have to follow these steps: ## Add NuGet packages -To get started with Steeltoe Discovery, add a reference to the package(s) containing the discovery technology you might want to use. +To get started with Steeltoe Discovery, add a reference to the package(s) containing the discovery technology you want to use. Each package also includes all the relevant dependencies. | Package | Description | @@ -44,7 +44,7 @@ var app = builder.Build(); ## Client configuration Discovery clients need to be explicitly configured to fetch application instances and/or register your app with the discovery server. -See the sub-page for the discovery technology of choice for instructions about how to set it up. +See the sub-topic for the discovery technology of choice for instructions about setting it up. ## Enable debug logging diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index e7b9d0d3..45b063da 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -112,7 +112,7 @@ After the app has fully started, the assigned port numbers are updated in Eureka ### Querying -The configuration settings that pertain to querying the Eureka registry for apps (used by the load balancers during service discovery) are shown in the table. +The configuration settings that pertain to querying the Eureka registry for apps (used by the load balancers during service discovery) are shown in the following table. All of these settings must start with `Eureka:Client:`. | Key | Description | Default | @@ -194,8 +194,8 @@ appManager.UpdateInstance(newStatus: null, newOverriddenStatus: null, > [!CAUTION] > After metadata has been updated from code, later metadata changes in configuration are ignored. -> -> In general, additional metadata does not change the behavior of applications, unless the apps are made aware of + +In general, additional metadata does not change the behavior of applications, unless they are made aware of the meaning of the metadata. ## Configuring mutual TLS diff --git a/api/v4/fileshares/usage.md b/api/v4/fileshares/usage.md index c61895d6..4b3e145c 100644 --- a/api/v4/fileshares/usage.md +++ b/api/v4/fileshares/usage.md @@ -1,4 +1,4 @@ -# Using Network File Share +# Using Network File Shares Before starting with Steeltoe's Windows Network File Share library, you should already have a plan for interacting with the file system. Steeltoe only manages the connection to the file share. diff --git a/api/v4/initializr/index.md b/api/v4/initializr/index.md index 01425fa0..8ebfbf24 100644 --- a/api/v4/initializr/index.md +++ b/api/v4/initializr/index.md @@ -5,7 +5,7 @@ Metadata may include, among other properties, a project name, a namespace, and a At the core of an Initializr is the [Steeltoe InitializrService](https://github.com/SteeltoeOSS/InitializrService). InitializrService provides several REST/HTTP endpoints, and includes: -* an endpoint to generate projects, and +* an endpoint to generate projects * an endpoint to provide smart clients the metadata needed to construct user interfaces It is possible to have a fully functioning Initializr deployment by simply deploying the InitializrService. diff --git a/api/v4/logging/dynamic-serilog-logging.md b/api/v4/logging/dynamic-serilog-logging.md index e4880b12..c2745131 100644 --- a/api/v4/logging/dynamic-serilog-logging.md +++ b/api/v4/logging/dynamic-serilog-logging.md @@ -4,7 +4,7 @@ This logging provider integrates with [Serilog](https://serilog.net/). It enable ## Usage -To use the Serilog Dynamic Logger, do the following: +To use the Serilog logging provider: 1. Add the appropriate NuGet package reference to your project. 2. Configure Logging settings. diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 5e4a0453..98fdaa7c 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -77,5 +77,5 @@ For this reason, all endpoints are exposed by default at `/cloudfoundryapplicati In addition, the endpoints may be secured by whatever security mechanism the application itself uses. For more details, see [securing actuators](./using-endpoints.md#securing-endpoints). > [!CAUTION] -> Applying an authorization policy on `/actuator` also has an impact on `/cloudfoundryapplication`, which then breaks the integration with Apps Manager. +> An authorization policy on `/actuator` also applies to `/cloudfoundryapplication`, which then breaks the integration with Apps Manager. > To prevent public access to `/actuator` when running on Cloud Foundry, consider configuring actuators to [use an alternate port](./using-endpoints.md#configure-global-settings). diff --git a/api/v4/management/health.md b/api/v4/management/health.md index aebf6e1a..6bf2d163 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -30,7 +30,7 @@ Each key must be prefixed with `Management:Endpoints:Health:`. | `Claim` | The claim required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized` | | | `Role` | The role required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized` | | -The depth of information exposed by the health endpoint depends on the `ShowComponents` and `ShowDetails` properties; both be configured with one of the following values: +The depth of information exposed by the health endpoint depends on the `ShowComponents` and `ShowDetails` properties; both can be configured with one of the following values: | Name | Description | | ------- | ----------- | @@ -238,21 +238,21 @@ These entries demonstrate enabling the probes and their groups, and specifies in #### Liveness -The "Liveness" state of an application instance tells whether its internal state allows it to work correctly, or recover itself if it's currently failing. A broken "Liveness" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application. +The Liveness state of an application tells whether its internal state is valid. If Liveness is broken, this means that the application itself is in a failed state and cannot recover from it. In this case, the best course of action is to restart the application instance. -Out of the box, any of Steeltoe's extension methods that set up the health actuator initialize the liveness state, `LivenessState.Correct`. The only other defined state for liveness is `LivenessState.Broken`, though Steeltoe code does not currently cover any conditions that set this state. +Out of the box, any of Steeltoe's extension methods that set up the health actuator initialize the liveness state with `LivenessState.Correct`. The only other defined state for liveness is `LivenessState.Broken`, though Steeltoe code does not currently cover any conditions that set this state. > [!CAUTION] -> In general, the "Liveness" state should not depend on external system checks such as a database, queue, or cache server. Including checks on external systems could trigger massive restarts and cascading failures across the platform. +> In general, the Liveness state should not depend on external system checks such as a database, queue, or cache server. Including checks on external systems could trigger massive restarts and cascading failures across the platform. #### Readiness -The "Readiness" state of an application instance describes whether the application is ready to handle traffic. A failing "Readiness" state tells the platform that it should not route traffic to the application instance. +The Readiness state tells whether the application is ready to accept client requests. If the Readiness state is unready, the platform should not route traffic to this instance. If an application is too busy processing a task queue, then it could declare itself as busy until its load is manageable again. Out of the box, any of Steeltoe's extension methods that set up the health actuator also: -* Registers a callback on [`ApplicationStarted`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstarted) to initialize the readiness state to `AcceptingTraffic` when the application has started -* Registers a callback on [`ApplicationStopping`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstopping) to change the state to `RefusingTraffic` when the application begins to shut down +* Register a callback on [`ApplicationStarted`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstarted) to initialize the readiness state to `AcceptingTraffic` when the application has started +* Register a callback on [`ApplicationStopping`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstopping) to change the state to `RefusingTraffic` when the application begins to shut down These are the only defined states for this availability type. diff --git a/api/v4/management/heapdump.md b/api/v4/management/heapdump.md index c229747a..907a4fde 100644 --- a/api/v4/management/heapdump.md +++ b/api/v4/management/heapdump.md @@ -29,7 +29,7 @@ Acceptable values are: ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/heapdump`. See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. diff --git a/api/v4/management/info.md b/api/v4/management/info.md index c111e567..a0e14684 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -69,8 +69,7 @@ This contributor exposes any values below the `Info` configuration key. For exam ### Git properties -* Exposes information from the `git.properties` Spring Boot file, if available -* Shows information from git, such as branch/tag name, commit hash, and remote +This contributor exposes information from the `git.properties` Spring Boot file. If available, the file contains information from git, such as branch/tag name, commit hash, and remote. > [!NOTE] > For an example of how to use this contributor within MSBuild using [GitInfo](https://github.com/devlooped/GitInfo), see the [Steeltoe Management sample](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src). diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index 9df2b9a0..d0134cef 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -95,7 +95,7 @@ For more information about HttpClient instrumentation for OpenTelemetry, see the ### .NET Runtime -To instrument the .NET Runtime for metrics: +To instrument the .NET runtime for metrics: 1. Add a reference to the `OpenTelemetry.Instrumentation.Runtime` NuGet package. @@ -181,7 +181,7 @@ If no instrumentation has been included, the response is very short: # EOF ``` -With the addition of [.NET Runtime instrumentation](#net-runtime), the response is similar to the following: +With the addition of [.NET runtime instrumentation](#net-runtime), the response is similar to the following: ```text # TYPE process_runtime_dotnet_gc_collections_count_total counter diff --git a/api/v4/management/using-endpoints.md b/api/v4/management/using-endpoints.md index 57ac1c08..9c61d2b0 100644 --- a/api/v4/management/using-endpoints.md +++ b/api/v4/management/using-endpoints.md @@ -166,7 +166,7 @@ builder.Services.AddHypermediaActuator().AddLoggersActuator().AddRefreshActuator ``` > [!NOTE] -> Use `AddAllActuators()` and `AddLoggingActuator()` to automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). You must set up [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) *before* adding actuators. For example: +> `AddAllActuators()` and `AddLoggingActuator()` automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). If you want to use [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) instead, add it *before* adding actuators. For example: > > ```csharp > using Steeltoe.Logging.DynamicSerilog; diff --git a/api/v4/security/certificate.md b/api/v4/security/certificate.md index 7117a7a9..3b7259ca 100644 --- a/api/v4/security/certificate.md +++ b/api/v4/security/certificate.md @@ -51,7 +51,7 @@ The root and intermediate certificates are automatically shared between applicat ### Add and use Certificate Authentication > [!NOTE] -> This section is required only on applications that are receiving certificate-authorized requests. +> This section is required only for applications that are receiving certificate-authorized requests. Several steps need to happen before certificate authorization policies can be used to secure resources: @@ -108,7 +108,7 @@ app.UseCertificateAuthorization(); ### Securing Endpoints > [!NOTE] -> This step is required only on applications that are receiving certificate-authorized requests. +> This step is required only for applications that are receiving certificate-authorized requests. As implied by the name of the extension method `AddOrgAndSpacePolicies` (from the previous section in this topic), Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints using the standard ASP.NET Core `Authorize` attribute with these security policies. @@ -158,13 +158,13 @@ To use app instance identity certificates in a client application, services must #### IHttpClientFactory integration > [!NOTE] -> This step is required only on applications that are sending certificate-authorized requests. +> This step is required only for applications that are sending certificate-authorized requests. For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` called `AddAppInstanceIdentityCertificate`. This method invokes code that handles loading certificates from paths defined in the application's configuration, monitors those file paths and their content for changes, and places the certificate in an HTTP header named `X-Client-Cert` on all outbound requests. > [!NOTE] -> For more information about IHttpClientFactory, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). +> For more information about `IHttpClientFactory`, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). ```csharp using Steeltoe.Security.Authorization.Certificate; diff --git a/api/v4/security/index.md b/api/v4/security/index.md index 9e8ef834..a9468a17 100644 --- a/api/v4/security/index.md +++ b/api/v4/security/index.md @@ -10,7 +10,7 @@ Choose from the following options when using Cloud Foundry security integration: In addition to authentication and authorization providers, Steeltoe security offers: -* [A security provider for using Redis on Cloud Foundry with ASP.NET Core Data Protection Key Ring storage](redis-key-storage-provider.md) +* [A security provider for using Redis/Valkey on Cloud Foundry with ASP.NET Core Data Protection Key Ring storage](redis-key-storage-provider.md) > [!NOTE] > Redis has been updated to [Valkey](https://valkey.io/topics/migration/). diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index a6c1bf1c..b29fdf67 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -23,16 +23,16 @@ To use this library: ### Add NuGet References -To use the provider, add: +To use this package, add NuGet package references to: -* a reference to the `Steeltoe.Security.Authentication.JwtBearer` NuGet package -* a reference to `Steeltoe.Configuration.CloudFoundry` (so that Cloud Foundry service bindings can be read by Steeltoe) +* `Steeltoe.Security.Authentication.JwtBearer` +* `Steeltoe.Configuration.CloudFoundry` (so that Cloud Foundry service bindings can be read by Steeltoe) ### Configure Settings The Steeltoe JWT Bearer library configures the Microsoft JWT Bearer implementation, so all supported settings are available in [`Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions). -`JwtBearerOptions` is bound to configuration values available in `Authentication:Schemes:Bearer`. The following example `appsettings.json` shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): +`JwtBearerOptions` is bound to configuration values at the key `Authentication:Schemes:Bearer`. The following example `appsettings.json` shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): ```json { @@ -63,7 +63,7 @@ builder.Configuration.AddCloudFoundryServiceBindings(); #### Local UAA -A UAA server, (such as [UAA Server for Steeltoe](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: +A UAA server, such as [UAA Server for Steeltoe](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this topic, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: ```json { @@ -106,7 +106,7 @@ builder.Services.AddAuthorizationBuilder() .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); ``` -The order of operations is important: +The middleware pipeline order is important: Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, as shown in the following example. ```csharp @@ -159,7 +159,7 @@ See the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/ ### Single Sign-On for VMware Tanzu -When using Single Sign-On for VMware Tanzu, you must identify the service plan to be used before you create a service instance of that plan. +When using Single Sign-On for VMware Tanzu, you must choose a service plan before you create a service instance. If you do not have an existing service plan, a platform operator might need to create a new plan for you. For information about service plans for use by developers, see the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). @@ -203,9 +203,9 @@ cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE cf restage MY_APPLICATION ``` -For details and instructions, see: +For more information, see: -* the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or +* the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) * the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) ### UAA Server diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index 11497706..16cafa74 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -1,4 +1,4 @@ -# Redis/Valkey Key Storage Provider +# Redis Key Storage Provider The Redis Key Storage Provider is commonly used when secured data needs to be shared between two or more instances of the same application. @@ -8,11 +8,11 @@ The Redis Key Storage Provider is commonly used when secured data needs to be sh By default, the [data protection system in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/data-protection/introduction) stores cryptographic keys on the local file system. Even when not used by the application directly, these cryptographic keys are used for systems like [session state](https://learn.microsoft.com/aspnet/core/fundamentals/app-state#session-state) storage. -By using the Steeltoe Redis key storage provider, you can easily reconfigure the data protection service to store these keys in Redis instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). +By using the Steeltoe Redis Key Storage Provider, you can easily reconfigure the data protection service to store these keys in Redis instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). For more information, see the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md). -## Using the Redis/Valkey Storage Provider +## Using the Redis Key Storage Provider To use this provider: @@ -94,7 +94,7 @@ builder.AddCloudFoundryConfiguration(); ### Cloud Foundry -To use the Redis data protection key ring provider on Cloud Foundry, use a supported [Redis service](../connectors/redis.md#cloud-foundry) to create and bind an instance of Redis to your application. +To store data protection keys in a Redis/Valkey cache on Cloud Foundry, use a supported [Redis service](../connectors/redis.md#cloud-foundry) to create and bind an instance of Redis/Valkey to your application. You can complete these steps using the Cloud Foundry command line, as follows: diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index 8be372ca..fa1acdc0 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -13,7 +13,7 @@ For more information about how to use this library, see the [Steeltoe Security s ## Using the OpenID Connect Library -To use the OpenID Connect Library: +To use the OpenID Connect library: 1. Add NuGet references. 1. Configure settings for the security provider. @@ -32,7 +32,7 @@ To use this package, add NuGet package references to: The Steeltoe OpenID Connect library configures the Microsoft OpenID Connect implementation, so all supported settings are available in [`Microsoft.AspNetCore.Authentication.OpenIdConnect.OpenIdConnectOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions). -`OpenIdConnectOptions` is bound to configuration values found under `Authentication:Schemes:OpenIdConnect`. The following example `appsettings.json` shows how to declare a list of permissions that should be requested for users. +`OpenIdConnectOptions` is bound to configuration values found at the key `Authentication:Schemes:OpenIdConnect`. The following example `appsettings.json` shows how to declare a list of permissions that should be requested for users. ```json { @@ -118,7 +118,7 @@ builder.Services.AddAuthorizationBuilder() .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); ``` -The order of operations is important: +The middleware pipeline order is important: Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, as shown in the following example. ```csharp @@ -178,7 +178,7 @@ The preceding example establishes the following security rules: ### Single Sign-On for VMware Tanzu -When using Single Sign-On for VMware Tanzu, you must identify the service plan to be used before creating a service instance of that plan. +When using Single Sign-On for VMware Tanzu, you must choose a service plan before you create a service instance. If you do not have an existing service plan, a platform operator may need to create a new plan for you. For the operator resource, see the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). This guide contains information about how to configure plans for developer use. diff --git a/api/v4/toc.yml b/api/v4/toc.yml index 55373f95..8102f25e 100644 --- a/api/v4/toc.yml +++ b/api/v4/toc.yml @@ -92,7 +92,7 @@ topicHref: fileshares/ items: - topicHref: fileshares/usage.md - name: Using Network File Share + name: Using Network File Shares - name: Security topicHref: security/ items: diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index 7c416d5b..4b266f70 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -6,7 +6,7 @@ Previous versions of Steeltoe offered either an implementation of OpenCensus or OpenTelemetry has evolved to the point that only a few lines of code are needed. So instead of providing a Steeltoe component, the guidance below is offered to accomplish the same. The benefit of this approach is greater flexibility: when OpenTelemetry changes, there's no need to wait for a new Steeltoe version before using it. -Steeltoe continues to directly offer an option for [log correlation](#log-correlation). This topic provides direction for developers looking to achieve the same outcomes Steeltoe has previously provided more directly. +Steeltoe continues to directly offer an option for [log correlation](#log-correlation). The remainder of this topic provides direction for developers looking to achieve the same outcomes Steeltoe has previously provided more directly. ## About distributed tracing @@ -46,7 +46,7 @@ To use the processor: 1. Add a reference to the `Steeltoe.Management.Tracing` NuGet package. -2. Register the processor: +1. Register the processor from `Program.cs`: ```csharp using Steeltoe.Management.Tracing; @@ -57,17 +57,17 @@ To use the processor: > [!NOTE] > This extension method also ensures that implementations of `IApplicationInstanceInfo` and `IDynamicLoggerProvider` have been registered. -> If you wish to customize either of these or use non-default implementations, make these changes before calling `AddTracingLogProcessor`. +> If you want to customize either of these or use non-default implementations, call their extension methods *before* calling `AddTracingLogProcessor`. ## OpenTelemetry To use OpenTelemetry, start by adding a reference to the `OpenTelemetry.Extensions.Hosting` NuGet package. -Other package references will probably be necessary, but these depend on your specific application needs. +Depending on your specific application needs, other package references will probably be necessary. This package provides access to `OpenTelemetryBuilder`, which is the main entrypoint to OpenTelemetry. -### Add Open Telemetry Tracing +### Add OpenTelemetry Tracing -To add Open Telemetry Tracing, use the following: +To use tracing with OpenTelemetry, add the following to your `Program.cs`: ```csharp var builder = WebApplication.CreateBuilder(args); @@ -75,7 +75,7 @@ builder.Services.AddOpenTelemetry().WithTracing(); ``` > [!NOTE] -> At this point, not much has changed for the application, but you will continue by making changes to add [instrumentation](#instrumenting-applications) and [exporting of traces](#exporting-distributed-traces) to this line. +> At this point, not much has changed for the application. The following sections will expand this line to add [instrumentation](#instrumenting-applications) and [exporting of traces](#exporting-distributed-traces). ### Sampler configuration @@ -89,7 +89,7 @@ As a replacement for what Steeltoe used to provide for using these samplers, set > [!NOTE] > OpenTelemetry is generally built to follow the [options pattern](https://learn.microsoft.com/dotnet/core/extensions/options). -> There are more ways to configure options than demonstrated on this page; these are just examples to help you get started. +> There are more ways to configure options than demonstrated in this topic; these are just examples to help you get started. ### Set Application Name @@ -217,7 +217,7 @@ To use B3 propagation: using B3Propagator = OpenTelemetry.Extensions.Propagators.B3Propagator; ``` -2. Register a `CompositeTextMapPropagator` that includes the `B3Propagator` and `BaggagePropagator`: +1. Register a `CompositeTextMapPropagator` that includes the `B3Propagator` and `BaggagePropagator`: ```csharp using OpenTelemetry; From a186b8d171dcc092f0ed8772738e4bf4e6dc7979 Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Wed, 26 Mar 2025 16:39:18 -0500 Subject: [PATCH 24/43] apply suggestions from review - auto-number bullets - which have been removed => that have been removed - .NET runtime - usage => using - wish => want --- api/v4/bootstrap/index.md | 2 +- .../configuration/cloud-foundry-provider.md | 4 +- .../configuration/config-server-provider.md | 7 +-- api/v4/configuration/placeholder-provider.md | 2 +- api/v4/configuration/random-value-provider.md | 2 +- api/v4/configuration/spring-boot-provider.md | 2 +- api/v4/connectors/microsoft-sql-server.md | 26 ++++----- api/v4/connectors/mongodb.md | 57 ++++++++++--------- api/v4/connectors/mysql.md | 2 +- api/v4/connectors/postgresql.md | 3 +- api/v4/connectors/redis.md | 2 +- api/v4/connectors/usage.md | 1 + api/v4/discovery/index.md | 2 +- api/v4/initializr/index.md | 4 +- api/v4/logging/dynamic-console-logging.md | 6 +- api/v4/logging/dynamic-serilog-logging.md | 6 +- api/v4/management/cloud-foundry.md | 2 +- api/v4/management/health.md | 2 +- api/v4/management/httpexchanges.md | 2 +- api/v4/management/info.md | 2 +- api/v4/management/prometheus.md | 4 +- api/v4/security/certificate.md | 10 ++-- api/v4/security/index.md | 2 +- api/v4/security/jwt-bearer.md | 8 +-- api/v4/security/redis-key-storage-provider.md | 6 +- api/v4/tracing/index.md | 4 +- api/v4/welcome/whats-new.md | 4 +- 27 files changed, 88 insertions(+), 86 deletions(-) diff --git a/api/v4/bootstrap/index.md b/api/v4/bootstrap/index.md index 609f23b7..a56f6a6a 100644 --- a/api/v4/bootstrap/index.md +++ b/api/v4/bootstrap/index.md @@ -42,7 +42,7 @@ builder.AddSteeltoe(); ## Excluding Components -If you wish to exclude a component from the automatic bootstrap process, you may add the feature's assembly name to the exclusions list. One example where this feature would be desired is if you want to control the order in which configuration providers are added. This example shows how to provide exclusions: +If you want to exclude a component from the automatic bootstrap process, you may add the feature's assembly name to the exclusions list. One example where this feature would be desired is if you want to control the order in which configuration providers are added. This example shows how to provide exclusions: ```csharp using Steeltoe.Bootstrap.AutoConfiguration; diff --git a/api/v4/configuration/cloud-foundry-provider.md b/api/v4/configuration/cloud-foundry-provider.md index 2ab4157a..3e2be65c 100644 --- a/api/v4/configuration/cloud-foundry-provider.md +++ b/api/v4/configuration/cloud-foundry-provider.md @@ -6,7 +6,7 @@ Cloud Foundry creates and uses these environment variables to communicate an app For more information about the Cloud Foundry environment variables, see the [Cloud Foundry documentation](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html). -## Usage +## Using the Cloud Foundry Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. @@ -34,7 +34,7 @@ var builder = WebApplication.CreateBuilder(args); builder.AddCloudFoundryConfiguration(); ``` -#### Add Configuration Provider without using the host builder extension method +#### Add Configuration Provider without options If you don't want to use the host builder extension method, the following code shows how to add the Cloud Foundry configuration provider to the `ConfigurationBuilder`: diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index c10af9e7..4613f43b 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -8,7 +8,7 @@ To gain a better understanding of the Spring Cloud Config Server, you should rea In addition to the Quick Start provided later, you can refer to the [Steeltoe ConfigurationProviders](https://github.com/SteeltoeOSS/Samples/tree/main/Configuration/src/ConfigurationProviders) sample application when you need to understand how to use this provider. -## Usage +## Using the Config Server Provider You should know how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. A basic understanding of the `ConfigurationBuilder` and how to add providers to the builder is necessary. @@ -53,9 +53,8 @@ The following example shows some provider settings that have been put in a JSON } ``` -The following table describes all the settings that can be used to configure the behavior of the provider: - -As mentioned earlier, all settings should start with `Spring:Cloud:Config:`. +The following table describes all the settings that can be used to configure the behavior of the provider. +All settings should start with `Spring:Cloud:Config:`. | Key | Description | Default | | --- | ----------- | ------- | diff --git a/api/v4/configuration/placeholder-provider.md b/api/v4/configuration/placeholder-provider.md index fa10918a..9a7ee9ac 100644 --- a/api/v4/configuration/placeholder-provider.md +++ b/api/v4/configuration/placeholder-provider.md @@ -6,7 +6,7 @@ A placeholder takes the form of `${key:subkey1:subkey2?defaultValue}`, where `ke Note that placeholder defaults (for example, `defaultValue`) can also be defined to be placeholders, and they are resolved as well. -## Usage +## Using the Placeholder Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. diff --git a/api/v4/configuration/random-value-provider.md b/api/v4/configuration/random-value-provider.md index ed17681e..0726b2eb 100644 --- a/api/v4/configuration/random-value-provider.md +++ b/api/v4/configuration/random-value-provider.md @@ -28,7 +28,7 @@ You can also use the generator with property placeholders. For example, consider } ``` -## Usage +## Using the Random Value Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. diff --git a/api/v4/configuration/spring-boot-provider.md b/api/v4/configuration/spring-boot-provider.md index 7ab649a2..0de0f8e9 100644 --- a/api/v4/configuration/spring-boot-provider.md +++ b/api/v4/configuration/spring-boot-provider.md @@ -5,7 +5,7 @@ This provider exists for interoperability with Spring Boot environment variables The Steeltoe Spring Boot configuration provider reads the JSON in the `SPRING_BOOT_APPLICATION` environment variable and adds its contents to the configuration. It does the same for command-line arguments. In both cases, any `.` delimiters in configuration keys are converted to `:`, which is the configuration key separator used by .NET. Likewise, Spring array syntax, such as `[1]`, is converted to .NET array syntax `:1`. -## Usage +## Using the Spring Boot Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. diff --git a/api/v4/connectors/microsoft-sql-server.md b/api/v4/connectors/microsoft-sql-server.md index 069fb195..68dfeda3 100644 --- a/api/v4/connectors/microsoft-sql-server.md +++ b/api/v4/connectors/microsoft-sql-server.md @@ -7,7 +7,7 @@ It supports the following .NET drivers: - [System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient), which provides an ADO.NET `DbConnection` - [Microsoft.EntityFrameworkCore.SqlServer](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.SqlServer), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md). +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. ## Using the Microsoft SQL Server Connector @@ -126,19 +126,19 @@ To retrieve data from SQL Server in your app using Entity Framework Core, use th 1. After you have configured and added your `DbContext` to the service container, you can inject it and use it in a controller or view: - ```csharp - using Microsoft.AspNetCore.Mvc; - using Microsoft.EntityFrameworkCore; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.EntityFrameworkCore; - public class HomeController : Controller - { - public async Task Index([FromServices] AppDbContext appDbContext) - { - List entities = await appDbContext.SampleEntities.ToListAsync(); - return View(entities); - } - } - ``` + public class HomeController : Controller + { + public async Task Index([FromServices] AppDbContext appDbContext) + { + List entities = await appDbContext.SampleEntities.ToListAsync(); + return View(entities); + } + } + ``` A complete sample app that uses Entity Framework Core with SQL Server is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/SqlServerEFCore. diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index 069830df..88d510f3 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -60,42 +60,43 @@ builder.AddMongoDb(); ### Use IMongoClient -Start by defining a class that contains collection data: -```csharp -using MongoDB.Bson; +1. Start by defining a class that contains collection data: -public class SampleObject -{ - public ObjectId Id { get; set; } - public string? Text { get; set; } -} -``` + ```csharp + using MongoDB.Bson; -To obtain an `IMongoClient` instance in your application, inject the Steeltoe factory in a controller or view: + public class SampleObject + { + public ObjectId Id { get; set; } + public string? Text { get; set; } + } + ``` -```csharp -using Microsoft.AspNetCore.Mvc; -using MongoDb.Data; -using MongoDB.Driver; -using Steeltoe.Connectors; -using Steeltoe.Connectors.MongoDb; +1. Obtain an `IMongoClient` instance in your application by injecting the Steeltoe factory in a controller or view: -public class HomeController : Controller -{ - public async Task Index( - [FromServices] ConnectorFactory connectorFactory) + ```csharp + using Microsoft.AspNetCore.Mvc; + using MongoDb.Data; + using MongoDB.Driver; + using Steeltoe.Connectors; + using Steeltoe.Connectors.MongoDb; + + public class HomeController : Controller { - var connector = connectorFactory.Get(); - IMongoClient client = connector.GetConnection(); + public async Task Index( + [FromServices] ConnectorFactory connectorFactory) + { + var connector = connectorFactory.Get(); + IMongoClient client = connector.GetConnection(); - IMongoDatabase database = client.GetDatabase(connector.Options.Database); - IMongoCollection collection = database.GetCollection("SampleObjects"); - List sampleObjects = await collection.Find(obj => true).ToListAsync(); + IMongoDatabase database = client.GetDatabase(connector.Options.Database); + IMongoCollection collection = database.GetCollection("SampleObjects"); + List sampleObjects = await collection.Find(obj => true).ToListAsync(); - return View(sampleObjects); + return View(sampleObjects); + } } -} -``` + ``` A complete sample app that uses `IMongoClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb. diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index 3a91e8c8..7ebbc6d8 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -8,7 +8,7 @@ It supports the following .NET drivers: - [Pomelo.EntityFrameworkCore.MySql](https://www.nuget.org/packages/Pomelo.EntityFrameworkCore.MySql), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support - [MySql.EntityFrameworkCore](https://www.nuget.org/packages/MySql.EntityFrameworkCore), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md). +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. ## Using the MySQL connector diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index 889657b5..5e15b876 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -2,10 +2,11 @@ This connector simplifies accessing [PostgreSQL](https://www.postgresql.org/) databases. It supports the following .NET drivers: + - [Npgsql](https://www.nuget.org/packages/Npgsql), which provides an ADO.NET `DbConnection`. - [Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -The remainder of this topic assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. ## Using the PostgreSQL connector diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index fca18dbf..1dff64ee 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -3,7 +3,7 @@ This connector simplifies accessing [Redis](https://redis.io/) databases. > [!NOTE] -> Redis has been updated to [Valkey](https://valkey.io/topics/migration/). +> This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases.. It supports the following .NET drivers: diff --git a/api/v4/connectors/usage.md b/api/v4/connectors/usage.md index 16d49747..ea95a54e 100644 --- a/api/v4/connectors/usage.md +++ b/api/v4/connectors/usage.md @@ -163,6 +163,7 @@ connectionOne.Open(); `ConnectorFactory` either returns a new connection/client instance each time or caches the first one, based on documented best practices for the specific .NET driver. +The cached instance is per named service, so when both service1 and service2 exist, there are two cached instances. ## Legacy host builders diff --git a/api/v4/discovery/index.md b/api/v4/discovery/index.md index a5944cae..8b21cef1 100644 --- a/api/v4/discovery/index.md +++ b/api/v4/discovery/index.md @@ -2,7 +2,7 @@ Service Discovery enables the use of friendly names for the microservices your app depends on. These microservices typically register themselves at startup to a discovery server, which acts as a central registry. -Each time your app connects to a microservice like this, the friendly name is resolved to the actual scheme/host/port by querying the discovery server. +Each time your app connects to one of those microservices, the friendly name is resolved to the actual scheme/host/port by querying the discovery server. A discovery server can track multiple instances for a single friendly name, which enables your app to load-balance across instances. It also tracks whether your microservice instances are still alive, using health checks and/or keep-alives. diff --git a/api/v4/initializr/index.md b/api/v4/initializr/index.md index 8ebfbf24..f22a27ae 100644 --- a/api/v4/initializr/index.md +++ b/api/v4/initializr/index.md @@ -3,13 +3,13 @@ An Initializr jumpstarts .NET development by generating projects based on project metadata. Metadata may include, among other properties, a project name, a namespace, and a list of dependencies. At the core of an Initializr is the [Steeltoe InitializrService](https://github.com/SteeltoeOSS/InitializrService). -InitializrService provides several REST/HTTP endpoints, and includes: +InitializrService provides several REST/HTTP endpoints, including: * an endpoint to generate projects * an endpoint to provide smart clients the metadata needed to construct user interfaces It is possible to have a fully functioning Initializr deployment by simply deploying the InitializrService. -A more user-friendly deployment might include a user interface, such as a web frontend or an IDE plug-in. +A more user-friendly deployment might include a user interface, such as a web frontend. A deployment may also use a [Spring Cloud Config Server](https://cloud.spring.io/spring-cloud-config/multi/multi__spring_cloud_config_server.html) to access a configuration store. As an example, the [Steeltoe Initializr deployment](https://start.steeltoe.io) includes [InitializrWeb](https://github.com/SteeltoeOSS/InitializrWeb) for a friendly user experience and a Spring Cloud Config Server using a GitHub-maintained configuration. diff --git a/api/v4/logging/dynamic-console-logging.md b/api/v4/logging/dynamic-console-logging.md index f82549ba..4209251d 100644 --- a/api/v4/logging/dynamic-console-logging.md +++ b/api/v4/logging/dynamic-console-logging.md @@ -8,15 +8,15 @@ This logging provider is a wrapper around the [Microsoft Console Logger](https:/ > [!CAUTION] > External tool integration involves sending the fully-qualified logger name over HTTP. Avoid using colons in the name of a logger to prevent invalid HTTP requests. -## Usage +## Using Dynamic Console Logging Before starting to use Steeltoe provider, you should know how [Logging in .NET](https://learn.microsoft.com/aspnet/core/fundamentals/logging) works; Steeltoe provides nothing more than a wrapper around the existing Microsoft console logger. To use the Steeltoe logging provider: 1. Add the appropriate NuGet package reference to your project. -2. Configure logging settings. -3. Add the dynamic logging provider to the logging builder. +1. Configure logging settings. +1. Add the dynamic logging provider to the logging builder. ### Add NuGet References diff --git a/api/v4/logging/dynamic-serilog-logging.md b/api/v4/logging/dynamic-serilog-logging.md index c2745131..2199e747 100644 --- a/api/v4/logging/dynamic-serilog-logging.md +++ b/api/v4/logging/dynamic-serilog-logging.md @@ -2,13 +2,13 @@ This logging provider integrates with [Serilog](https://serilog.net/). It enables logger minimum levels configured through Serilog to be queried and modified at runtime using the [loggers actuator](../management/loggers.md). -## Usage +## Using Dynamic Serilog Logging To use the Serilog logging provider: 1. Add the appropriate NuGet package reference to your project. -2. Configure Logging settings. -3. Add the Serilog Dynamic Logger to the logging builder. +1. Configure Logging settings. +1. Add the Serilog Dynamic Logger to the logging builder. ### Add NuGet References diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 98fdaa7c..878d1a8a 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -34,7 +34,7 @@ The default path is `/cloudfoundryapplication`. See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. -To add the actuator to the service container, add a [CORS](#cross-origin-resource-sharing) policy, register security middleware and map its route, and use the `AddCloudFoundryActuator` extension method. +To add the actuator to the service container, add a [CORS](#cross-origin-resource-sharing) policy, register security middleware and map its route, use the `AddCloudFoundryActuator` extension method. Add the following code to `Program.cs` to use the actuator endpoint: diff --git a/api/v4/management/health.md b/api/v4/management/health.md index 6bf2d163..2a9d95d6 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -296,7 +296,7 @@ app.Run(); If you want to provide custom health information for your application: 1. Create a class that implements the `IHealthContributor` interface. -2. Add the new class to the service container. +1. Add the new class to the service container. The following example contributor always returns a `HealthStatus` of `WARNING`: diff --git a/api/v4/management/httpexchanges.md b/api/v4/management/httpexchanges.md index 44d60e3d..9cae94a3 100644 --- a/api/v4/management/httpexchanges.md +++ b/api/v4/management/httpexchanges.md @@ -2,7 +2,7 @@ The Steeltoe HTTP Exchanges endpoint provides the ability to view the last several requests sent to your application. -When you activate this endpoint, an `IHttpExchangesRepository` implementation is registered; it stores HTTP request/response information in memory, and can be retrieved by using the endpoint. +When you activate this endpoint, an `IHttpExchangesRepository` implementation is registered, which stores HTTP request/response information in memory. This endpoint provides access to that information. ## Configure Settings diff --git a/api/v4/management/info.md b/api/v4/management/info.md index a0e14684..98515661 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -125,7 +125,7 @@ Depending on the registered contributors, this endpoint returns JSON similar to ## Custom Contributors -If you wish to provide custom information for your application, create a class that implements the `IInfoContributor` interface and then add it to the service container. +If you want to provide custom information for your application, create a class that implements the `IInfoContributor` interface and then add it to the service container. The following example contributor adds the local server time: diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index d0134cef..73507a74 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -83,7 +83,7 @@ To instrument `HttpClient`s for metrics: 1. Add a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. -2. Add the instrumentation to the `MeterProviderBuilder`: +1. Add the instrumentation to the `MeterProviderBuilder`: ```csharp using OpenTelemetry.Metrics; @@ -93,7 +93,7 @@ To instrument `HttpClient`s for metrics: For more information about HttpClient instrumentation for OpenTelemetry, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http). -### .NET Runtime +### .NET runtime To instrument the .NET runtime for metrics: diff --git a/api/v4/security/certificate.md b/api/v4/security/certificate.md index 3b7259ca..393ddd94 100644 --- a/api/v4/security/certificate.md +++ b/api/v4/security/certificate.md @@ -56,11 +56,11 @@ The root and intermediate certificates are automatically shared between applicat Several steps need to happen before certificate authorization policies can be used to secure resources: 1. Bind configuration values into named `CertificateOptions`. -2. Monitor certificate files for changes (to stay up to date when certificates are rotated). -3. Configure certificate forwarding (so that ASP.NET reads the certificate from an HTTP Header). -4. Add authentication services. -5. Add authorization services and policies. -6. Activate middleware. +1. Monitor certificate files for changes (to stay up to date when certificates are rotated). +1. Configure certificate forwarding (so that ASP.NET reads the certificate from an HTTP Header). +1. Add authentication services. +1. Add authorization services and policies. +1. Activate middleware. Fortunately, all of these requirements can be satisfied with a handful of extension methods: diff --git a/api/v4/security/index.md b/api/v4/security/index.md index a9468a17..014ae3b2 100644 --- a/api/v4/security/index.md +++ b/api/v4/security/index.md @@ -13,4 +13,4 @@ In addition to authentication and authorization providers, Steeltoe security off * [A security provider for using Redis/Valkey on Cloud Foundry with ASP.NET Core Data Protection Key Ring storage](redis-key-storage-provider.md) > [!NOTE] -> Redis has been updated to [Valkey](https://valkey.io/topics/migration/). +> This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases.. diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index b29fdf67..852fbba7 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -153,9 +153,9 @@ In the preceding example, if an incoming GET request is made to the `/api/sample See the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples using a user's access token to interact with downstream APIs, focusing on these locations: -* [Configure ASP.NET Core to save the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/appsettings.json#L15) -* [Get the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/Controllers/HomeController.cs#L60) -* [Include the token in a downstream request](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/ApiClients/JwtAuthorizationApiClient.cs#L24) +* [Configure ASP.NET Core to save the user's token](https://github.com/SteeltoeOSS/Samples/blob/4c0b222a8ea201240bb6b99aae46434864cf4dd1/Security/src/AuthWeb/appsettings.json#L15) +* [Get the user's token](https://github.com/SteeltoeOSS/Samples/blob/4c0b222a8ea201240bb6b99aae46434864cf4dd1/Security/src/AuthWeb/Controllers/HomeController.cs#L60) +* [Include the token in a downstream request](https://github.com/SteeltoeOSS/Samples/blob/4c0b222a8ea201240bb6b99aae46434864cf4dd1/Security/src/AuthWeb/ApiClients/JwtAuthorizationApiClient.cs#L24) ### Single Sign-On for VMware Tanzu @@ -226,4 +226,4 @@ And to bind the service instance to the app: cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE ``` -For additional information, refer to the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). +For additional information, see the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index 16cafa74..d00a71a5 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -3,12 +3,12 @@ The Redis Key Storage Provider is commonly used when secured data needs to be shared between two or more instances of the same application. > [!NOTE] -> Redis has been updated to [Valkey](https://valkey.io/topics/migration/). +> This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases. By default, the [data protection system in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/data-protection/introduction) stores cryptographic keys on the local file system. Even when not used by the application directly, these cryptographic keys are used for systems like [session state](https://learn.microsoft.com/aspnet/core/fundamentals/app-state#session-state) storage. -By using the Steeltoe Redis Key Storage Provider, you can easily reconfigure the data protection service to store these keys in Redis instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). +By using the Steeltoe Redis Key Storage Provider, you can easily reconfigure the data protection service to store these keys in Redis/Valkey instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). For more information, see the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md). @@ -31,7 +31,7 @@ If you are using Cloud Foundry service bindings, you must also add a reference t ### Configure connection string -You must configure a connection string to use Redis. +You must configure a connection string to use Redis/Valkey. The following example `appsettings.Development.json` uses a local Redis server listening on the default Redis port: ```json diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index 4b266f70..6511ac3d 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -110,7 +110,7 @@ builder.Services.ConfigureOpenTelemetryTracerProvider((serviceProvider, tracerPr The above example assumes you are already using some other Steeltoe component that adds `IApplicationInstanceInfo` to the IoC container. If that is not the case, follow these steps to register the default implementation: 1. Add a NuGet package reference to `Steeltoe.Common`. -2. Call `AddApplicationInstanceInfo`. +1. Call `AddApplicationInstanceInfo`. ```csharp using Steeltoe.Common.Extensions; @@ -136,7 +136,7 @@ To instrument requests coming into the application through ASP.NET Core: ```csharp using OpenTelemetry.Trace; - builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddAspNetCoreInstrumentation()); + builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing.AddAspNetCoreInstrumentation()); ``` 1. To replicate the Steeltoe setting `IngressIgnorePattern` (a Regex pattern describing which incoming requests to ignore), configure the `AspNetCoreTraceInstrumentationOptions`: diff --git a/api/v4/welcome/whats-new.md b/api/v4/welcome/whats-new.md index 82b2e914..43dbc443 100644 --- a/api/v4/welcome/whats-new.md +++ b/api/v4/welcome/whats-new.md @@ -206,7 +206,7 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | `Steeltoe.Common.Availability.ReadinessHealthContributor` | Type | Steeltoe.Common [Abstractions] | Removed | None | Made internal | | `Steeltoe.Common.CasingConventions.EnumExtensions.ToSnakeCaseString` | Extension method | Steeltoe.Common | Added | | Use to convert between .NET and Java enum member naming styles | | `Steeltoe.Common.CasingConventions.SnakeCaseAllCapsEnumMemberJsonConverter` | Type | Steeltoe.Common | Added | | Use to convert between .NET and Java enum member naming styles | -| `Steeltoe.Common.ConcurrentDictionaryExtensions.GetOrAddEx` | Extension method | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.ConcurrentDictionaryExtensions.GetOrAddEx` | Extension method | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.Configuration.ConfigurationValuesHelper` | Type | Steeltoe.Common [Abstractions] | Removed | None | Refactored to use ASP.NET Options pattern instead | | `Steeltoe.Common.Configuration.PropertyPlaceholderHelper` | Type | Steeltoe.Common [Abstractions] | Made internal | None | Placeholder substitution is handled in Steeltoe.Configuration.Placeholder package | | `Steeltoe.Common.Contexts` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed for SpEL support, which has been removed | @@ -236,7 +236,7 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | `Steeltoe.Common.Net.InetUtils` | Type | Steeltoe.Common [Abstractions] | Made internal | None | Internally used to resolve host names and IP addresses | | `Steeltoe.Common.Options.AbstractOptions` | Type | Steeltoe.Common [Abstractions] | Removed | None | Refactored to use ASP.NET Options pattern instead | | `Steeltoe.Common.Options.CertificateOptions` | Type | Steeltoe.Common [Abstractions] | Moved | Steeltoe.Common.Certificates package | | -| `Steeltoe.Common.Order` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.Order` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.Platform.IsFullFramework` | Property | Steeltoe.Common [Abstractions] | Removed | None | Support for .NET Framework is no longer available | | `Steeltoe.Common.Platform.IsNetCore` | Property | Steeltoe.Common [Abstractions] | Removed | None | This enum member is no longer needed | | `Steeltoe.Common.Reflection` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support Type Locators, which have been replaced with internal-only shims | From ae1f5a8cbcc3d20b93f161e8f4db249f6e8c3405 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 27 Mar 2025 13:57:42 +0100 Subject: [PATCH 25/43] Review feedback --- api/v4/connectors/redis.md | 7 ++----- api/v4/discovery/index.md | 2 +- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index 1dff64ee..c8e26fb5 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -1,9 +1,6 @@ # Redis/Valkey -This connector simplifies accessing [Redis](https://redis.io/) databases. - -> [!NOTE] -> This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases.. +This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases. It supports the following .NET drivers: @@ -16,7 +13,7 @@ The remainder of this topic assumes that you are familiar with the basic concept To use this connector: -1. Create a Redis server instance or use a [docker container](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#redis). +1. Create a Redis/Valkey server instance or use a [Redis docker container](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#redis) or [Valkey docker container](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#valkey). 1. Add NuGet references to your project. 1. Configure your connection string in `appsettings.json`. 1. Initialize the Steeltoe Connector at startup. diff --git a/api/v4/discovery/index.md b/api/v4/discovery/index.md index 8b21cef1..cf6c6ad8 100644 --- a/api/v4/discovery/index.md +++ b/api/v4/discovery/index.md @@ -9,7 +9,7 @@ It also tracks whether your microservice instances are still alive, using health While service discovery enables changing infrastructure without affecting your app, its real power lies in scalability. Discovery servers can typically be run in a cluster to eliminate the single point of failure. -And because they monitor the live-ness of your microservice instances, you can easily scale them up and down. +And because they monitor the liveness of your microservice instances, you can easily scale them up and down. Steeltoe facilitates both registration and querying of discovery servers by providing various implementations of `IDiscoveryClient`. To resolve friendly names, Steeltoe provides implementations of `ILoadBalancer`, which rely on `IDiscoveryClient`. From 4d4451af24d9e505451824a49e1981136400fa0c Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 27 Mar 2025 15:42:25 +0100 Subject: [PATCH 26/43] Revert changes from shell to bash code fence --- api/v4/configuration/config-server-provider.md | 2 +- api/v4/connectors/cosmosdb.md | 2 +- api/v4/connectors/microsoft-sql-server.md | 2 +- api/v4/connectors/mongodb.md | 2 +- api/v4/connectors/mysql.md | 2 +- api/v4/connectors/postgresql.md | 2 +- api/v4/connectors/rabbitmq.md | 2 +- api/v4/connectors/redis.md | 2 +- api/v4/initializr/initializr-service.md | 8 ++++---- api/v4/management/prometheus.md | 4 ++-- api/v4/management/tasks.md | 2 +- api/v4/security/jwt-bearer.md | 4 ++-- api/v4/security/redis-key-storage-provider.md | 2 +- api/v4/security/sso-open-id.md | 8 ++++---- api/v4/welcome/common-steps.md | 4 ++-- 15 files changed, 24 insertions(+), 24 deletions(-) diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index 4613f43b..0ad73a62 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -131,7 +131,7 @@ builder.AddConfigServer(); When you want to use a Config Server on Cloud Foundry and you have installed [Spring Cloud Services](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#provision-sccs-on-cloud-foundry), you can create and bind an instance of it to your application by using the Cloud Foundry CLI, as follows: -```bash +```shell # Create a Config Server instance named `myConfigServer` cf create-service p-config-server standard myConfigServer diff --git a/api/v4/connectors/cosmosdb.md b/api/v4/connectors/cosmosdb.md index a869e5f5..118d7beb 100644 --- a/api/v4/connectors/cosmosdb.md +++ b/api/v4/connectors/cosmosdb.md @@ -132,7 +132,7 @@ This Connector supports the following service brokers: You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create CosmosDB service cf create-service csb-azure-cosmosdb-sql mini myCosmosDbService diff --git a/api/v4/connectors/microsoft-sql-server.md b/api/v4/connectors/microsoft-sql-server.md index 68dfeda3..28a338ad 100644 --- a/api/v4/connectors/microsoft-sql-server.md +++ b/api/v4/connectors/microsoft-sql-server.md @@ -150,7 +150,7 @@ This Connector supports the following service brokers: You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create SQL Server service cf create-service csb-azure-mssql small-v2 mySqlServerService diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index 88d510f3..f2674fb0 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -108,7 +108,7 @@ This Connector supports the following service brokers: You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create MongoDB service cf create-service csb-azure-mongodb small myMongoDbService diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index 7ebbc6d8..5e937839 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -159,7 +159,7 @@ This Connector supports the following service brokers: You can create and bind an instance to your application using the Cloud Foundry CLI: -```bash +```shell # Create MySQL service cf create-service p.mysql db-small myMySqlService diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index 5e15b876..dd0e0a52 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -152,7 +152,7 @@ This Connector supports the following service brokers: You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create PostgreSQL service cf create-service csb-azure-postgresql small myPostgreSqlService diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index 8c0a905d..fd4118f6 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -93,7 +93,7 @@ This Connector supports the following service brokers: You can create and bind an instance to your application using the Cloud Foundry CLI: -```bash +```shell # Create RabbitMQ service cf create-service p.rabbitmq single-node myRabbitMQService diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index c8e26fb5..ac822149 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -124,7 +124,7 @@ This Connector supports the following service brokers: You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create Redis service cf create-service p-redis shared-vm myRedisService diff --git a/api/v4/initializr/initializr-service.md b/api/v4/initializr/initializr-service.md index 72216b13..69e9dd19 100644 --- a/api/v4/initializr/initializr-service.md +++ b/api/v4/initializr/initializr-service.md @@ -12,7 +12,7 @@ The InitializrService provides four REST/HTTP endpoints: `api/` accepts `GET` requests and returns a help document. The document includes available parameters (and their defaults) and dependencies, plus CLI samples. -```bash +```shell # sample: view help doc $ http -p b https://start.steeltoe.io/api/ ... @@ -32,7 +32,7 @@ The URI templates take a set of parameters to customize the result of a request. `api/about` accepts `GET` requests and returns the InitializrService "About" information. -```bash +```shell # sample: view "About" document $ http -p b https://start.steeltoe.io/api/about { @@ -61,7 +61,7 @@ The following endpoints can be used by CLI users to browse project configuration * `api/config/languages` * `api/config/steeltoeVersions` -```bash +```shell # sample: list available Steeltoe versions $ http -p b https://start.steeltoe.io/api/config/steeltoeVersions [ @@ -111,7 +111,7 @@ The parameter `dependencies` is different than other parameters in that it is se > [!NOTE] > To get a list of parameters and dependencies, send a `GET` request to `api/`. -```bash +```shell # sample: generate a .NET Core App 3.1 project with actuator endpoints and a Redis backend: $ http https://start.steeltoe.io/api/project dotNetFramework=netcoreapp3.1 dependencies==actuators,redis -d ``` diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index 73507a74..008aeba4 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -153,7 +153,7 @@ The specific port is not important to Steeltoe, it only matters that the binding Install the metrics-registrar plugin and use it to register your endpoint: -```bash +```shell cf install-plugin -r CF-Community "metric-registrar" cf register-metrics-endpoint APP-NAME /actuator/prometheus --internal-port 8091 ``` @@ -166,7 +166,7 @@ cf register-metrics-endpoint APP-NAME /actuator/prometheus --internal-port 8091 The result of using the metrics registrar plugin is a user-provided service, which can also be created and bound manually. -```bash +```shell cf create-user-provided-service APP-NAME -l secure-endpoint://:8091/actuator/prometheus cf bind-service APP-NAME SERVICE-NAME ``` diff --git a/api/v4/management/tasks.md b/api/v4/management/tasks.md index 00507776..c83ec8c9 100644 --- a/api/v4/management/tasks.md +++ b/api/v4/management/tasks.md @@ -111,7 +111,7 @@ As a matter of best practice, it is recommended that you provide the `RunTask` v However, due to the way .NET configuration works, it doesn't matter which configuration provider is used to provide the task name. Invoking the command on Cloud Foundry looks similar to this: -```bash +```shell cf run-task YourAppName "dotnet run -- RunTask=ExampleTaskName" --name ExampleTaskName ``` diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index 852fbba7..e95c383f 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -165,7 +165,7 @@ For information about service plans for use by developers, see the [Single Sign- After you have identified the service plan to use, create a service instance: -```bash +```shell cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE ``` @@ -195,7 +195,7 @@ applications: Alternatively, you can bind the instance manually and restage the app with the Cloud Foundry CLI. Then you can configure the SSO binding with the web interface: -```bash +```shell # Bind service to your app cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index d00a71a5..dbfb60a5 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -98,7 +98,7 @@ To store data protection keys in a Redis/Valkey cache on Cloud Foundry, use a su You can complete these steps using the Cloud Foundry command line, as follows: -```bash +```shell # Push your app cf push sampleApp --buildpack dotnet_core_buildpack diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index fa1acdc0..1833bc20 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -184,7 +184,7 @@ For the operator resource, see the [Single Sign-On for Tanzu operator guide](htt After you have identified the service plan to use, create a service instance: -```bash +```shell cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE ``` @@ -215,7 +215,7 @@ applications: Alternatively, you can bind the instance manually and restage the app with the Cloud Foundry CLI. Then you can configure the SSO binding with the web interface: -```bash +```shell # Bind service to your app cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE @@ -236,13 +236,13 @@ There is no service broker available to manage service instances or bindings for This command is an example of how the service instance can be created: -```bash +```shell cf cups MY_SERVICE_INSTANCE -p '{"auth_domain": "https://uaa.login.sys.cf-app.com","grant_types": [ "authorization_code", "client_credentials" ],"client_secret": "SOME_CLIENT_SECRET","client_id": "SOME_CLIENT_ID"}' ``` And to bind the service instance to the app: -```bash +```shell cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE ``` diff --git a/api/v4/welcome/common-steps.md b/api/v4/welcome/common-steps.md index 2454749c..09e80a5a 100644 --- a/api/v4/welcome/common-steps.md +++ b/api/v4/welcome/common-steps.md @@ -24,7 +24,7 @@ You can use the `dotnet` CLI to [build and locally publish](https://learn.micros This section describes how to use the [Cloud Foundry CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html) to push the published application to Cloud Foundry using the parameters that match what you selected for framework and runtime: -```bash +```shell # Push to Linux cell cf push -f manifest.yml -p bin/Debug/net8.0/linux-x64/publish @@ -41,7 +41,7 @@ To see the logs as you start the application, use `cf logs your-app-name`. On a Linux cell, you should see output similar to the following during startup: -```bash +```shell 2016-06-01T09:14:14.38-0600 [CELL/0] OUT Creating container 2016-06-01T09:14:15.93-0600 [CELL/0] OUT Successfully created container 2016-06-01T09:14:17.14-0600 [CELL/0] OUT Starting health monitoring of container From 83ec2e09b80210e5732c656a988d40d8c4de45c5 Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Thu, 27 Mar 2025 18:06:29 -0500 Subject: [PATCH 27/43] Apply suggestions from code review Co-authored-by: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> --- api/v4/configuration/config-server-provider.md | 2 +- api/v4/connectors/cosmosdb.md | 2 +- api/v4/connectors/mongodb.md | 2 +- api/v4/management/springbootadmin.md | 2 +- api/v4/security/redis-key-storage-provider.md | 2 +- api/v4/security/sso-open-id.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index 0ad73a62..c6a762a5 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -54,7 +54,7 @@ The following example shows some provider settings that have been put in a JSON ``` The following table describes all the settings that can be used to configure the behavior of the provider. -All settings should start with `Spring:Cloud:Config:`. +Each key must be prefixed with `Spring:Cloud:Config:`. | Key | Description | Default | | --- | ----------- | ------- | diff --git a/api/v4/connectors/cosmosdb.md b/api/v4/connectors/cosmosdb.md index 118d7beb..01c91cd3 100644 --- a/api/v4/connectors/cosmosdb.md +++ b/api/v4/connectors/cosmosdb.md @@ -60,7 +60,7 @@ builder.AddCosmosDb(); ### Use CosmosClient -To retrieve data from CosmosDB in your app, follow the steps below: +To retrieve data from CosmosDB in your app, use the following steps: 1. Define a class that contains container data: diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index f2674fb0..cc2a8637 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -60,7 +60,7 @@ builder.AddMongoDb(); ### Use IMongoClient -1. Start by defining a class that contains collection data: +1. Define a class that contains collection data: ```csharp using MongoDB.Bson; diff --git a/api/v4/management/springbootadmin.md b/api/v4/management/springbootadmin.md index 6bd99a18..58369841 100644 --- a/api/v4/management/springbootadmin.md +++ b/api/v4/management/springbootadmin.md @@ -57,7 +57,7 @@ a few additional steps are needed: - Register additional actuator endpoints - For the server to report the app as "UP," you must add at least the hypermedia and health actuators in `Program.cs`. + For the server to report the app as "UP", you must add at least the hypermedia and health actuators in `Program.cs`. > [!NOTE] > For testing, you can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin). diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index dbfb60a5..6d6e62fd 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -3,7 +3,7 @@ The Redis Key Storage Provider is commonly used when secured data needs to be shared between two or more instances of the same application. > [!NOTE] -> This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases. +> The Key Storage Provider can be used with [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases. By default, the [data protection system in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/data-protection/introduction) stores cryptographic keys on the local file system. Even when not used by the application directly, these cryptographic keys are used for systems like [session state](https://learn.microsoft.com/aspnet/core/fundamentals/app-state#session-state) storage. diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index 1833bc20..a58db878 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -84,7 +84,7 @@ A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/Steel > [!IMPORTANT] > If you want to use the Steeltoe UAA server without modification, some application configuration options will be very limited. -> Because the OpenID Connect authentication flow requires user redirection to known locations, the client `steeltoesamplesclient` is expected to listen at , so you must update `launchSettings.json` accordingly. +> Because the OpenID Connect authentication flow requires user redirection to known locations, the client `steeltoesamplesclient` is expected to listen at https://localhost:7072, so you must update `launchSettings.json` accordingly. > The Steeltoe UAA Server configuration is located in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L116). ### Add and use OpenID Connect From 33252eec1b758590a9bff5f721077cf8d98d765f Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 28 Mar 2025 11:54:58 +0100 Subject: [PATCH 28/43] Apply suggestions from code review Co-authored-by: Tim Hess --- api/v4/connectors/rabbitmq.md | 2 +- api/v4/discovery/netflix-eureka.md | 4 ++-- api/v4/security/index.md | 3 --- 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index fd4118f6..6d83748e 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -3,7 +3,7 @@ This connector simplifies accessing [RabbitMQ](https://www.rabbitmq.com/) message brokers. It supports the following .NET drivers: -- [RabbitMQ.Client](https://www.nuget.org/packages/RabbitMQ.Client), which provides an `IConnection`. +- [RabbitMQ.Client](https://www.nuget.org/packages/RabbitMQ.Client), which provides an `IConnection` The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 45b063da..16e1de35 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -63,7 +63,7 @@ All of these settings must start with `Eureka:Client:`. | Key | Description | Default | | --- | ----------- | ------- | | `ShouldRegisterWithEureka` | Whether to register the running app as a service instance | `true` | -| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see following section) | `true` | +| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see [Configuring health contributors](#configuring-health-contributors)) | `true` | Additionally, the table below lists the configuration settings that control *how* to register the instance. All of these settings must start with `Eureka:Instance:`. @@ -122,7 +122,7 @@ All of these settings must start with `Eureka:Client:`. | `ShouldFilterOnlyUpInstances` | Whether to include only instances with UP status after fetching the list of applications | `true` | | `ShouldDisableDelta` | Whether to fetch the full registry each time (`true`) or fetch only deltas (`false`) | `false` | | `RegistryRefreshSingleVipAddress` | Whether to fetch registry information only for the specified VIP address | `false` | -| `Health:MonitoredApps` | Comma-delimited list of applications in Eureka that this app depends on (see following section) | | +| `Health:MonitoredApps` | Comma-delimited list of applications in Eureka that this app depends on (see [Configuring health contributors](#configuring-health-contributors)) | | ## Configuring health contributors diff --git a/api/v4/security/index.md b/api/v4/security/index.md index 014ae3b2..b83cc89d 100644 --- a/api/v4/security/index.md +++ b/api/v4/security/index.md @@ -11,6 +11,3 @@ Choose from the following options when using Cloud Foundry security integration: In addition to authentication and authorization providers, Steeltoe security offers: * [A security provider for using Redis/Valkey on Cloud Foundry with ASP.NET Core Data Protection Key Ring storage](redis-key-storage-provider.md) - -> [!NOTE] -> This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases.. From 57c88637b328a5b67432bd9c40b5ab3d820eccf7 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 28 Mar 2025 11:58:19 +0100 Subject: [PATCH 29/43] Fix incorrect link --- api/v4/discovery/netflix-eureka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 16e1de35..8e59a621 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -63,7 +63,7 @@ All of these settings must start with `Eureka:Client:`. | Key | Description | Default | | --- | ----------- | ------- | | `ShouldRegisterWithEureka` | Whether to register the running app as a service instance | `true` | -| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see [Configuring health contributors](#configuring-health-contributors)) | `true` | +| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see [Configuring health contributors](#configuring-health-checks)) | `true` | Additionally, the table below lists the configuration settings that control *how* to register the instance. All of these settings must start with `Eureka:Instance:`. From d7aedc9354d586a0a5911b1c30a0757b8e946165 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 28 Mar 2025 12:07:37 +0100 Subject: [PATCH 30/43] Revert footnote changes --- api/v4/discovery/netflix-eureka.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 8e59a621..02c9c148 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -98,11 +98,7 @@ All of these settings must start with `Eureka:Instance:`. | `AsgName` | AWS auto-scaling group name associated with the instance | | | `DataCenterInfo` | Data center the instance is deployed to (`Netflix`, `Amazon`, or `MyOwn`) | `MyOwn` | -[^1]: When both non-secure and secure ports are enabled, the secure port is preferred during service discovery. The values for `Port` and `SecurePort`, and whether they are enabled, are automatically determined from the ASP.NET address bindings. See [8 ways to set the URLs for an ASP.NET Core app](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/) -for how to influence them using environment variables. -It is also possible to use dynamic port bindings (by setting the port number to `0` in ASP.NET). -In that case, Steeltoe adds a random number (outside the valid port range) to the `InstanceId` to make it unique. -After the app has fully started, the assigned port numbers are updated in Eureka, but the `InstanceId` does not change. +[^1]: When both non-secure and secure ports are enabled, the secure port is preferred during service discovery. [^2]: Specify `direct` to use container-to-container networking on Cloud Foundry. Specify `hostname` to force using `HostName`. @@ -110,6 +106,14 @@ After the app has fully started, the assigned port numbers are updated in Eureka [^4]: Add a NuGet package reference to `Steeltoe.Management.Endpoint` to use its `health` and `info` actuator paths. +The values for `Port` and `SecurePort`, and whether they are enabled, are automatically determined from the ASP.NET address bindings. [^1] +See [8 ways to set the URLs for an ASP.NET Core app](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/) +for how to influence them using environment variables. + +It is also possible to use dynamic port bindings (by setting the port number to `0` in ASP.NET). +In that case, Steeltoe adds a random number (outside the valid port range) to the `InstanceId` to make it unique. +After the app has fully started, the assigned port numbers are updated in Eureka, but the `InstanceId` does not change. + ### Querying The configuration settings that pertain to querying the Eureka registry for apps (used by the load balancers during service discovery) are shown in the following table. From 2a06d408d8d7835727b6c3c86464cf6a5fe591fa Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 28 Mar 2025 12:14:08 +0100 Subject: [PATCH 31/43] Address review feedback --- api/v4/management/health.md | 2 +- api/v4/tracing/index.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api/v4/management/health.md b/api/v4/management/health.md index 2a9d95d6..e5d1d971 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -366,7 +366,7 @@ When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `Whe ## ASP NET Core Health Checks -ASP.NET Core offers [middleware and libraries](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks) and abstractions for reporting health. There is wide community support for these abstractions from libraries such as [AspNetCore.Diagnostics.HealthChecks](https://github.com/Xabaril/AspNetCore.Diagnostics.HealthChecks). You can use these community-provided health checks and make them available using the health actuator endpoint (for integration with Cloud Foundry or any other infrastructure that depends on this format). In addition, Steeltoe Connectors expose functionality to get the connection string, which is needed to set up these community health checks. +ASP.NET Core offers [middleware and libraries](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks) and abstractions for reporting health. There is wide community support for these abstractions from libraries such as [AspNetCore.Diagnostics.HealthChecks](https://github.com/Xabaril/AspNetCore.Diagnostics.HealthChecks). You can use these community-provided health checks and make them available using the health actuator (for integration with Cloud Foundry or any other infrastructure that depends on this format). In addition, Steeltoe Connectors expose functionality to get the connection string, which is needed to set up these community health checks. For example, to use the Steeltoe MySQL connector, but replace its health contributor with the ASP.NET Core community health check, use the following code in `Program.cs`: diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index 6511ac3d..35ca6281 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -100,10 +100,10 @@ using OpenTelemetry.Resources; using OpenTelemetry.Trace; using Steeltoe.Common; -builder.Services.ConfigureOpenTelemetryTracerProvider((serviceProvider, tracerProviderBuilder) => +builder.Services.ConfigureOpenTelemetryTracerProvider((serviceProvider, tracing) => { var appInfo = serviceProvider.GetRequiredService(); - tracerProviderBuilder.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(appInfo.ApplicationName!)); + tracing.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(appInfo.ApplicationName!)); }); ``` @@ -183,7 +183,7 @@ To instrument requests leaving the application through `HttpClient`: ```csharp using OpenTelemetry.Trace; - builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddHttpClientInstrumentation()); + builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing.AddHttpClientInstrumentation()); ``` 1. To replicate the Steeltoe setting `EgressIgnorePattern` (a Regex pattern describing which outgoing HTTP requests to ignore), configure the `HttpClientTraceInstrumentationOptions`: @@ -253,7 +253,7 @@ To use the Zipkin Exporter: 1. Use the extension method `AddZipkinExporter` by updating the existing call from above to: ```csharp - builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddZipkinExporter()); + builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing.AddZipkinExporter()); ``` The Zipkin options class `ZipkinExporterOptions` works nearly the same as Steeltoe settings with the same names in previous releases: From 97f66da36ab84274f65ac181a9e401c02fbd20ed Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 28 Mar 2025 13:09:08 +0100 Subject: [PATCH 32/43] Fix copy/paste error --- api/v4/management/loggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/v4/management/loggers.md b/api/v4/management/loggers.md index e741db73..e1760113 100644 --- a/api/v4/management/loggers.md +++ b/api/v4/management/loggers.md @@ -24,7 +24,7 @@ The default path is `/actuator/loggers`. See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. -To add the actuator to the service container and map its route, use the `AddInfoActuator` extension method. +To add the actuator to the service container and map its route, use the `AddLoggersActuator` extension method. Add the following code to `Program.cs` to use the actuator endpoint: From 61252ad007749db52f8240e057943e122faed412 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 28 Mar 2025 13:43:49 +0100 Subject: [PATCH 33/43] Revert callouts to docfx style and review their severeties --- README.md | 4 ++-- api/v4/bootstrap/index.md | 2 +- api/v4/configuration/config-server-provider.md | 12 ++++++------ api/v4/configuration/decryption-provider.md | 2 +- api/v4/configuration/random-value-provider.md | 2 +- api/v4/discovery/discovering-services.md | 6 +++--- .../discovery/initialize-discovery-client.md | 2 +- api/v4/discovery/netflix-eureka.md | 8 ++++---- api/v4/initializr/initializr-service.md | 2 +- api/v4/management/cloud-foundry.md | 4 ++-- api/v4/management/dbmigrations.md | 4 ++-- api/v4/management/env.md | 2 +- api/v4/management/health.md | 4 ++-- api/v4/management/heapdump.md | 6 +++--- api/v4/management/httpexchanges.md | 2 +- api/v4/management/hypermedia.md | 4 ++-- api/v4/management/info.md | 6 +++--- api/v4/management/loggers.md | 18 +++++++++++++----- api/v4/management/mappings.md | 2 +- api/v4/management/prometheus.md | 2 +- api/v4/management/refresh.md | 4 ++-- api/v4/management/services.md | 2 +- api/v4/management/springbootadmin.md | 4 ++-- api/v4/management/tasks.md | 4 ++-- api/v4/management/threaddump.md | 6 +++--- api/v4/management/using-endpoints.md | 4 ++-- api/v4/security/certificate.md | 6 +++--- api/v4/security/redis-key-storage-provider.md | 4 ++-- api/v4/tracing/index.md | 6 +++--- api/v4/welcome/common-steps.md | 4 ++-- examples.md | 16 +++++++++++----- 31 files changed, 84 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index f06365c8..88ac4c2c 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Visual Studio Code users may find the [Docs Authoring Pack](https://marketplace. As you get familiar with DocFX, you'll notice the addition of a YAML header in the markdown files. Values in this header let you control page design, as well as set the page's `UID`. With this, you can create `xref` as well as use DocFX's `@` shorthand. Learn more about [linking in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). > [!NOTE] -> It should be very rare that you hardcode a link to an 'HTML' page with your markdown. Instead, use its `UID` and let the path get calculated, as well as get links validated when building the project. +> It should be very rare that you hardcode a link to an HTML page with your markdown. Instead, use its `UID` and let the path get calculated, as well as get links validated when building the project. ### Page display options @@ -98,7 +98,7 @@ Corresponding entry in `api/v2/toc.yml`: ## Installing DocFX -> [!NOTE] +> [!IMPORTANT] > This project currently expects DocFX version 2.59.4 to be available. ### Install with Chocolatey diff --git a/api/v4/bootstrap/index.md b/api/v4/bootstrap/index.md index a56f6a6a..c21ef3a9 100644 --- a/api/v4/bootstrap/index.md +++ b/api/v4/bootstrap/index.md @@ -51,7 +51,7 @@ HashSet assemblyNamesToExclude = [SteeltoeAssemblyNames.ConfigurationCon builder.AddSteeltoe(assemblyNamesToExclude); ``` -> [!NOTE] +> [!TIP] > The static class `SteeltoeAssemblyNames` enables you to easily find the name of any specific assembly to exclude. ## Logging inside Configuration Providers diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index c6a762a5..bd4a0564 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -35,7 +35,7 @@ The following example shows some provider settings that have been put in a JSON * `Spring:Application:Name` configures the "application name" to be `sample`. * `Spring:Cloud:Config:Uri` configures the address of the Config Server. -> [!NOTE] +> [!TIP] > The `Spring:Application:Name` key is also used by various other Steeltoe components. ```json @@ -87,7 +87,7 @@ Each key must be prefixed with `Spring:Cloud:Config:`. | `Health:Enabled` | Enable or disable Config Server health check contributor | `true` | | `Health:TimeToLive` | Health check contributor cache time to live, in milliseconds | `300_000` (5 min) | -> [!NOTE] +> [!TIP] > If you use self-signed certificates on Cloud Foundry, you might run into certificate validation issues when pushing an application. > A quick way to work around this is to disable certificate validation until a proper solution can be put in place. @@ -101,8 +101,8 @@ Then, after the JSON provider has been added, you can add the Config Server prov Because the JSON provider that reads `appsettings.json` has been added *before* the Config Server provider, the JSON-based settings become available to the Steeltoe provider. Note that you do not have to use JSON for the Steeltoe settings. You can use any of the other off-the-shelf configuration providers for the settings (such as INI files, environment variables, and so on). -> [!CAUTION] -> You must use the `Add*()` methods to add the source of the Config Server clients settings (`AddJsonFile(..)`) *before* you use `AddConfigServer(..)`. Otherwise, the settings are not picked up and used. +> [!IMPORTANT] +> You must use the `Add*()` methods to add the source of the Config Server clients settings, such as `AddJsonFile()`, *before* you use `AddConfigServer(..)`. Otherwise, the settings are not picked up and used. The following sample shows how to add a configuration provider: @@ -157,7 +157,7 @@ When the `ConfigurationBuilder` builds the configuration, the Config Server clie If there are any errors or problems accessing the server, the application continues to initialize, but the values from the server are not retrieved. If this is not the behavior you want, set `Spring:Cloud:Config:FailFast` to `true`. After that is done, the application fails to start if problems occur during the retrieval. -> [!NOTE] +> [!TIP] > To diagnose startup errors, activate bootstrap logging as described in [Application Bootstrapping](../bootstrap/index.md#logging-inside-configuration-providers). After the configuration has been built, you can access the retrieved data directly by using `IConfiguration`. See the following example: @@ -283,5 +283,5 @@ Aside from PEM files, Steeltoe supports a single file in PKCS#12 format: } ``` -> [!NOTE] +> [!TIP] > A single certificate can be shared with both Config Server and Eureka by using the key `Certificates` instead of `Certificates:ConfigServer`. diff --git a/api/v4/configuration/decryption-provider.md b/api/v4/configuration/decryption-provider.md index d664c700..89a55b28 100644 --- a/api/v4/configuration/decryption-provider.md +++ b/api/v4/configuration/decryption-provider.md @@ -107,5 +107,5 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddDecryption(new ExampleTextDecryptor(), NullLoggerFactory.Instance); ``` -> [!CAUTION] +> [!WARNING] > Creating encryption algorithms is notoriously difficult. Use this only if you know what you are doing. diff --git a/api/v4/configuration/random-value-provider.md b/api/v4/configuration/random-value-provider.md index 0726b2eb..279e8b26 100644 --- a/api/v4/configuration/random-value-provider.md +++ b/api/v4/configuration/random-value-provider.md @@ -53,7 +53,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddRandomValueSource(); ``` -> [!NOTE] +> [!TIP] > To generate random values as part of using placeholders, add the random value provider to the builder *before* you add the placeholder resolver. ### Access Random Value Data diff --git a/api/v4/discovery/discovering-services.md b/api/v4/discovery/discovering-services.md index 4e2857d2..02509619 100644 --- a/api/v4/discovery/discovering-services.md +++ b/api/v4/discovery/discovering-services.md @@ -8,8 +8,8 @@ The recommended approach is to use a typed `HttpClient`, supplied through [HttpClientFactory](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). Call the `.AddServiceDiscovery()` extension method from the `Steeltoe.Discovery.HttpClients` NuGet package to activate service discovery. -> [!NOTE] -> The `AddServiceDiscovery()` extension method takes an optional `ILoadBalancer` parameter. +> [!TIP] +> The `AddServiceDiscovery()` extension method takes an optional `ILoadBalancer` type parameter. > If no load balancer is provided, the built-in `RandomLoadBalancer` is activated, > which uses randomized selection of service instances. @@ -160,7 +160,7 @@ To use this load balancer in service discovery, pass it to the `AddServiceDiscov builder.Services.AddHttpClient().AddServiceDiscovery(); ``` -> [!NOTE] +> [!TIP] > When caching is activated (see above), this load balancer stores the last-used instance index in the cache. > Combining it with a shared Redis cache ensures an even load distribution. diff --git a/api/v4/discovery/initialize-discovery-client.md b/api/v4/discovery/initialize-discovery-client.md index 86791a96..2224914f 100644 --- a/api/v4/discovery/initialize-discovery-client.md +++ b/api/v4/discovery/initialize-discovery-client.md @@ -37,7 +37,7 @@ builder.Services.AddConfigurationDiscoveryClient(); var app = builder.Build(); ``` -> [!NOTE] +> [!TIP] > Alternatively, you can use `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration), which uses reflection to determine > which discovery assemblies are loaded, and adding the appropriate clients automatically. diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 02c9c148..65b43573 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -30,7 +30,7 @@ For a complete understanding of the effects of many of these settings, we recomm In most cases, unless you are confident that you understand the effects of changing the values from their defaults, we recommend that you use the defaults. -> [!NOTE] +> [!TIP] > Since Steeltoe v4, most of these settings can be changed at runtime, and the Eureka server is updated accordingly. ### General @@ -196,7 +196,7 @@ appManager.UpdateInstance(newStatus: null, newOverriddenStatus: null, }); ``` -> [!CAUTION] +> [!IMPORTANT] > After metadata has been updated from code, later metadata changes in configuration are ignored. In general, additional metadata does not change the behavior of applications, unless they are made aware of @@ -229,7 +229,7 @@ or: > [!NOTE] > To support certificate rotation, the configuration keys and the files on disk are automatically monitored for changes. -> [!NOTE] +> [!TIP] > A single certificate can be shared with both Config Server and Eureka by using the key `Certificates`, instead of `Certificates:Eureka`. ### Using custom HTTP headers @@ -262,5 +262,5 @@ public sealed class ExtraRequestHeaderDelegatingHandler : DelegatingHandler } ``` -> [!NOTE] +> [!TIP] > To send an extra header to the OAuth2 endpoint, replace `"Eureka"` with `"AccessTokenForEureka"` in the preceding example. diff --git a/api/v4/initializr/initializr-service.md b/api/v4/initializr/initializr-service.md index 69e9dd19..ea5b7061 100644 --- a/api/v4/initializr/initializr-service.md +++ b/api/v4/initializr/initializr-service.md @@ -108,7 +108,7 @@ $ http https://start.steeltoe.io/api/config/dependencies | jq '.[] .values[] .id Projects are configured using HTTP parameters, such as `name` for the project name and `steeltoeVersion` for the Steeltoe version. The parameter `dependencies` is different than other parameters in that it is set to a comma-separated list of dependency IDs. -> [!NOTE] +> [!TIP] > To get a list of parameters and dependencies, send a `GET` request to `api/`. ```shell diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 878d1a8a..ca730f57 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -8,7 +8,7 @@ When used, this endpoint enables the following additional functionality on Cloud * All endpoints are also mapped under the base path `/cloudfoundryapplication`. * [Authentication and authorization](#security) for your Cloud Foundry environment is added to the request pipeline. -> [!NOTE] +> [!IMPORTANT] > The Cloud Foundry integration works only when the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured. ## Configure Settings @@ -47,7 +47,7 @@ builder.Configuration.AddCloudFoundry(); builder.Services.AddCloudFoundryActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/dbmigrations.md b/api/v4/management/dbmigrations.md index 9ade7b69..0731d82a 100644 --- a/api/v4/management/dbmigrations.md +++ b/api/v4/management/dbmigrations.md @@ -2,7 +2,7 @@ The Steeltoe Database Migrations endpoint exposes information about database migrations that are available to an application's data source that has been built with Entity Framework Core (EF Core). EF Core migrations give developers the ability to update an application's database schema while staying consistent with the application's data model, and without removing any existing data. -> [!NOTE] +> [!TIP] > For more detailed information, see [EF Core Migrations Overview](https://learn.microsoft.com/ef/core/managing-schemas/migrations) in the Microsoft documentation. ## Configure Settings @@ -36,7 +36,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddDbMigrationsActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/env.md b/api/v4/management/env.md index 42e0d13b..f9fa3852 100644 --- a/api/v4/management/env.md +++ b/api/v4/management/env.md @@ -36,7 +36,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddEnvironmentActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/health.md b/api/v4/management/health.md index e5d1d971..99993832 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -82,7 +82,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHealthActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. @@ -91,7 +91,7 @@ For example, when a health check fails, the response status code is `503 Service The configuration key `Management:Endpoints:UseStatusCodeFromResponse` can be set to `false`, which makes the health check always respond with status code `200 OK`. Clients can overrule this per request by sending an `X-Use-Status-Code-From-Response` HTTP header with the value `true` or `false`. -> [!NOTE] +> [!TIP] > By default, health contributors for disk space and ping are activated. They can be turned off through configuration: > > ```json diff --git a/api/v4/management/heapdump.md b/api/v4/management/heapdump.md index 907a4fde..4514c096 100644 --- a/api/v4/management/heapdump.md +++ b/api/v4/management/heapdump.md @@ -24,8 +24,8 @@ Acceptable values are: * `Triage` * `Full` -> [!IMPORTANT] -> On macOS, this setting is ignored and a gcdump is always captured. +> [!NOTE] +> On macOS, the `HeapDumpType` setting is ignored and a gcdump is always captured. ## Enable HTTP Access @@ -45,6 +45,6 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHeapDumpActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/httpexchanges.md b/api/v4/management/httpexchanges.md index 9cae94a3..b0b8b4f0 100644 --- a/api/v4/management/httpexchanges.md +++ b/api/v4/management/httpexchanges.md @@ -104,7 +104,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHttpExchangesActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/hypermedia.md b/api/v4/management/hypermedia.md index 9fc6e1ea..3a251c98 100644 --- a/api/v4/management/hypermedia.md +++ b/api/v4/management/hypermedia.md @@ -40,7 +40,7 @@ Each key must be prefixed with `Management:Endpoints:Actuator:`. Note this key d The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator`. -> [!NOTE] +> [!IMPORTANT] > When running on Cloud Foundry, the [Cloud Foundry Actuator](./cloud-foundry.md) should be used instead. > Its default path is `/cloudfoundryapplication`. @@ -57,7 +57,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddHypermediaActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/info.md b/api/v4/management/info.md index 98515661..b4ab63af 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -37,7 +37,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddInfoActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. @@ -63,7 +63,7 @@ This contributor exposes any values below the `Info` configuration key. For exam } ``` -> [!NOTE] +> [!TIP] > When combined with the [Placeholder Configuration Provider](../configuration/placeholder-provider.md), > compound configuration values can be exposed originating from other places in configuration. @@ -71,7 +71,7 @@ This contributor exposes any values below the `Info` configuration key. For exam This contributor exposes information from the `git.properties` Spring Boot file. If available, the file contains information from git, such as branch/tag name, commit hash, and remote. -> [!NOTE] +> [!TIP] > For an example of how to use this contributor within MSBuild using [GitInfo](https://github.com/devlooped/GitInfo), see the [Steeltoe Management sample](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src). ## Sample Output diff --git a/api/v4/management/loggers.md b/api/v4/management/loggers.md index e1760113..304f24e3 100644 --- a/api/v4/management/loggers.md +++ b/api/v4/management/loggers.md @@ -35,13 +35,21 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddLoggersActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. > [!NOTE] -> When `AddLoggersActuator` is called, it tries to register [Dynamic Console Logging](../logging/dynamic-console-logging.md). -> If you'd like to use Serilog instead, call `AddDynamicSerilog` *before* calling `AddLoggersActuator`. +> `AddAllActuators()` and `AddLoggingActuator()` automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). If you want to use [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) instead, add it *before* adding actuators. For example: +> +> ```csharp +> using Steeltoe.Logging.DynamicSerilog; +> using Steeltoe.Management.Endpoint.Actuators.All; +> +> var builder = WebApplication.CreateBuilder(args); +> builder.Logging.AddDynamicSerilog(); +> builder.Services.AddLoggersActuator(); +> ``` ## Retrieving Minimum Log Levels @@ -135,7 +143,7 @@ by sending a POST request to `/actuator/loggers/Steeltoe.Management` with the fo } ``` -> [!NOTE] +> [!CAUTION] > Because the logger category is part of the request URL, avoid using colons in the name to prevent invalid HTTP requests. To verify that the change was applied, send a `GET` request to `/actuator/loggers` to see the updated loggers. @@ -203,5 +211,5 @@ The returned `ILogger` instances are also wrapped so that the minimum level can When changes to `appsettings.json` are saved, existing loggers are updated with the new minimum levels, unless they are overridden. A reset of an overridden logger reverts to the updated level from `appsettings.json`. -> [!NOTE] +> [!TIP] > The Steeltoe dynamic logging provider can be combined with `BootstrapLoggerFactory` to upgrade loggers after startup. diff --git a/api/v4/management/mappings.md b/api/v4/management/mappings.md index 50e77c12..50f64293 100644 --- a/api/v4/management/mappings.md +++ b/api/v4/management/mappings.md @@ -34,7 +34,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddRouteMappingsActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index 008aeba4..94d930f6 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -158,7 +158,7 @@ cf install-plugin -r CF-Community "metric-registrar" cf register-metrics-endpoint APP-NAME /actuator/prometheus --internal-port 8091 ``` -> [!CAUTION] +> [!IMPORTANT] > Due to an issue with the Cloud Foundry CLI plugin interface, some variations on this command do not work on Windows. > If you are a Windows user, you should either use the metric registrar plugin from WSL or use another method. diff --git a/api/v4/management/refresh.md b/api/v4/management/refresh.md index ac575a82..d3f1ecb7 100644 --- a/api/v4/management/refresh.md +++ b/api/v4/management/refresh.md @@ -17,7 +17,7 @@ Each key must be prefixed with `Management:Endpoints:Refresh:`. | `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `POST` | | `ReturnConfiguration` | Whether to return the configuration after refresh | `true` | -> [!NOTE] +> [!CAUTION] > Despite it being *possible* to configure this endpoint to respond to `GET` requests, > this is discouraged because it is not a [Safe HTTP Method](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP). @@ -39,7 +39,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddRefreshActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/services.md b/api/v4/management/services.md index ad2b6a8a..86c6c38f 100644 --- a/api/v4/management/services.md +++ b/api/v4/management/services.md @@ -36,7 +36,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddServicesActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/springbootadmin.md b/api/v4/management/springbootadmin.md index 58369841..b8de89df 100644 --- a/api/v4/management/springbootadmin.md +++ b/api/v4/management/springbootadmin.md @@ -59,7 +59,7 @@ a few additional steps are needed: For the server to report the app as "UP", you must add at least the hypermedia and health actuators in `Program.cs`. -> [!NOTE] +> [!TIP] > For testing, you can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin). Putting it all together, your config files contain the contents shown in the following: @@ -141,5 +141,5 @@ app.MapControllers(); app.Run(); ``` -> [!NOTE] +> [!TIP] > To see all the Spring Boot Admin features in action, replace the `Add*Actuator()` calls in `Program.cs` with `AddAllActuators()` and expose all endpoints. See [Exposing endpoints](./using-endpoints.md#exposing-endpoints). diff --git a/api/v4/management/tasks.md b/api/v4/management/tasks.md index c83ec8c9..c666dd5a 100644 --- a/api/v4/management/tasks.md +++ b/api/v4/management/tasks.md @@ -42,7 +42,7 @@ public class ExampleTask(ILogger logger) : IApplicationTask } ``` -> [!NOTE] +> [!TIP] > Steeltoe includes the `MigrateDbContextTask` task, which runs database migrations with Entity Framework Core. > It requires a reference to the `Steeltoe.Connectors.EntityFrameworkCore` NuGet package. @@ -115,7 +115,7 @@ Invoking the command on Cloud Foundry looks similar to this: cf run-task YourAppName "dotnet run -- RunTask=ExampleTaskName" --name ExampleTaskName ``` -> [!NOTE] +> [!TIP] > The command line configuration provider is added by default when using `WebApplication.CreateBuilder(args)`. > If the task does not fire when running from the command line with the `RunTask=` parameter, > verify that the configuration provider has been added for your application. diff --git a/api/v4/management/threaddump.md b/api/v4/management/threaddump.md index 1307510f..6037fd12 100644 --- a/api/v4/management/threaddump.md +++ b/api/v4/management/threaddump.md @@ -15,8 +15,8 @@ Each key must be prefixed with `Management:Endpoints:ThreadDump:`. | `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 | `GET` | -> [!NOTE] -> In version 4, the configuration key prefix for this endpoint changed from `Management:Endpoints:Dump:` to `Management:Endpoints:ThreadDump:` +> [!IMPORTANT] +> In version 4, the configuration key prefix for this endpoint changed from `Management:Endpoints:Dump:` to `Management:Endpoints:ThreadDump:`. ## Enable HTTP Access @@ -36,7 +36,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddThreadDumpActuator(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/using-endpoints.md b/api/v4/management/using-endpoints.md index 9c61d2b0..653c25c2 100644 --- a/api/v4/management/using-endpoints.md +++ b/api/v4/management/using-endpoints.md @@ -119,7 +119,7 @@ To expose all endpoints, you can use `*`. For example, to expose everything exce } ``` -> [!NOTE] +> [!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](./cloud-foundry.md#security). > Individual endpoints can be turned off by setting `Enabled` to `false`, which applies to both URLs. @@ -150,7 +150,7 @@ var builder = WebApplication.CreateBuilder(args); builder.Services.AddAllActuators(); ``` -> [!NOTE] +> [!TIP] > It is recommended that you use `AddAllActuators()` instead of adding individual actuators; > this enables individually turning them on/off at runtime using configuration. diff --git a/api/v4/security/certificate.md b/api/v4/security/certificate.md index 393ddd94..112887a7 100644 --- a/api/v4/security/certificate.md +++ b/api/v4/security/certificate.md @@ -78,7 +78,7 @@ builder.Services.AddAuthorizationBuilder() .AddOrgAndSpacePolicies(); ``` -> [!NOTE] +> [!TIP] > Steeltoe configures the certificate forwarding middleware to look for a certificate in the `X-Client-Cert` HTTP header. > To change the HTTP header name used for authorization, include it when registering the policy. For example: `.AddOrgAndSpacePolicies("X-Custom-Certificate-Header")`. @@ -112,7 +112,7 @@ app.UseCertificateAuthorization(); As implied by the name of the extension method `AddOrgAndSpacePolicies` (from the previous section in this topic), Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints using the standard ASP.NET Core `Authorize` attribute with these security policies. -> [!NOTE] +> [!TIP] > For more information about authorization in ASP.NET Core, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/security/authorization/introduction). The following example shows a controller using the security attributes with the included policies: @@ -163,7 +163,7 @@ To use app instance identity certificates in a client application, services must For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` called `AddAppInstanceIdentityCertificate`. This method invokes code that handles loading certificates from paths defined in the application's configuration, monitors those file paths and their content for changes, and places the certificate in an HTTP header named `X-Client-Cert` on all outbound requests. -> [!NOTE] +> [!TIP] > For more information about `IHttpClientFactory`, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). ```csharp diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index 6d6e62fd..d32b1bd2 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -116,7 +116,7 @@ After the service is bound to your application, the configuration settings are a > [!NOTE] > The preceding commands are for the Redis service provided by Tanzu Platform for Cloud Foundry. -> If you use a different service, you have to adjust the `create-service` command. +> If you use a different service, adjust the `create-service` command accordingly. -> [!NOTE] +> [!TIP] > For more information, see the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md). diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index 35ca6281..69a1fbc1 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -56,7 +56,7 @@ To use the processor: ``` > [!NOTE] -> This extension method also ensures that implementations of `IApplicationInstanceInfo` and `IDynamicLoggerProvider` have been registered. +> The `AddTracingLogProcessor()` extension method also ensures that implementations of `IApplicationInstanceInfo` and `IDynamicLoggerProvider` have been registered. > If you want to customize either of these or use non-default implementations, call their extension methods *before* calling `AddTracingLogProcessor`. ## OpenTelemetry @@ -87,7 +87,7 @@ As a replacement for what Steeltoe used to provide for using these samplers, set * `always_on` * `always_off` -> [!NOTE] +> [!TIP] > OpenTelemetry is generally built to follow the [options pattern](https://learn.microsoft.com/dotnet/core/extensions/options). > There are more ways to configure options than demonstrated in this topic; these are just examples to help you get started. @@ -269,5 +269,5 @@ builder.Services.Configure(options => }); ``` -> [!NOTE] +> [!TIP] > The Zipkin endpoint can also be set with the environment variable `OTEL_EXPORTER_ZIPKIN_ENDPOINT`. diff --git a/api/v4/welcome/common-steps.md b/api/v4/welcome/common-steps.md index 09e80a5a..26a58297 100644 --- a/api/v4/welcome/common-steps.md +++ b/api/v4/welcome/common-steps.md @@ -28,12 +28,12 @@ This section describes how to use the [Cloud Foundry CLI](https://docs.cloudfoun # Push to Linux cell cf push -f manifest.yml -p bin/Debug/net8.0/linux-x64/publish -# Push to Windows cell, .NET Core +# Push to Windows cell cf push -f manifest-windows.yml -p bin/Debug/net8.0/win-x64/publish ``` > [!NOTE] -> All sample manifests have been defined to bind their application to the services as created earlier. +> All samples contain manifest files to bind to the services they depend on. ### Observe the Logs diff --git a/examples.md b/examples.md index 204b516c..0d0d9f73 100644 --- a/examples.md +++ b/examples.md @@ -5,13 +5,19 @@ title: Example markdown # These are example markdown items > [!NOTE] -> This is a note - -> [!WARNING] -> This is a warning +> Information the user should notice even if skimming. > [!TIP] -> This is a tip +> Optional information to help a user be more successful. + +> [!IMPORTANT] +> Essential information required for user success. + +> [!CAUTION] +> Negative potential consequences of an action. + +> [!WARNING] +> Dangerous certain consequences of an action. ## Sectioned code From 4ce8e7045deef663f855f7c1d1c9b88326e9b0a8 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 28 Mar 2025 14:11:35 +0100 Subject: [PATCH 34/43] Match up description with link target --- api/v4/discovery/netflix-eureka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 65b43573..b8d354de 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -63,7 +63,7 @@ All of these settings must start with `Eureka:Client:`. | Key | Description | Default | | --- | ----------- | ------- | | `ShouldRegisterWithEureka` | Whether to register the running app as a service instance | `true` | -| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see [Configuring health contributors](#configuring-health-checks)) | `true` | +| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see [Configuring health checks](#configuring-health-checks)) | `true` | Additionally, the table below lists the configuration settings that control *how* to register the instance. All of these settings must start with `Eureka:Instance:`. From 920c3b08a734ed382177779a8d705cb81b0d2d2b Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Wed, 2 Apr 2025 10:27:32 +0200 Subject: [PATCH 35/43] Apply suggestions from code review Co-authored-by: Tim Hess --- api/v4/security/jwt-bearer.md | 2 +- api/v4/security/sso-open-id.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index e95c383f..16f621b2 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -161,7 +161,7 @@ See the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/ When using Single Sign-On for VMware Tanzu, you must choose a service plan before you create a service instance. If you do not have an existing service plan, a platform operator might need to create a new plan for you. -For information about service plans for use by developers, see the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). +For information about configuring service plans for use by developers, a platform operator should follow the steps in the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). After you have identified the service plan to use, create a service instance: diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index a58db878..195e2bb4 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -180,7 +180,7 @@ The preceding example establishes the following security rules: When using Single Sign-On for VMware Tanzu, you must choose a service plan before you create a service instance. If you do not have an existing service plan, a platform operator may need to create a new plan for you. -For the operator resource, see the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). This guide contains information about how to configure plans for developer use. +For information about configuring service plans for use by developers, a platform operator should follow the steps in the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). After you have identified the service plan to use, create a service instance: From c22f9ed8d30cbfc9c84e3a321ab05c84bf60d6ad Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 3 Apr 2025 17:52:26 +0200 Subject: [PATCH 36/43] Remove trailing periods from markdown tables --- api/v4/configuration/config-server-provider.md | 10 +++++----- api/v4/configuration/decryption-provider.md | 16 ++++++++-------- api/v4/discovery/netflix-eureka.md | 2 +- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index bd4a0564..f71a269d 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -64,16 +64,16 @@ Each key must be prefixed with `Spring:Cloud:Config:`. | `Env` | Environment or profile used in the server request | `Production` | | `ValidateCertificates` | Enable or disable server certificate validation | `true` | | `Label` | Comma-separated list of labels to request | | -| `Timeout` | Time to wait for response from server, in milliseconds. | `60_000` (1 min) | +| `Timeout` | Time to wait for response from server, in milliseconds | `60_000` (1 min) | | `PollingInterval` | How often to check for changes in Config Server | | | `Username` | Username for basic authentication | | | `Password` | Password for basic authentication | | | `FailFast` | Enable or disable failure at startup | `false` | | `Headers` | Extra HTTP headers that are added to Config Server requests | | | `Token` | HashiCorp Vault authentication token | | -| `TokenTtl` | HashiCorp Vault token renewal TTL, in milliseconds. Valid on Cloud Foundry only | `300_000` (5 min) | -| `TokenRenewRate` | HashiCorp Vault token renewal rate, in milliseconds. Valid on Cloud Foundry only | `60_000` (1 min) | -| `DisableTokenRenewal` | Enable or disable HashiCorp Vault token renewal. Valid on Cloud Foundry only | `false` | +| `TokenTtl` | HashiCorp Vault token renewal TTL, in milliseconds (used on Cloud Foundry only) | `300_000` (5 min) | +| `TokenRenewRate` | HashiCorp Vault token renewal rate, in milliseconds (used on Cloud Foundry only) | `60_000` (1 min) | +| `DisableTokenRenewal` | Enable or disable HashiCorp Vault token renewal (used on Cloud Foundry only) | `false` | | `Retry:Enabled` | Enable or disable retry logic | `false` | | `Retry:MaxAttempts` | Max retries if retry enabled | `6` | | `Retry:InitialInterval` | Starting interval, in milliseconds | `1000` | @@ -81,7 +81,7 @@ Each key must be prefixed with `Spring:Cloud:Config:`. | `Retry:Multiplier` | Retry interval multiplier | `1.1` | | `ClientId` | OAuth2 client ID when using OAuth security | | | `ClientSecret` | OAuth2 client secret when using OAuth security | | -| `AccessTokenUri` | URI to use to obtain OAuth access token. | | +| `AccessTokenUri` | URI to use to obtain OAuth access token | | | `Discovery:Enabled` | Enable or disable the Discovery First feature | `false` | | `Discovery:ServiceId` | Config Server service ID to use in Discovery First feature | `configserver` | | `Health:Enabled` | Enable or disable Config Server health check contributor | `true` | diff --git a/api/v4/configuration/decryption-provider.md b/api/v4/configuration/decryption-provider.md index 89a55b28..3c83421a 100644 --- a/api/v4/configuration/decryption-provider.md +++ b/api/v4/configuration/decryption-provider.md @@ -69,14 +69,14 @@ The following table describes the configuration settings that you can apply to t | Key | Description | Default | | --- | ----------- | ------- | -| `Encrypt:Enabled` | Enable decryption of encrypted `{cipher}` values. | `false` | -| `Encrypt:Rsa:Strong` | When set to `true`, the "strong" GCM AES algorithm is used. Otherwise, the standard CBC algorithm is used. | `false` | -| `Encrypt:Rsa:Salt` | Salt for the random secret used to encrypt cipher text. | `deadbeef` | -| `Encrypt:Rsa:Algorithm` | The RSA algorithm to use (`DEFAULT` or `OAEP`). | `DEFAULT` | -| `Encrypt:KeyStore:Location` | Location of the keystore file. Only PKCS12 store is supported. | | -| `Encrypt:KeyStore:Password` | Password that locks the keystore. | | -| `Encrypt:KeyStore:Alias` | Alias for a key in the store. | | -| `Encrypt:Key` | A symmetric key. As a stronger alternative, consider using a keystore. | | +| `Encrypt:Enabled` | Enable decryption of encrypted `{cipher}` values | `false` | +| `Encrypt:Rsa:Strong` | When set to `true`, the "strong" GCM AES algorithm is used; otherwise, the standard CBC algorithm is used | `false` | +| `Encrypt:Rsa:Salt` | Salt for the random secret used to encrypt cipher text | `deadbeef` | +| `Encrypt:Rsa:Algorithm` | The RSA algorithm to use (`DEFAULT` or `OAEP`) | `DEFAULT` | +| `Encrypt:KeyStore:Location` | Location of the keystore file (PKCS12 store is supported) | | +| `Encrypt:KeyStore:Password` | Password that locks the keystore | | +| `Encrypt:KeyStore:Alias` | Alias for a key in the store | | +| `Encrypt:Key` | A symmetric key; as a stronger alternative, consider using a keystore | | ## Custom encryption diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index b8d354de..34600d3f 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -84,7 +84,7 @@ All of these settings must start with `Eureka:Instance:`. | `NonSecurePortEnabled` | Whether the non-secure port should be enabled [^1] | computed | | `SecurePort` | Secure port on which the instance should receive traffic | computed | | `SecurePortEnabled` | Whether the secure port should be enabled [^1] | computed | -| `RegistrationMethod` | How to register on Cloud Foundry. Can be `route`, `direct`, or `hostname` [^2] | | +| `RegistrationMethod` | How to register on Cloud Foundry; can be `route`, `direct`, or `hostname` [^2] | | | `InstanceEnabledOnInit` | Whether the instance should take traffic as soon as it is registered [^3] | `true` | | `LeaseRenewalIntervalInSeconds` | How often (in seconds) the client sends heartbeats to Eureka to indicate that it is still alive | `30` | | `LeaseExpirationDurationInSeconds` | Time (in seconds) that the Eureka server waits after receiving the last heartbeat before it marks the instance as down | `90` | From 79c9a2d7dc3c2f86b39fb5e6c9a573b6243b56ef Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 3 Apr 2025 18:16:45 +0200 Subject: [PATCH 37/43] Unify JSON response line --- api/v4/discovery/netflix-eureka.md | 10 +++++----- api/v4/management/dbmigrations.md | 2 +- api/v4/management/env.md | 2 +- api/v4/management/info.md | 2 +- api/v4/management/refresh.md | 2 +- api/v4/management/services.md | 2 +- api/v4/management/threaddump.md | 2 +- api/v4/welcome/whats-new.md | 2 +- 8 files changed, 12 insertions(+), 12 deletions(-) diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 34600d3f..bc672932 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -41,7 +41,7 @@ All of these settings must start with `Eureka:Client:`. | Key | Description | Default | | --------- | ----------- | ------- | | `Enabled` | Whether to enable the Eureka client | `true` | -| `ServiceUrl` | Comma-delimited list of Eureka server endpoints | `http://localhost:8761/eureka/` | +| `ServiceUrl` | Comma-separated list of Eureka server endpoints | `http://localhost:8761/eureka/` | | `AccessTokenUri` | URL at which to obtain OAuth2 access token, before connecting to the Eureka server | | | `ClientId` | Client ID for obtaining an access token | | | `ClientSecret` | Secret for obtaining an access token | | @@ -78,8 +78,8 @@ All of these settings must start with `Eureka:Instance:`. | `IPAddress` | IP address on which the instance is registered | computed | | `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress` | `false` | | `PreferIPAddress` | Whether to register with `IPAddress` instead of `HostName` | `false` | -| `VipAddress` | Comma-delimited list of VIP addresses for the instance | computed | -| `SecureVipAddress` | Comma-delimited list of secure VIP addresses for the instance | computed | +| `VipAddress` | Comma-separated list of VIP addresses for the instance | computed | +| `SecureVipAddress` | Comma-separated list of secure VIP addresses for the instance | computed | | `Port` | Non-secure port number on which the instance should receive traffic | computed | | `NonSecurePortEnabled` | Whether the non-secure port should be enabled [^1] | computed | | `SecurePort` | Secure port on which the instance should receive traffic | computed | @@ -126,7 +126,7 @@ All of these settings must start with `Eureka:Client:`. | `ShouldFilterOnlyUpInstances` | Whether to include only instances with UP status after fetching the list of applications | `true` | | `ShouldDisableDelta` | Whether to fetch the full registry each time (`true`) or fetch only deltas (`false`) | `false` | | `RegistryRefreshSingleVipAddress` | Whether to fetch registry information only for the specified VIP address | `false` | -| `Health:MonitoredApps` | Comma-delimited list of applications in Eureka that this app depends on (see [Configuring health contributors](#configuring-health-contributors)) | | +| `Health:MonitoredApps` | Comma-separated list of applications in Eureka that this app depends on (see [Configuring health contributors](#configuring-health-contributors)) | | ## Configuring health contributors @@ -168,7 +168,7 @@ If you require more control over the health checks, consider implementing your o ## Configuring multiple Eureka servers -You can specify a comma-delimited list of Eureka server URLs that the client uses when registering or fetching +You can specify a comma-separated list of Eureka server URLs that the client uses when registering or fetching the service registry. These servers should be part of a properly configured Eureka server cluster, and should be using peer-to-peer communications to keep in sync. diff --git a/api/v4/management/dbmigrations.md b/api/v4/management/dbmigrations.md index 0731d82a..87e2e478 100644 --- a/api/v4/management/dbmigrations.md +++ b/api/v4/management/dbmigrations.md @@ -44,7 +44,7 @@ builder.Services.AddDbMigrationsActuator(); This endpoint returns a list of objects representing each registered `DbContext` along with its migrations, grouped by status (pending or applied). -The response is always returned as JSON, as shown here: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/env.md b/api/v4/management/env.md index f9fa3852..b444e359 100644 --- a/api/v4/management/env.md +++ b/api/v4/management/env.md @@ -44,7 +44,7 @@ builder.Services.AddEnvironmentActuator(); This endpoint returns a list of objects representing information from `IConfiguration`. -The response is always returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/info.md b/api/v4/management/info.md index b4ab63af..06d9898f 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -76,7 +76,7 @@ This contributor exposes information from the `git.properties` Spring Boot file. ## Sample Output -Depending on the registered contributors, this endpoint returns JSON similar to this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/refresh.md b/api/v4/management/refresh.md index d3f1ecb7..bff815d7 100644 --- a/api/v4/management/refresh.md +++ b/api/v4/management/refresh.md @@ -47,7 +47,7 @@ builder.Services.AddRefreshActuator(); This endpoint returns an array of keys obtained from `IConfiguration`. -The response always returns as JSON: +The response is always returned as JSON: ```json [ diff --git a/api/v4/management/services.md b/api/v4/management/services.md index 86c6c38f..0331e86c 100644 --- a/api/v4/management/services.md +++ b/api/v4/management/services.md @@ -44,7 +44,7 @@ builder.Services.AddServicesActuator(); This endpoint returns the contents of `IServiceCollection`. -The response is always returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/threaddump.md b/api/v4/management/threaddump.md index 6037fd12..201e3965 100644 --- a/api/v4/management/threaddump.md +++ b/api/v4/management/threaddump.md @@ -44,7 +44,7 @@ builder.Services.AddThreadDumpActuator(); This endpoint returns a list of threads with their state and stack trace. -The response always returned as JSON: +The response is always returned as JSON: ```json { diff --git a/api/v4/welcome/whats-new.md b/api/v4/welcome/whats-new.md index 43dbc443..8b2aa294 100644 --- a/api/v4/welcome/whats-new.md +++ b/api/v4/welcome/whats-new.md @@ -789,7 +789,7 @@ For more information, see the updated [Connectors documentation](../configuratio | `Steeltoe.Discovery.Eureka.EurekaClientConfig` | Type | Steeltoe.Discovery.Eureka | Removed | `Steeltoe.Discovery.Eureka.Configuration.EurekaClientOptions` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerConnectTimeoutSeconds` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.ConnectTimeoutSeconds` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerRetryCount` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.RetryCount` | Default changed from 3 attempts to 2 retries (bug fix) | -| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerServiceUrls` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.EurekaServerServiceUrls` | Now supports comma-delimited list of URLs | +| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerServiceUrls` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.EurekaServerServiceUrls` | Now supports comma-separated list of URLs | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthCheckEnabled` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.CheckEnabled` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthContribEnabled` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.ContributorEnabled` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthMonitoredApps` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.MonitoredApps` | | From d461ee42b64382a6602bfa0cf9bdee4330415781 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 3 Apr 2025 18:18:37 +0200 Subject: [PATCH 38/43] Convert headings to bullets --- api/v4/management/springbootadmin.md | 114 +++++++++++++-------------- 1 file changed, 54 insertions(+), 60 deletions(-) diff --git a/api/v4/management/springbootadmin.md b/api/v4/management/springbootadmin.md index b8de89df..84fc6289 100644 --- a/api/v4/management/springbootadmin.md +++ b/api/v4/management/springbootadmin.md @@ -64,82 +64,76 @@ a few additional steps are needed: Putting it all together, your config files contain the contents shown in the following: -### appsettings.Development.json - -In `appsettings.Development.json`: - -```json -{ - "Spring": { - "Application": { - "Name": "ExampleSteeltoeApp" - }, - "Boot": { - "Admin": { - "Client": { - // This is the URL of the Spring Boot Admin Server. - "Url": "http://localhost:9099", - // This is what the Spring Boot Admin Server uses to connect to your app. - "BasePath": "http://host.docker.internal:5258" +- In `appsettings.Development.json`: + + ```json + { + "Spring": { + "Application": { + "Name": "ExampleSteeltoeApp" + }, + "Boot": { + "Admin": { + "Client": { + // This is the URL of the Spring Boot Admin Server. + "Url": "http://localhost:9099", + // This is what the Spring Boot Admin Server uses to connect to your app. + "BasePath": "http://host.docker.internal:5258" + } + } } } } - } -} -``` - -### launchsettings.json - -In `launchsettings.json`: - -```json -{ - "$schema": "http://json.schemastore.org/launchsettings.json", - "profiles": { - "http": { - "commandName": "Project", - "dotnetRunMessages": true, - // Listen on all network interfaces by using a wildcard for the hostname. - "applicationUrl": "http://*:5258", - "environmentVariables": { - "ASPNETCORE_ENVIRONMENT": "Development" + ``` + +- In `launchsettings.json`: + + ```json + { + "$schema": "http://json.schemastore.org/launchsettings.json", + "profiles": { + "http": { + "commandName": "Project", + "dotnetRunMessages": true, + // Listen on all network interfaces by using a wildcard for the hostname. + "applicationUrl": "http://*:5258", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development" + } + } } } - } -} -``` - -> [!NOTE] -> If you want your app to listen on a different port number, replace `5258` in both files above with the desired port. + ``` -### Program.cs + > [!NOTE] + > If you want your app to listen on a different port number, replace `5258` in both files above with the desired port. -And the following code in `Program.cs`: +- In `Program.cs`: -```csharp -using Steeltoe.Management.Endpoint.Actuators.Health; -using Steeltoe.Management.Endpoint.Actuators.Hypermedia; -using Steeltoe.Management.Endpoint.SpringBootAdminClient; + ```csharp + using Steeltoe.Management.Endpoint.Actuators.Health; + using Steeltoe.Management.Endpoint.Actuators.Hypermedia; + using Steeltoe.Management.Endpoint.SpringBootAdminClient; -var builder = WebApplication.CreateBuilder(args); + var builder = WebApplication.CreateBuilder(args); -// Add services to the container. + // Add services to the container. -builder.Services.AddSpringBootAdminClient(); -builder.Services.AddHypermediaActuator(); -builder.Services.AddHealthActuator(); + builder.Services.AddSpringBootAdminClient(); + builder.Services.AddHypermediaActuator(); + builder.Services.AddHealthActuator(); -builder.Services.AddControllers(); + builder.Services.AddControllers(); -var app = builder.Build(); + var app = builder.Build(); -// To avoid trust issues with self-signed certificates, do not automatically redirect to https. -//app.UseHttpsRedirection(); + // To avoid trust issues with self-signed certificates, do not automatically redirect to https. + //app.UseHttpsRedirection(); -app.MapControllers(); + app.MapControllers(); -app.Run(); -``` + app.Run(); + ``` > [!TIP] > To see all the Spring Boot Admin features in action, replace the `Add*Actuator()` calls in `Program.cs` with `AddAllActuators()` and expose all endpoints. See [Exposing endpoints](./using-endpoints.md#exposing-endpoints). From 931064918440d5e7966a53b860209744cb1a0c99 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 3 Apr 2025 18:07:51 +0200 Subject: [PATCH 39/43] Do not use mention --- api/v4/connectors/mongodb.md | 2 +- api/v4/connectors/mysql.md | 2 +- api/v4/connectors/postgresql.md | 2 +- api/v4/connectors/rabbitmq.md | 2 +- api/v4/connectors/redis.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index cc2a8637..db9bcb59 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -27,7 +27,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would The available connection string parameters for MongoDB are described in the [MongoDB documentation](https://www.mongodb.com/docs/manual/reference/connection-string/). -The following example `appsettings.json` uses the docker container mentioned earlier: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index 5e937839..799bc119 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -35,7 +35,7 @@ For the available connection string parameters for MySQL, see: * [MySQL Connector documentation](https://mysqlconnector.net/connection-options/) * [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connection-parameters-base) -The following example `appsettings.json` uses the docker container from the earlier example: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index dd0e0a52..bf44bddd 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -29,7 +29,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would The available connection string parameters for PostgreSQL are described in the [Npgsql documentation](https://www.npgsql.org/doc/connection-string-parameters.html). -The following example `appsettings.json` uses the docker container from the previous example: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index 6d83748e..a55db147 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -27,7 +27,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would The available connection string parameters for RabbitMQ are described in the [RabbitMQ documentation](https://www.rabbitmq.com/uri-spec.html). -The following example `appsettings.json` uses the docker container from earlier: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index ac822149..7bbd7793 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -29,7 +29,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would The available connection string parameters for Redis are described in [StackExchange.Redis](https://stackexchange.github.io/StackExchange.Redis/Configuration.html). -The following example `appsettings.json` uses the docker container used earlier: +The following example `appsettings.json` uses the Redis docker container referred to earlier: ```json { From 26f14eb40338126e6f912759aa306cfcc2da61cd Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 3 Apr 2025 17:54:21 +0200 Subject: [PATCH 40/43] Fix comma --- api/v4/configuration/config-server-provider.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index f71a269d..ec1d96ac 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -218,7 +218,7 @@ However, with the default "Config First" mode of the Steeltoe client, you cannot 1. If your application does not use a service discovery service, you need to configure your application to do so. See the [Steeltoe Discovery documentation](../discovery/initialize-discovery-client.md) for instructions. At a minimum, you must configure the Eureka Server address. 1. Change the Steeltoe Config Server client setting `Spring:Cloud:Config:Discovery:Enabled` to `true` (the default is `false`). -1. If your Config Server is registered with Eureka using a name other than "configserver," use `Spring:Cloud:Config:Discovery:ServiceId` to specify the name used by the client for lookup. +1. If your Config Server is registered with Eureka using a name other than `configserver`, use `Spring:Cloud:Config:Discovery:ServiceId` to specify the name used by the client for lookup. Note that the cost for using this mode of operation is an extra network roundtrip on startup to locate the Config Server service registration. The benefit is that, as long as the discovery service is at a fixed point, the Config Server can change its address and no changes to applications are needed. From 442373026f8af6235c470ebe046567abb91bbef7 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 3 Apr 2025 18:16:08 +0200 Subject: [PATCH 41/43] Various --- api/v4/discovery/initialize-discovery-client.md | 4 ++-- api/v4/discovery/netflix-eureka.md | 4 ++-- api/v4/tracing/index.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api/v4/discovery/initialize-discovery-client.md b/api/v4/discovery/initialize-discovery-client.md index 2224914f..beecf2a9 100644 --- a/api/v4/discovery/initialize-discovery-client.md +++ b/api/v4/discovery/initialize-discovery-client.md @@ -38,8 +38,8 @@ var app = builder.Build(); ``` > [!TIP] -> Alternatively, you can use `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration), which uses reflection to determine -> which discovery assemblies are loaded, and adding the appropriate clients automatically. +> Alternatively, you can use `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration), +> which uses reflection to determine which discovery assemblies are loaded and adds the appropriate clients automatically. ## Client configuration diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index bc672932..4c3cef27 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -122,7 +122,7 @@ All of these settings must start with `Eureka:Client:`. | Key | Description | Default | | --- | ----------- | ------- | | `ShouldFetchRegistry` | Whether to periodically fetch registry information from the Eureka server | `true` | -| `RegistryFetchIntervalSeconds` | How often (in seconds) to fetch registry information from the Eureka server | every `30` seconds | +| `RegistryFetchIntervalSeconds` | How often (in seconds) to fetch registry information from the Eureka server | `30` | | `ShouldFilterOnlyUpInstances` | Whether to include only instances with UP status after fetching the list of applications | `true` | | `ShouldDisableDelta` | Whether to fetch the full registry each time (`true`) or fetch only deltas (`false`) | `false` | | `RegistryRefreshSingleVipAddress` | Whether to fetch registry information only for the specified VIP address | `false` | @@ -162,7 +162,7 @@ as calculated from the ASP.NET health checks and active health contributors, to Consequently, after successful registration, Eureka always announces that the application is in 'UP' state. You can alter this behavior by enabling `Eureka:Client:Health:CheckEnabled` (`false` by default), which results in propagating health status to Eureka. -Note that other applications don't send traffic to your app unless the health checks and contributors report the status as 'UP'. +As a result, other applications stop sending traffic to your app until the health checks and contributors report the status as 'UP'. If you require more control over the health checks, consider implementing your own `IHealthCheckHandler`. diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index 69a1fbc1..f8945356 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -38,7 +38,7 @@ dbug: Microsoft.EntityFrameworkCore.Database.Command[20104] [ActuatorApi,44ed2fe24a051bda2d1a56815448e9fb,c32846ff227bed40,f315823f4c554816,true] Created DbCommand for 'ExecuteReader' (1ms). ``` -Log correlation is easiest with a tool such as [Splunk](https://www.splunk.com/en_us/solutions/isolate-cloud-native-problems.html), [SumoLogic](https://www.sumologic.com/lp/log-analytics/), or [DataDog](https://www.datadoghq.com/dg/enterprise/log-management-analytics-security). (This is not an endorsement of any tool, only a pointer to some popular options). +Log correlation is easiest with a tool such as [Splunk](https://www.splunk.com/en_us/solutions/isolate-cloud-native-problems.html), [SumoLogic](https://www.sumologic.com/lp/log-analytics/), or [DataDog](https://www.datadoghq.com/dg/enterprise/log-management-analytics-security). (This is not an endorsement of any tool, only a pointer to some popular options.) ### Using TracingLogProcessor From f07d30fc1e3e0208362b84b62fdc77518ec4d008 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 4 Apr 2025 11:25:49 +0200 Subject: [PATCH 42/43] Update api/v4/connectors/redis.md Co-authored-by: Tim Hess --- api/v4/connectors/redis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index 7bbd7793..651ca37d 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -29,7 +29,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would The available connection string parameters for Redis are described in [StackExchange.Redis](https://stackexchange.github.io/StackExchange.Redis/Configuration.html). -The following example `appsettings.json` uses the Redis docker container referred to earlier: +The following example `appsettings.json` works with either docker container referred to earlier: ```json { From 6e43d7686097d07ead53c784facf619c6eb78f0f Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 4 Apr 2025 13:36:11 +0200 Subject: [PATCH 43/43] Final pass over all changes --- api/v4/configuration/cloud-foundry-provider.md | 2 +- api/v4/configuration/config-server-provider.md | 4 ++-- api/v4/configuration/placeholder-provider.md | 1 - api/v4/connectors/mysql.md | 5 ++--- api/v4/connectors/postgresql.md | 4 ++-- api/v4/connectors/rabbitmq.md | 2 +- api/v4/discovery/netflix-eureka.md | 8 ++++---- api/v4/initializr/index.md | 2 +- api/v4/initializr/initializr-web.md | 15 +++++++-------- api/v4/management/dbmigrations.md | 2 +- api/v4/management/health.md | 7 ++++--- api/v4/management/info.md | 2 +- api/v4/management/springbootadmin.md | 4 ++-- api/v4/management/using-endpoints.md | 2 +- api/v4/security/redis-key-storage-provider.md | 2 +- 15 files changed, 30 insertions(+), 32 deletions(-) diff --git a/api/v4/configuration/cloud-foundry-provider.md b/api/v4/configuration/cloud-foundry-provider.md index 3e2be65c..d6c3e2e2 100644 --- a/api/v4/configuration/cloud-foundry-provider.md +++ b/api/v4/configuration/cloud-foundry-provider.md @@ -1,6 +1,6 @@ # Cloud Foundry Provider -The Cloud Foundry provider enables the standard Cloud Foundry environment variables (`VCAP_APPLICATION`, `VCAP_SERVICES`, and `CF_*`) to be parsed and accessed as configuration data within a .NET application. +The Cloud Foundry provider enables the standard Cloud Foundry environment variables (`VCAP_APPLICATION`, `VCAP_SERVICES`, and `CF_*`) to be parsed and accessed as configuration data within a .NET application. Cloud Foundry creates and uses these environment variables to communicate an application's environment and configuration to the application code running inside a container. More specifically, the values found in `VCAP_APPLICATION` provide information about the application's resource limits, routes (URIs), and version numbers, among other things. The `VCAP_SERVICES` environment variable provides information about the external services (databases, caches, and so on) to which the application is bound, along with details for contacting those services. diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index ec1d96ac..a19888be 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -32,7 +32,7 @@ The most convenient way to configure settings for the provider is to put them in The following example shows some provider settings that have been put in a JSON file. Only two settings are required: -* `Spring:Application:Name` configures the "application name" to be `sample`. +* `Spring:Application:Name` configures the application name to be `sample`. * `Spring:Cloud:Config:Uri` configures the address of the Config Server. > [!TIP] @@ -168,7 +168,7 @@ string? property1 = configuration["example:property1"]; string? property2 = configuration["example:property2"]; ``` -Alternatively, you can create a class to hold your configuration data and then use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) along with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to get an instance of your options class into your controllers and views. +Alternatively, you can create a class to hold your configuration data and then use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to get an instance of your options class into your controllers and views. 1. First create a class representing the configuration data you expect to retrieve from the server, as follows: diff --git a/api/v4/configuration/placeholder-provider.md b/api/v4/configuration/placeholder-provider.md index 9a7ee9ac..2c07a03c 100644 --- a/api/v4/configuration/placeholder-provider.md +++ b/api/v4/configuration/placeholder-provider.md @@ -53,7 +53,6 @@ Consider the following `appsettings.json` file: } } } - ... } ``` diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index 799bc119..169e274e 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -23,8 +23,7 @@ To use this connector: ### Add NuGet References To use this connector, add a NuGet reference to `Steeltoe.Connectors`. -If you're using Entity Framework Core, add a -NuGet reference to `Steeltoe.Connectors.EntityFrameworkCore` instead. +If you're using Entity Framework Core, add a NuGet reference to `Steeltoe.Connectors.EntityFrameworkCore` instead. Also add a NuGet reference to one of the .NET drivers listed above, as you would if you were not using Steeltoe. @@ -157,7 +156,7 @@ This Connector supports the following service brokers: - [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-9/csb-azure/index.html) - [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) -You can create and bind an instance to your application using the Cloud Foundry CLI: +You can create and bind an instance to your application by using the Cloud Foundry CLI: ```shell # Create MySQL service diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index bf44bddd..f308e39c 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -3,8 +3,8 @@ This connector simplifies accessing [PostgreSQL](https://www.postgresql.org/) databases. It supports the following .NET drivers: -- [Npgsql](https://www.nuget.org/packages/Npgsql), which provides an ADO.NET `DbConnection`. -- [Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. +- [Npgsql](https://www.nuget.org/packages/Npgsql), which provides an ADO.NET `DbConnection` +- [Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index a55db147..caca3a49 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -91,7 +91,7 @@ This Connector supports the following service brokers: - [VMware Tanzu RabbitMQ on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-rabbitmq-on-cloud-foundry/10-0/tanzu-rabbitmq-cloud-foundry/index.html) -You can create and bind an instance to your application using the Cloud Foundry CLI: +You can create and bind an instance to your application by using the Cloud Foundry CLI: ```shell # Create RabbitMQ service diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 4c3cef27..fd7439cf 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -102,7 +102,7 @@ All of these settings must start with `Eureka:Instance:`. [^2]: Specify `direct` to use container-to-container networking on Cloud Foundry. Specify `hostname` to force using `HostName`. -[^3]: When set to `false`, call `EurekaApplicationInfoManager.UpdateInstance()` after initialization to mark the instance as up. +[^3]: When set to `false`, call `EurekaApplicationInfoManager.UpdateInstance()` after initialization to mark the instance as `UP`. [^4]: Add a NuGet package reference to `Steeltoe.Management.Endpoint` to use its `health` and `info` actuator paths. @@ -123,7 +123,7 @@ All of these settings must start with `Eureka:Client:`. | --- | ----------- | ------- | | `ShouldFetchRegistry` | Whether to periodically fetch registry information from the Eureka server | `true` | | `RegistryFetchIntervalSeconds` | How often (in seconds) to fetch registry information from the Eureka server | `30` | -| `ShouldFilterOnlyUpInstances` | Whether to include only instances with UP status after fetching the list of applications | `true` | +| `ShouldFilterOnlyUpInstances` | Whether to include only instances with `UP` status after fetching the list of applications | `true` | | `ShouldDisableDelta` | Whether to fetch the full registry each time (`true`) or fetch only deltas (`false`) | `false` | | `RegistryRefreshSingleVipAddress` | Whether to fetch registry information only for the specified VIP address | `false` | | `Health:MonitoredApps` | Comma-separated list of applications in Eureka that this app depends on (see [Configuring health contributors](#configuring-health-contributors)) | | @@ -159,10 +159,10 @@ periodic heartbeats to inform the Eureka server that the currently running app i Unless specified otherwise, the client does not propagate the current health status of the application, as calculated from the ASP.NET health checks and active health contributors, to Eureka. -Consequently, after successful registration, Eureka always announces that the application is in 'UP' state. +Consequently, after successful registration, Eureka always announces that the application is in `UP` state. You can alter this behavior by enabling `Eureka:Client:Health:CheckEnabled` (`false` by default), which results in propagating health status to Eureka. -As a result, other applications stop sending traffic to your app until the health checks and contributors report the status as 'UP'. +As a result, other applications stop sending traffic to your app until the health checks and contributors report the status as `UP`. If you require more control over the health checks, consider implementing your own `IHealthCheckHandler`. diff --git a/api/v4/initializr/index.md b/api/v4/initializr/index.md index f22a27ae..acacf910 100644 --- a/api/v4/initializr/index.md +++ b/api/v4/initializr/index.md @@ -13,4 +13,4 @@ A more user-friendly deployment might include a user interface, such as a web fr A deployment may also use a [Spring Cloud Config Server](https://cloud.spring.io/spring-cloud-config/multi/multi__spring_cloud_config_server.html) to access a configuration store. As an example, the [Steeltoe Initializr deployment](https://start.steeltoe.io) includes [InitializrWeb](https://github.com/SteeltoeOSS/InitializrWeb) for a friendly user experience and a Spring Cloud Config Server using a GitHub-maintained configuration. -InitializrWeb is the reference UI for the Steeltoe Initializr and is an example of a smart client. It uses project metadata from the InitializrService to populate its web controls with, for example, supported .NET target frameworks and Steeltoe versions. +InitializrWeb is the reference UI for the Steeltoe Initializr and is an example of a smart client. It uses project metadata from the InitializrService to populate its web controls with, for example, supported .NET target frameworks and Steeltoe versions. diff --git a/api/v4/initializr/initializr-web.md b/api/v4/initializr/initializr-web.md index ee476827..264db5c8 100644 --- a/api/v4/initializr/initializr-web.md +++ b/api/v4/initializr/initializr-web.md @@ -12,7 +12,7 @@ The interface is made up of four areas: * project configuration area * project action area (bottom) -* UI configuration (right) +* Dependencies configuration (right) * external links (left) The remainder of this document focuses on the project configuration and action areas. @@ -21,21 +21,20 @@ The remainder of this document focuses on the project configuration and action a The configuration area exposes five project properties to the end user: -* **Name** -* **Namespace**: C# namespace -* **Application**: application name -* **Description** +* **Name**: application name +* **Namespace**: code namespace +* **Description**: application description * **Steeltoe**: Steeltoe version * **.NET Framework**: .NET target framework -* **.NET template** -* **Dependencies** +* **Language**: The programming language ## Project actions -The actions area provides three project actions to the end user: +The actions area provides four project actions to the end user: * **Generate** * **Explore** +* **Bookmark** * **Share** ### Generate diff --git a/api/v4/management/dbmigrations.md b/api/v4/management/dbmigrations.md index 87e2e478..875bbe2a 100644 --- a/api/v4/management/dbmigrations.md +++ b/api/v4/management/dbmigrations.md @@ -42,7 +42,7 @@ builder.Services.AddDbMigrationsActuator(); ## Sample Output -This endpoint returns a list of objects representing each registered `DbContext` along with its migrations, grouped by status (pending or applied). +This endpoint returns a list of objects representing each registered `DbContext`, along with its migrations, grouped by status (pending or applied). The response is always returned as JSON: diff --git a/api/v4/management/health.md b/api/v4/management/health.md index 99993832..cd9dbe47 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -11,7 +11,7 @@ In addition, you can write your own. By default, the final application health state is computed by the registered `IHealthAggregator` implementation. It is responsible for sorting out all of the returned statuses from each `IHealthContributor` and [`IHealthCheck`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.diagnostics.healthchecks.ihealthcheck) and deriving an overall application health state. -The built-in aggregator returns the "worst" status returned from the contributors and checks. +The built-in aggregator returns the *worst* status returned from the contributors and checks. ## Configure Settings @@ -208,8 +208,9 @@ Support is provided, out of the box, for Liveness and Readiness, where each is e While these health contributors are included, they are disabled by default and must be enabled in the configuration (as shown in the example below). To change the health contributors that are included in either of the two built-in groups, use the same style of configuration described above. -Note that this _replaces_ these groupings, so if you want to _add_ an `IHealthContributor`, you must include the original entry. -These entries demonstrate enabling the probes and their groups, and specifies including disk space in both groups: +Note that this _replaces_ the default groupings, so if you want to _add_ an `IHealthContributor`, you must include the original entry. + +The following example enables both contributors and their groups, and specifies to include disk space in both groups: ```json { diff --git a/api/v4/management/info.md b/api/v4/management/info.md index 06d9898f..70ee9269 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -69,7 +69,7 @@ This contributor exposes any values below the `Info` configuration key. For exam ### Git properties -This contributor exposes information from the `git.properties` Spring Boot file. If available, the file contains information from git, such as branch/tag name, commit hash, and remote. +This contributor exposes information from the `git.properties` Spring Boot file, if available. The file contains information from git, such as branch/tag name, commit hash, and remote. > [!TIP] > For an example of how to use this contributor within MSBuild using [GitInfo](https://github.com/devlooped/GitInfo), see the [Steeltoe Management sample](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src). diff --git a/api/v4/management/springbootadmin.md b/api/v4/management/springbootadmin.md index 84fc6289..4d0c61f3 100644 --- a/api/v4/management/springbootadmin.md +++ b/api/v4/management/springbootadmin.md @@ -26,7 +26,7 @@ Each key must be prefixed with `Spring:Boot:Admin:Client:`. | ----- | ----------- | ------- | | `Url` | The URL of the Spring Boot Admin server | | | `ApplicationName` | The name of the Steeltoe app being registered | computed | -| `BasePath` | The base path to find endpoints for integration | computed | +| `BasePath` | The base URL to find endpoints for integration | computed | | `ValidateCertificates` | Whether server certificates should be validated | `true` | | `ConnectionTimeoutMS` | Connection timeout (in milliseconds) | `100_000` | | `Metadata` | Dictionary of metadata to use when registering | | @@ -57,7 +57,7 @@ a few additional steps are needed: - Register additional actuator endpoints - For the server to report the app as "UP", you must add at least the hypermedia and health actuators in `Program.cs`. + For the server to report the app as `UP`, you must add at least the hypermedia and health actuators in `Program.cs`. > [!TIP] > For testing, you can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin). diff --git a/api/v4/management/using-endpoints.md b/api/v4/management/using-endpoints.md index 653c25c2..0f17f9ff 100644 --- a/api/v4/management/using-endpoints.md +++ b/api/v4/management/using-endpoints.md @@ -75,7 +75,7 @@ The following table describes the configuration settings that are common to all ### Custom JSON Serialization Options -The `JsonSerializerOptions` used to serialize actuator responses are configurable, and custom `JsonConverter`s can be used by adding the [assembly-qualified type](https://learn.microsoft.com/dotnet/api/system.type.assemblyqualifiedname"). +The `JsonSerializerOptions` used to serialize actuator responses are configurable, and custom `JsonConverter`s can be used by adding the [assembly-qualified type](https://learn.microsoft.com/dotnet/api/system.type.assemblyqualifiedname). For example, to pretty-print all JSON, and serialize `DateTime` values as epoch times: diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index d32b1bd2..05bbae74 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -67,7 +67,7 @@ There are several steps required to configure key storage in Redis: - Set the key persistence location to Redis. - Set an application name so all instances of the application can see the same data. -These steps can be performed by chaining the method calls together: +These steps can be performed by chaining the method calls: ```csharp using Microsoft.AspNetCore.DataProtection;