From e28af58b4ba24495d7d1db03feb53e5737fe33e7 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 11 Jul 2024 11:12:21 +0200 Subject: [PATCH 1/2] backend-defaults: deprecate config service options Signed-off-by: Patrik Oldsberg --- .changeset/wet-rivers-travel.md | 5 ++++ .../core-services/root-config.md | 30 ++++++++++++------- .../backend-defaults/api-report-rootConfig.md | 2 +- .../rootConfig/rootConfigServiceFactory.ts | 1 + 4 files changed, 27 insertions(+), 11 deletions(-) create mode 100644 .changeset/wet-rivers-travel.md diff --git a/.changeset/wet-rivers-travel.md b/.changeset/wet-rivers-travel.md new file mode 100644 index 0000000000..44dedf3ccb --- /dev/null +++ b/.changeset/wet-rivers-travel.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-defaults': patch +--- + +The `RootConfigFactoryOptions` have been deprecated alongside the deprecation of service factory options. For more information on how to customize the config service, see the [Root Config Service docs](https://backstage.io/docs/backend-system/core-services/root-config#configuring-the-service). diff --git a/docs/backend-system/core-services/root-config.md b/docs/backend-system/core-services/root-config.md index 7cdc10f38c..9561a8f0cd 100644 --- a/docs/backend-system/core-services/root-config.md +++ b/docs/backend-system/core-services/root-config.md @@ -36,12 +36,12 @@ createBackendPlugin({ ## Configuring the service -There's additional configuration that you can optionally pass to setup the `config` core service. +There are several APIs from the `@backstage/config-loader` package that allow you to customize the implementation of the config service. The default implementation uses the `ConfigSources.default` method, which has several options, for example: - `argv` - Override the arguments that are passed to the config loader, instead of using `process.argv` - `remote` - Configure remote configuration loading -You can configure these additional options by adding an override for the core service when calling `createBackend` like follows: +You can use these to create your own config service implementation: ```ts import { rootConfigServiceFactory } from '@backstage/backend-app-api'; @@ -49,14 +49,24 @@ import { rootConfigServiceFactory } from '@backstage/backend-app-api'; const backend = createBackend(); backend.add( - rootConfigServiceFactory({ - argv: [ - '--config', - '/backstage/app-config.development.yaml', - '--config', - '/backstage/app-config.yaml', - ], - remote: { reloadIntervalSeconds: 60 }, + createServiceFactory({ + service: coreServices.rootConfig, + deps: {}, + async factory() { + const source = ConfigSources.default({ + argv: [ + '--config', + '/backstage/app-config.development.yaml', + '--config', + '/backstage/app-config.yaml', + ], + remote: { reloadIntervalSeconds: 60 }, + }); + console.log(`Loading config from ${source}`); + return await ConfigSources.toConfig(source); + }, }), ); ``` + +You can also use other config source such as `StaticConfigSource` and combine them with other sources using `ConfigSources.merge(...)`. You can also create your own config source by implementing the `ConfigSource` interface. diff --git a/packages/backend-defaults/api-report-rootConfig.md b/packages/backend-defaults/api-report-rootConfig.md index 24e827f520..8ad2e01a90 100644 --- a/packages/backend-defaults/api-report-rootConfig.md +++ b/packages/backend-defaults/api-report-rootConfig.md @@ -17,7 +17,7 @@ export function createConfigSecretEnumerator(options: { schema?: ConfigSchema; }): Promise<(config: Config) => Iterable>; -// @public +// @public @deprecated export interface RootConfigFactoryOptions { argv?: string[]; remote?: Pick; diff --git a/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts b/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts index 5752a9c634..7bcb9ef56b 100644 --- a/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts @@ -31,6 +31,7 @@ import { * for more information. * * @public + * @deprecated These service options will be removed, please use the `ConfigSources` API from `@backstage/config-loader` to implement your own version of the service factory instead. */ export interface RootConfigFactoryOptions { /** From e375bb93df617dc101df8bb8a7a2da7b743c752b Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 16 Jul 2024 10:20:11 +0200 Subject: [PATCH 2/2] backend-defaults: update root config implementation to use manual factory pattern + update docs Signed-off-by: Patrik Oldsberg --- .changeset/wet-rivers-travel.md | 2 +- .../core-services/root-config.md | 25 +++++++++++++++++-- .../backend-defaults/api-report-rootConfig.md | 13 +++++----- .../rootConfig/rootConfigServiceFactory.ts | 19 ++++++++------ 4 files changed, 42 insertions(+), 17 deletions(-) diff --git a/.changeset/wet-rivers-travel.md b/.changeset/wet-rivers-travel.md index 44dedf3ccb..1778a3db23 100644 --- a/.changeset/wet-rivers-travel.md +++ b/.changeset/wet-rivers-travel.md @@ -2,4 +2,4 @@ '@backstage/backend-defaults': patch --- -The `RootConfigFactoryOptions` have been deprecated alongside the deprecation of service factory options. For more information on how to customize the config service, see the [Root Config Service docs](https://backstage.io/docs/backend-system/core-services/root-config#configuring-the-service). +Refactor of `rootConfigServiceFactory` to allow it to be constructed with options, but without declaring options via `createServiceFactory`. diff --git a/docs/backend-system/core-services/root-config.md b/docs/backend-system/core-services/root-config.md index 9561a8f0cd..8505b9e7ec 100644 --- a/docs/backend-system/core-services/root-config.md +++ b/docs/backend-system/core-services/root-config.md @@ -36,18 +36,39 @@ createBackendPlugin({ ## Configuring the service -There are several APIs from the `@backstage/config-loader` package that allow you to customize the implementation of the config service. The default implementation uses the `ConfigSources.default` method, which has several options, for example: +There's additional configuration that you can optionally pass to setup the `config` core service. - `argv` - Override the arguments that are passed to the config loader, instead of using `process.argv` - `remote` - Configure remote configuration loading -You can use these to create your own config service implementation: +You can configure these additional options by adding an override for the core service when calling `createBackend` like follows: ```ts import { rootConfigServiceFactory } from '@backstage/backend-app-api'; const backend = createBackend(); +backend.add( + rootConfigServiceFactory({ + argv: [ + '--config', + '/backstage/app-config.development.yaml', + '--config', + '/backstage/app-config.yaml', + ], + remote: { reloadIntervalSeconds: 60 }, + }), +); +``` + +For more advanced customization, there are several APIs from the `@backstage/config-loader` package that allow you to customize the implementation of the config service. The default implementation uses the `ConfigSources.default` method, which has the same options as the `rootConfigServiceFactory` function. You can use these to create your own config service implementation: + +```ts +import { ConfigSources } from '@backstage/config-loader'; +import { createServiceFactory } from '@backstage/backend-plugin-api'; + +const backend = createBackend(); + backend.add( createServiceFactory({ service: coreServices.rootConfig, diff --git a/packages/backend-defaults/api-report-rootConfig.md b/packages/backend-defaults/api-report-rootConfig.md index 8ad2e01a90..61f5c9dc9d 100644 --- a/packages/backend-defaults/api-report-rootConfig.md +++ b/packages/backend-defaults/api-report-rootConfig.md @@ -8,7 +8,7 @@ import { ConfigSchema } from '@backstage/config-loader'; import { LoggerService } from '@backstage/backend-plugin-api'; import { RemoteConfigSourceOptions } from '@backstage/config-loader'; import { RootConfigService } from '@backstage/backend-plugin-api'; -import { ServiceFactoryCompat } from '@backstage/backend-plugin-api'; +import { ServiceFactory } from '@backstage/backend-plugin-api'; // @public (undocumented) export function createConfigSecretEnumerator(options: { @@ -17,7 +17,7 @@ export function createConfigSecretEnumerator(options: { schema?: ConfigSchema; }): Promise<(config: Config) => Iterable>; -// @public @deprecated +// @public export interface RootConfigFactoryOptions { argv?: string[]; remote?: Pick; @@ -26,11 +26,10 @@ export interface RootConfigFactoryOptions { } // @public (undocumented) -export const rootConfigServiceFactory: ServiceFactoryCompat< - RootConfigService, - 'root', - RootConfigFactoryOptions ->; +export const rootConfigServiceFactory: (( + options?: RootConfigFactoryOptions, +) => ServiceFactory) & + ServiceFactory; // (No @packageDocumentation comment for this package) ``` diff --git a/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts b/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts index 7bcb9ef56b..63a7353241 100644 --- a/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts @@ -31,7 +31,6 @@ import { * for more information. * * @public - * @deprecated These service options will be removed, please use the `ConfigSources` API from `@backstage/config-loader` to implement your own version of the service factory instead. */ export interface RootConfigFactoryOptions { /** @@ -46,11 +45,10 @@ export interface RootConfigFactoryOptions { watch?: boolean; } -/** - * @public - */ -export const rootConfigServiceFactory = createServiceFactory( - (options?: RootConfigFactoryOptions) => ({ +export const rootConfigServiceFactoryWithOptions = ( + options?: RootConfigFactoryOptions, +) => + createServiceFactory({ service: coreServices.rootConfig, deps: {}, async factory() { @@ -62,5 +60,12 @@ export const rootConfigServiceFactory = createServiceFactory( console.log(`Loading config from ${source}`); return await ConfigSources.toConfig(source); }, - }), + })(); + +/** + * @public + */ +export const rootConfigServiceFactory = Object.assign( + rootConfigServiceFactoryWithOptions, + rootConfigServiceFactoryWithOptions(), );