diff --git a/.changeset/rich-birds-reply.md b/.changeset/rich-birds-reply.md new file mode 100644 index 0000000000..6e4755ca86 --- /dev/null +++ b/.changeset/rich-birds-reply.md @@ -0,0 +1,23 @@ +--- +'@backstage/plugin-catalog-backend': minor +--- + +Add `readonly` mode to catalog backend + +This change adds a `catalog.readonly` field in `app-config.yaml` that can be used to configure the catalog in readonly mode which effectively disables the possibility of adding new components to the catalog after startup. + +When in `readonly` mode only locations configured in `catalog.locations` are loaded and served. +By default `readonly` is disabled which represents the current functionality where locations can be added at run-time. + +This change requires the config API in the router which requires a change to `createRouter`. + +```diff + return await createRouter({ + entitiesCatalog, + locationsCatalog, + higherOrderOperation, + locationAnalyzer, + logger: env.logger, ++ config: env.config, + }); +``` diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index fb69937613..32b1fefd7d 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -70,6 +70,7 @@ Protobuf Proxying Raghunandan Readme +readonly rebase Recharts Redash diff --git a/packages/backend/src/plugins/catalog.ts b/packages/backend/src/plugins/catalog.ts index eaca42717c..076840944f 100644 --- a/packages/backend/src/plugins/catalog.ts +++ b/packages/backend/src/plugins/catalog.ts @@ -45,5 +45,6 @@ export default async function createPlugin( higherOrderOperation, locationAnalyzer, logger: env.logger, + config: env.config, }); } diff --git a/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts b/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts index 556b385af3..838228cdb4 100644 --- a/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts +++ b/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts @@ -27,5 +27,6 @@ export default async function createPlugin(env: PluginEnvironment): Promise; }>; + /** + * Readonly defines whether the catalog allows writes after startup. + * + * Setting 'readonly=false' allows users to register their own components. + * This is the default value. + * + * Setting 'readonly=true' configures catalog to only allow reads. This can + * be used in combination with static locations to only serve operator + * provided locations. Effectively this removes the ability to register new + * components to a running backstage instance. + * + */ + readonly?: boolean; + /** * A set of static locations that the catalog shall always keep itself * up-to-date with. This is commonly used for large, permanent integrations diff --git a/plugins/catalog-backend/src/service/router.test.ts b/plugins/catalog-backend/src/service/router.test.ts index 74cf187548..756e17f858 100644 --- a/plugins/catalog-backend/src/service/router.test.ts +++ b/plugins/catalog-backend/src/service/router.test.ts @@ -15,6 +15,7 @@ */ import { getVoidLogger } from '@backstage/backend-common'; +import { ConfigReader } from '@backstage/config'; import { NotFoundError } from '@backstage/errors'; import type { Entity, LocationSpec } from '@backstage/catalog-model'; import express from 'express'; @@ -25,7 +26,7 @@ import { HigherOrderOperation } from '../ingestion/types'; import { createRouter } from './router'; import { basicEntityFilter } from './request'; -describe('createRouter', () => { +describe('createRouter readonly disabled', () => { let entitiesCatalog: jest.Mocked; let locationsCatalog: jest.Mocked; let higherOrderOperation: jest.Mocked; @@ -55,6 +56,7 @@ describe('createRouter', () => { locationsCatalog, higherOrderOperation, logger: getVoidLogger(), + config: new ConfigReader(undefined), }); app = express().use(router); }); @@ -353,3 +355,157 @@ describe('createRouter', () => { }); }); }); + +describe('createRouter readonly enabled', () => { + let entitiesCatalog: jest.Mocked; + let locationsCatalog: jest.Mocked; + let higherOrderOperation: jest.Mocked; + let app: express.Express; + + beforeAll(async () => { + entitiesCatalog = { + entities: jest.fn(), + removeEntityByUid: jest.fn(), + batchAddOrUpdateEntities: jest.fn(), + }; + locationsCatalog = { + addLocation: jest.fn(), + removeLocation: jest.fn(), + locations: jest.fn(), + location: jest.fn(), + locationHistory: jest.fn(), + logUpdateSuccess: jest.fn(), + logUpdateFailure: jest.fn(), + }; + higherOrderOperation = { + addLocation: jest.fn(), + refreshAllLocations: jest.fn(), + }; + const router = await createRouter({ + entitiesCatalog, + locationsCatalog, + higherOrderOperation, + logger: getVoidLogger(), + config: new ConfigReader({ + catalog: { + readonly: true, + }, + }), + }); + app = express().use(router); + }); + + beforeEach(() => { + jest.resetAllMocks(); + }); + + describe('GET /entities', () => { + it('happy path: lists entities', async () => { + const entities: Entity[] = [ + { apiVersion: 'a', kind: 'b', metadata: { name: 'n' } }, + ]; + + entitiesCatalog.entities.mockResolvedValueOnce({ + entities: [entities[0]], + pageInfo: { hasNextPage: false }, + }); + + const response = await request(app).get('/entities'); + + expect(response.status).toEqual(200); + expect(response.body).toEqual(entities); + }); + }); + + describe('POST /entities', () => { + it('is not allowed', async () => { + const entity: Entity = { + apiVersion: 'a', + kind: 'b', + metadata: { + name: 'c', + namespace: 'd', + }, + }; + + const response = await request(app) + .post('/entities') + .set('Content-Type', 'application/json') + .send(entity); + + expect(entitiesCatalog.batchAddOrUpdateEntities).not.toHaveBeenCalled(); + expect(response.status).toEqual(403); + expect(response.text).toMatch(/not allowed in readonly/); + }); + }); + + describe('DELETE /entities/by-uid/:uid', () => { + // this delete is allowed as there is no other way to remove entities + it('is allowed', async () => { + const response = await request(app).delete('/entities/by-uid/apa'); + + expect(entitiesCatalog.removeEntityByUid).toHaveBeenCalledTimes(1); + expect(entitiesCatalog.removeEntityByUid).toHaveBeenCalledWith('apa'); + expect(response.status).toEqual(204); + }); + }); + + describe('GET /locations', () => { + it('happy path: lists locations', async () => { + const locations: LocationResponse[] = [ + { + currentStatus: { timestamp: '', status: '', message: '' }, + data: { id: 'a', type: 'b', target: 'c' }, + }, + ]; + locationsCatalog.locations.mockResolvedValueOnce(locations); + + const response = await request(app).get('/locations'); + + expect(response.status).toEqual(200); + expect(response.body).toEqual(locations); + }); + }); + + describe('POST /locations', () => { + it('is not allowed', async () => { + const spec: LocationSpec = { + type: 'b', + target: 'c', + }; + + const response = await request(app).post('/locations').send(spec); + + expect(higherOrderOperation.addLocation).not.toHaveBeenCalled(); + expect(response.status).toEqual(403); + expect(response.text).toMatch(/not allowed in readonly/); + }); + + it('supports dry run', async () => { + const spec: LocationSpec = { + type: 'b', + target: 'c', + }; + + higherOrderOperation.addLocation.mockResolvedValue({ + location: { id: 'a', ...spec }, + entities: [], + }); + + const response = await request(app) + .post('/locations?dryRun=true') + .send(spec); + + expect(higherOrderOperation.addLocation).toHaveBeenCalledTimes(1); + expect(higherOrderOperation.addLocation).toHaveBeenCalledWith(spec, { + dryRun: true, + }); + expect(response.status).toEqual(201); + expect(response.body).toEqual( + expect.objectContaining({ + location: { id: 'a', ...spec }, + }), + ); + }); + }); +}); diff --git a/plugins/catalog-backend/src/service/router.ts b/plugins/catalog-backend/src/service/router.ts index 048126aace..ae58255a4e 100644 --- a/plugins/catalog-backend/src/service/router.ts +++ b/plugins/catalog-backend/src/service/router.ts @@ -20,6 +20,7 @@ import { analyzeLocationSchema, locationSpecSchema, } from '@backstage/catalog-model'; +import { Config } from '@backstage/config'; import { NotFoundError } from '@backstage/errors'; import express from 'express'; import Router from 'express-promise-router'; @@ -33,7 +34,11 @@ import { parseEntityPaginationParams, parseEntityTransformParams, } from './request'; -import { requireRequestBody, validateRequestBody } from './util'; +import { + disallowReadonlyMode, + requireRequestBody, + validateRequestBody, +} from './util'; export interface RouterOptions { entitiesCatalog?: EntitiesCatalog; @@ -41,6 +46,7 @@ export interface RouterOptions { higherOrderOperation?: HigherOrderOperation; locationAnalyzer?: LocationAnalyzer; logger: Logger; + config: Config; } export async function createRouter( @@ -51,11 +57,19 @@ export async function createRouter( locationsCatalog, higherOrderOperation, locationAnalyzer, + config, + logger, } = options; const router = Router(); router.use(express.json()); + const readonlyEnabled = + config.getOptionalBoolean('catalog.readonly') || false; + if (readonlyEnabled) { + logger.info('Catalog is running in readonly mode'); + } + if (entitiesCatalog) { router .get('/entities', async (req, res) => { @@ -87,6 +101,8 @@ export async function createRouter( * It stays around in the service for the time being, but may be * removed or change semantics at any time without prior notice. */ + disallowReadonlyMode(readonlyEnabled); + const body = await requireRequestBody(req); const [result] = await entitiesCatalog.batchAddOrUpdateEntities([ { entity: body as Entity, relations: [] }, @@ -133,6 +149,13 @@ export async function createRouter( router.post('/locations', async (req, res) => { const input = await validateRequestBody(req, locationSpecSchema); const dryRun = yn(req.query.dryRun, { default: false }); + + // when in dryRun addLocation is effectively a read operation so we don't + // need to disallow readonly + if (!dryRun) { + disallowReadonlyMode(readonlyEnabled); + } + const output = await higherOrderOperation.addLocation(input, { dryRun }); res.status(201).json(output); }); @@ -155,6 +178,8 @@ export async function createRouter( res.status(200).json(output); }) .delete('/locations/:id', async (req, res) => { + disallowReadonlyMode(readonlyEnabled); + const { id } = req.params; await locationsCatalog.removeLocation(id); res.status(204).end(); diff --git a/plugins/catalog-backend/src/service/standaloneServer.ts b/plugins/catalog-backend/src/service/standaloneServer.ts index 73a33c8c8e..44a5c0f84d 100644 --- a/plugins/catalog-backend/src/service/standaloneServer.ts +++ b/plugins/catalog-backend/src/service/standaloneServer.ts @@ -61,6 +61,7 @@ export async function startStandaloneServer( locationsCatalog, higherOrderOperation, logger, + config, }); const service = createServiceBuilder(module) .enableCors({ origin: 'http://localhost:3000' }) diff --git a/plugins/catalog-backend/src/service/util.ts b/plugins/catalog-backend/src/service/util.ts index d806f630e8..9cc5ba1b52 100644 --- a/plugins/catalog-backend/src/service/util.ts +++ b/plugins/catalog-backend/src/service/util.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { InputError } from '@backstage/errors'; +import { InputError, NotAllowedError } from '@backstage/errors'; import { Request } from 'express'; import lodash from 'lodash'; import yup from 'yup'; @@ -54,3 +54,9 @@ export async function validateRequestBody( return (body as unknown) as T; } + +export function disallowReadonlyMode(readonly: boolean) { + if (readonly) { + throw new NotAllowedError('This operation not allowed in readonly mode'); + } +}