paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 22 Packages Projects Releases Wiki Activity

address config schema review comments

Browse Source
This commit is contained in:
Patrik Oldsberg
2020-11-17 18:25:55 +01:00
parent 39591369ba
commit 0b97a89f55
8 changed files with 39 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/add-config-schema-support.md
+3 -3
View File
@@ -4,13 +4,13 @@
'@backstage/config-loader': minor
---
Added support for loading and validating configuration schema, as well as declaring config visibility through schema.
Added support for loading and validating configuration schemas, as well as declaring config visibility through schemas.
The new `loadConfigSchema` function exported by `@backstage/config-loader` allows for the collection and merging of configuration schemas from all nearby dependencies of the project.
Configuration schema is declared using the following JSONSchema meta schema, which is based on draft07: https://backstage.io/schema/config-v1. The only difference to the draft07 schema is the custom `visibility` keyword, which is used to indicate whether the given config value should be visible in the frontend or not. The possible values are `frontend`, `backend`, `secret`, where `backend` is the default. A visibility of `secret` has the same scope at runtime, but it will be treated with more care in certain contexts, and defining both `frontend` and `secret` for the same value in two different schemas will result in an error during schema merging.
A configuration schema is declared using the `https://backstage.io/schema/config-v1` JSON Schema meta schema, which is based on draft07. The only difference to the draft07 schema is the custom `visibility` keyword, which is used to indicate whether the given config value should be visible in the frontend or not. The possible values are `frontend`, `backend`, and `secret`, where `backend` is the default. A visibility of `secret` has the same scope at runtime, but it will be treated with more care in certain contexts, and defining both `frontend` and `secret` for the same value in two different schemas will result in an error during schema merging.
Packages that wish to contribute configuration schema should declare it in a root "configSchema" field in `package.json`. The field can either contain an inlined JSON schema, or a relative path to a schema file. Schema files can be declared in either `.json` or `.d.ts`.
Packages that wish to contribute configuration schema should declare it in a root `"configSchema"` field in `package.json`. The field can either contain an inlined JSON schema, or a relative path to a schema file. Schema files can be in either `.json` or `.d.ts` format.
TypeScript configuration schema files should export a single `Config` type, for example:
.changeset/app-backend-config.md
+1 -1
View File
@@ -4,4 +4,4 @@
Use new config schema support to automatically inject config with frontend visibility, in addition to the existing env schema injection.
This removes the confusing behavior where configuration was only injected into the app att build time. Any runtime configuration (except for environment config) in the backend used to only apply to the backend itself, and not be injected into the frontend.
This removes the confusing behavior where configuration was only injected into the app at build time. Any runtime configuration (except for environment config) in the backend used to only apply to the backend itself, and not be injected into the frontend.
.github/styles/vocab.txt
+1
View File
@@ -177,6 +177,7 @@ src
subkey
superfences
Superfences
superset
talkdesk
Talkdesk
tasklist
.github/workflows/master.yml
+3
View File
@@ -47,6 +47,9 @@ jobs:
run: yarn install --frozen-lockfile
# End of yarn setup
- name: validate config
run: yarn backstage-cli config:validate
- name: lint
run: yarn lerna -- run lint
docs/conf/defining.md
+15 -15
View File
@@ -5,7 +5,7 @@ description: Documentation on Defining Configuration for your Plugin
---
Configuration in Backstage is organized via a configuration schema, which in
turn is defined using a super set of
turn is defined using a superset of
[JSON Schema Draft-07](https://json-schema.org/specification-links.html#draft-7).
Each plugin or package within a Backstage app can contribute to the schema,
which during validation is stitched together into a single schema.
@@ -17,13 +17,13 @@ part of the Backstage ecosystem, including transitive dependencies. The current
definition of "part of the ecosystem" is that a package has at least one
dependency in the `@backstage` namespace, but this is subject to change.
Each package is search for schema at a single point of entry, a top-level
Each package is searched for a schema at a single point of entry, a top-level
`"configSchema"` field in `package.json`. The field can either contain an
inlined JSON schema, or a relative path to a schema file. Supported schema file
formats are `.json` or `.d.ts`.
> When using a schema file, be sure to include the file in your `package.json` >
> `"files"` field as well!
> When defining a schema file, be sure to include the file in your
> `package.json` > `"files"` field as well!
TypeScript configuration schema files should export a single `Config` type, for
example:
@@ -67,11 +67,11 @@ receive schema validation and autocompletion. For example:
## Visibility
The `https://backstage.io/schema/config-v1` meta schema is a super set of JSON
The `https://backstage.io/schema/config-v1` meta schema is a superset of JSON
Schema Draft 07. The single addition is a custom `visibility` keyword, which is
used to indicate whether the given config value should be visible in the
frontend or not. The possible values are `frontend`, `backend`, `secret`, where
`backend` is the default. A visibility of `secret` has the same scope at
frontend or not. The possible values are `frontend`, `backend`, and `secret`,
where `backend` is the default. A visibility of `secret` has the same scope at
runtime, but it will be treated with more care in certain contexts, and defining
both `frontend` and `secret` for the same value in two different schemas will
result in an error during schema merging.
@@ -85,24 +85,24 @@ declare the visibility of a leaf node of `type: "string"`.
## Validation
Schema can be validated using the `backstage-cli config:validate` command. If
Schemas can be validated using the `backstage-cli config:validate` command. If
you want to validate anything else than the default `app-config.yaml`, be sure
to pass in all of the configuration files as `--config <path>` options as well.
To validate and examine the frontend configuration, use can use the
To validate and examine the frontend configuration, use the
`backstage-cli config:print --frontend` command. Just like for validation you
may need to pass in all files using one or multiple `--config <path>` options.
## Guidelines
> Limit static configuration. The first question to ask is whether a particular
> option actually needs to be static configuration, or if it might just as well
> be a TypeScript API. In general options that you want to be able to change for
> different deployment environments should be static configuration, while it
> should otherwise be avoided.
> Make limited use of static configuration. The first question to ask is whether
> a particular option actually needs to be static configuration, or if it might
> just as well be a TypeScript API. In general, options that you want to be able
> to change for different deployment environments should be static
> configuration, while it should otherwise be avoided.
When defining configuration for your plugin, keep keys camelCased and stick to
existing casing conventions such as `baseUrl`.
existing casing conventions such as `baseUrl` rather than `baseURL`.
It is also usually best to prefer objects over arrays, as it makes it possible
to override individual values using separate files or environment variables.
docs/conf/index.md
+4 -4
View File
@@ -35,15 +35,15 @@ For more details, see [Writing Configuration](./writing.md).
## Configuration Schema
The configuration is validated using a JSON Schema definitions. Each plugin and
package can provide pieces of the configuration schema, which is stitched
The configuration is validated using JSON Schema definitions. Each plugin and
package can provide pieces of the configuration schema, which are stitched
together to form a complete schema during validation. The configuration schema
is also used to select what configuration is available in the frontend using a
custom `visibility` keyword, as configuration is by default only available in
the backend.
You can validate your configuration against the schema using
`backstage-cli config:validate`, and define schema for your own plugin either
`backstage-cli config:validate`, and define a schema for your own plugin either
using JSON Schema or TypeScript. For more information, see
[Defining Configuration](./defining.md).
@@ -63,5 +63,5 @@ More details are provided in dedicated sections of the documentation.
plugin.
- [Writing Configuration](./writing.md): How to provide configuration for your
Backstage deployment.
- [Defining Configuration](./defining.md): How to define configuration schema
- [Defining Configuration](./defining.md): How to define a configuration schema
for users of your plugin or package.
packages/backend-common/config.d.ts
Vendored
+9 -9
View File
@@ -21,8 +21,8 @@ export interface Config {
backend: {
baseUrl: string; // defined in core, but repeated here without doc
/** Address that the backend should listen to. */
/** Address that the backend should listen to. */
listen:
| string
| {
@@ -86,7 +86,7 @@ export interface Config {
/** Configuration for integrations towards various external repository provider systems */
integrations?: {
/** Integration configuration for Azure */
azure?: {
azure?: Array<{
/** The hostname of the given Azure instance */
host: string;
/**
@@ -94,10 +94,10 @@ export interface Config {
* @visibility secret
*/
token?: string;
}[];
}>;
/** Integration configuration for BitBucket */
bitbucket?: {
bitbucket?: Array<{
/** The hostname of the given Bitbucket instance */
host: string;
/**
@@ -117,10 +117,10 @@ export interface Config {
* @visibility secret
*/
appPassword?: string;
}[];
}>;
/** Integration configuration for GitHub */
github?: {
github?: Array<{
/** The hostname of the given GitHub instance */
host: string;
/**
@@ -132,10 +132,10 @@ export interface Config {
apiBaseUrl?: string;
/** The base url for GitHub raw resources, for example https://raw.githubusercontent.com */
rawBaseUrl?: string;
}[];
}>;
/** Integration configuration for GitLab */
gitlab?: {
gitlab?: Array<{
/** The hostname of the given GitLab instance */
host: string;
/**
@@ -143,6 +143,6 @@ export interface Config {
* @visibility secret
*/
token?: string;
}[];
}>;
};
}
packages/config-loader/src/lib/schema/types.ts
+3 -3
View File
@@ -21,11 +21,11 @@ import { AppConfig, JsonObject } from '@backstage/config';
*/
export type ConfigSchemaPackageEntry = {
/**
* The configuration schema itself, as JSONSchema draft-07
* The configuration schema itself.
*/
value: JsonObject;
/**
* The path that the configuration schema was discovered at.
* The relative path that the configuration schema was discovered at.
*/
path: string;
};
@@ -59,7 +59,7 @@ type ValidationResult = {
*/
errors?: ValidationError[];
/**
* The configuration visibilities the where discovered during validation.
* The configuration visibilities that were discovered during validation.
*
* The path in the key uses the form `/<key>/<sub-key>/<array-index>/<leaf-key>`
*/