From 91c12c9ef91bd8bb883e9cb49c52ad8fc235f5cf Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Fri, 24 Apr 2026 16:28:57 +0200 Subject: [PATCH 1/6] Update extensibility docs for connectors --- docs/docs/v4/connectors/extensibility.md | 89 +++++++++++++++++++++++- 1 file changed, 86 insertions(+), 3 deletions(-) diff --git a/docs/docs/v4/connectors/extensibility.md b/docs/docs/v4/connectors/extensibility.md index 7e8cc99c..3e10bad7 100644 --- a/docs/docs/v4/connectors/extensibility.md +++ b/docs/docs/v4/connectors/extensibility.md @@ -1,6 +1,89 @@ # Extensibility -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). +Steeltoe Connectors cover a fixed set of supported data stores and messaging systems (PostgreSQL, MySQL, SQL Server, MongoDB, Cosmos DB, RabbitMQ, and Redis/Valkey). +They are not open-ended plug-ins; extensibility means shaping platform credentials into the connection strings external drivers for those built-in connectors already understand. + +Connectors map Cloud Foundry credentials into configuration keys starting with `steeltoe:service-bindings` and merge them with local settings from `Steeltoe:Client`. +Each connector runs the binding logic for its own service type. + +To use a third-party `VCAP_SERVICES` structure, populate the `steeltoe:service-bindings` keys yourself. +It is recommended to turn off the built-in binding logic to prevent conflicts by setting `SkipDefaultServiceBindings` to `true`. +Doing so will still merge with local settings from `Steeltoe:Client`. + +> [!TIP] +> See the [Cloud Foundry configuration provider](../configuration/cloud-foundry-provider.md) for `vcap:*` keys and [`VCAP_SERVICES`](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) in general. + +For example, to use a third-party Cloud Foundry service broker for PostgreSQL that sets the `VCAP_SERVICES` environment variable to: + +```json +{ + "custom-postgres-broker": [ + { + "name": "products-db", + "credentials": { + "custom-hostname-key": "example.cloud.com", + "custom-port-key": 2345, + "custom-username-key": "products-user", + "custom-password-key": "products-secret", + "custom-database-name-key": "product-database" + } + }, + { + "name": "orders-db", + "credentials": { + "custom-hostname-key": "example.cloud.com", + "custom-port-key": 2345, + "custom-username-key": "orders-user", + "custom-password-key": "orders-secret", + "custom-database-name-key": "order-database" + } + } + ] +} +``` + +The following code can be used to map the PostgreSQL credentials to the format that [`NpgsqlConnectionStringBuilder`](https://www.npgsql.org/doc/api/Npgsql.NpgsqlConnectionStringBuilder.html) expects: + +```c# +using Npgsql; +using Steeltoe.Configuration.CloudFoundry; +using Steeltoe.Connectors; +using Steeltoe.Connectors.PostgreSql; + +var builder = WebApplication.CreateBuilder(); +builder.AddCloudFoundryConfiguration(); +MapCustomServiceBindings("custom-postgres-broker"); +builder.AddPostgreSql(configure => configure.SkipDefaultServiceBindings = true, null); +var app = builder.Build(); + +var factory = app.Services.GetRequiredService>(); + +PostgreSqlOptions productsDbOptions = factory.Get("products-db").Options; +Console.WriteLine(productsDbOptions.ConnectionString); +// Database=product-database;Host=example.cloud.com;Password=products-secret;Port=2345;Username=products-user + +PostgreSqlOptions ordersDbOptions = factory.Get("orders-db").Options; +Console.WriteLine(ordersDbOptions.ConnectionString); +// Database=order-database;Host=example.cloud.com;Password=orders-secret;Port=2345;Username=orders-user + +void MapCustomServiceBindings(string brokerName) +{ + var options = builder.Configuration.GetSection("vcap").Get(); + + foreach (CloudFoundryService service in options?.Services + .Where(pair => pair.Key == brokerName) + .SelectMany(pair => pair.Value) ?? []) + { + builder.Configuration.AddInMemoryCollection(new Dictionary + { + // Map credentials into the property names expected by NpgsqlConnectionStringBuilder. + [$"steeltoe:service-bindings:postgresql:{service.Name}:host"] = service.Credentials["custom-hostname-key"].Value, + [$"steeltoe:service-bindings:postgresql:{service.Name}:port"] = service.Credentials["custom-port-key"].Value, + [$"steeltoe:service-bindings:postgresql:{service.Name}:username"] = service.Credentials["custom-username-key"].Value, + [$"steeltoe:service-bindings:postgresql:{service.Name}:password"] = service.Credentials["custom-password-key"].Value, + [$"steeltoe:service-bindings:postgresql:{service.Name}:database"] = service.Credentials["custom-database-name-key"].Value + }); + } +} +``` -See [Advanced settings](usage.md#advanced-settings) to customize the built-in Connectors. From 5ff747fafeba3b9435d9204c20e1d7a299503b8e Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Wed, 6 May 2026 11:20:27 +0200 Subject: [PATCH 2/6] Review feedback --- docs/docs/v4/connectors/extensibility.md | 5 ++++- docs/docs/v4/connectors/usage.md | 3 +++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/docs/v4/connectors/extensibility.md b/docs/docs/v4/connectors/extensibility.md index 3e10bad7..5b0f5e9c 100644 --- a/docs/docs/v4/connectors/extensibility.md +++ b/docs/docs/v4/connectors/extensibility.md @@ -3,7 +3,8 @@ Steeltoe Connectors cover a fixed set of supported data stores and messaging systems (PostgreSQL, MySQL, SQL Server, MongoDB, Cosmos DB, RabbitMQ, and Redis/Valkey). They are not open-ended plug-ins; extensibility means shaping platform credentials into the connection strings external drivers for those built-in connectors already understand. -Connectors map Cloud Foundry credentials into configuration keys starting with `steeltoe:service-bindings` and merge them with local settings from `Steeltoe:Client`. +Connectors map credentials from [Cloud Foundry service bindings](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/elastic-application-runtime/10-3/eart/binding-credentials.html) and +[Service Binding Spec for Kubernetes](https://github.com/servicebinding/spec#well-known-secret-entries) into configuration keys starting with `steeltoe:service-bindings` and merge them with local settings from `Steeltoe:Client`. Each connector runs the binding logic for its own service type. To use a third-party `VCAP_SERVICES` structure, populate the `steeltoe:service-bindings` keys yourself. @@ -87,3 +88,5 @@ void MapCustomServiceBindings(string brokerName) } ``` +> [!TIP] +> See [Advanced settings](usage.md#advanced-settings) to customize the built-in Connectors. diff --git a/docs/docs/v4/connectors/usage.md b/docs/docs/v4/connectors/usage.md index 3106b058..414151f5 100644 --- a/docs/docs/v4/connectors/usage.md +++ b/docs/docs/v4/connectors/usage.md @@ -347,3 +347,6 @@ builder.Services.AddDbContext((serviceProvider, options) => sqlServerOptions.EnableRetryOnFailure(); })); ``` + +> [!TIP] +> See [Extensibility](extensibility.md) to use third-party service brokers. From 665d7e4cd411477594b71c61812225840dc0aed3 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Wed, 6 May 2026 11:27:17 +0200 Subject: [PATCH 3/6] Fix spelling --- docs/docs/v4/connectors/extensibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/v4/connectors/extensibility.md b/docs/docs/v4/connectors/extensibility.md index 5b0f5e9c..76b283a0 100644 --- a/docs/docs/v4/connectors/extensibility.md +++ b/docs/docs/v4/connectors/extensibility.md @@ -4,7 +4,7 @@ Steeltoe Connectors cover a fixed set of supported data stores and messaging sys They are not open-ended plug-ins; extensibility means shaping platform credentials into the connection strings external drivers for those built-in connectors already understand. Connectors map credentials from [Cloud Foundry service bindings](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/elastic-application-runtime/10-3/eart/binding-credentials.html) and -[Service Binding Spec for Kubernetes](https://github.com/servicebinding/spec#well-known-secret-entries) into configuration keys starting with `steeltoe:service-bindings` and merge them with local settings from `Steeltoe:Client`. +[Service Binding Spec for Kubernetes](https://github.com/servicebinding/spec#well-known-secret-entries) into configuration keys starting with `steeltoe:service-bindings` and merges them with local settings from `Steeltoe:Client`. Each connector runs the binding logic for its own service type. To use a third-party `VCAP_SERVICES` structure, populate the `steeltoe:service-bindings` keys yourself. From 2c6cfa9ae1fc8c0754b37a87e30d5005b8e85439 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 7 May 2026 12:04:24 +0200 Subject: [PATCH 4/6] Revert "Fix spelling" This reverts commit 665d7e4cd411477594b71c61812225840dc0aed3. --- docs/docs/v4/connectors/extensibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/v4/connectors/extensibility.md b/docs/docs/v4/connectors/extensibility.md index 76b283a0..5b0f5e9c 100644 --- a/docs/docs/v4/connectors/extensibility.md +++ b/docs/docs/v4/connectors/extensibility.md @@ -4,7 +4,7 @@ Steeltoe Connectors cover a fixed set of supported data stores and messaging sys They are not open-ended plug-ins; extensibility means shaping platform credentials into the connection strings external drivers for those built-in connectors already understand. Connectors map credentials from [Cloud Foundry service bindings](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/elastic-application-runtime/10-3/eart/binding-credentials.html) and -[Service Binding Spec for Kubernetes](https://github.com/servicebinding/spec#well-known-secret-entries) into configuration keys starting with `steeltoe:service-bindings` and merges them with local settings from `Steeltoe:Client`. +[Service Binding Spec for Kubernetes](https://github.com/servicebinding/spec#well-known-secret-entries) into configuration keys starting with `steeltoe:service-bindings` and merge them with local settings from `Steeltoe:Client`. Each connector runs the binding logic for its own service type. To use a third-party `VCAP_SERVICES` structure, populate the `steeltoe:service-bindings` keys yourself. From ce1ba2801ff799e7590667d4ed702b337f698d2e Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 7 May 2026 12:06:55 +0200 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Tim Hess --- docs/docs/v4/connectors/extensibility.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/docs/v4/connectors/extensibility.md b/docs/docs/v4/connectors/extensibility.md index 5b0f5e9c..7cdab274 100644 --- a/docs/docs/v4/connectors/extensibility.md +++ b/docs/docs/v4/connectors/extensibility.md @@ -6,7 +6,10 @@ They are not open-ended plug-ins; extensibility means shaping platform credentia Connectors map credentials from [Cloud Foundry service bindings](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/elastic-application-runtime/10-3/eart/binding-credentials.html) and [Service Binding Spec for Kubernetes](https://github.com/servicebinding/spec#well-known-secret-entries) into configuration keys starting with `steeltoe:service-bindings` and merge them with local settings from `Steeltoe:Client`. Each connector runs the binding logic for its own service type. - +> [!NOTE] +> The remainder of this page covers Cloud Foundry. Equivalent support for custom Kubernetes service bindings is not yet implemented. +> If you need it, [open an issue](https://github.com/SteeltoeOSS/Steeltoe/issues/new/choose) describing your scenario. + To use a third-party `VCAP_SERVICES` structure, populate the `steeltoe:service-bindings` keys yourself. It is recommended to turn off the built-in binding logic to prevent conflicts by setting `SkipDefaultServiceBindings` to `true`. Doing so will still merge with local settings from `Steeltoe:Client`. From 00a142dd8182b3d9aaef1f5c6e49086bc2794db2 Mon Sep 17 00:00:00 2001 From: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> Date: Thu, 7 May 2026 12:08:26 +0200 Subject: [PATCH 6/6] Add line break --- docs/docs/v4/connectors/extensibility.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/docs/v4/connectors/extensibility.md b/docs/docs/v4/connectors/extensibility.md index 7cdab274..ac19dcd6 100644 --- a/docs/docs/v4/connectors/extensibility.md +++ b/docs/docs/v4/connectors/extensibility.md @@ -6,10 +6,11 @@ They are not open-ended plug-ins; extensibility means shaping platform credentia Connectors map credentials from [Cloud Foundry service bindings](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/elastic-application-runtime/10-3/eart/binding-credentials.html) and [Service Binding Spec for Kubernetes](https://github.com/servicebinding/spec#well-known-secret-entries) into configuration keys starting with `steeltoe:service-bindings` and merge them with local settings from `Steeltoe:Client`. Each connector runs the binding logic for its own service type. -> [!NOTE] -> The remainder of this page covers Cloud Foundry. Equivalent support for custom Kubernetes service bindings is not yet implemented. -> If you need it, [open an issue](https://github.com/SteeltoeOSS/Steeltoe/issues/new/choose) describing your scenario. - + +> [!NOTE] +> The remainder of this page covers Cloud Foundry. Equivalent support for custom Kubernetes service bindings is not yet implemented. +> If you need it, [open an issue](https://github.com/SteeltoeOSS/Steeltoe/issues/new/choose) describing your scenario. + To use a third-party `VCAP_SERVICES` structure, populate the `steeltoe:service-bindings` keys yourself. It is recommended to turn off the built-in binding logic to prevent conflicts by setting `SkipDefaultServiceBindings` to `true`. Doing so will still merge with local settings from `Steeltoe:Client`.