diff --git a/.changeset/rotten-paths-pump.md b/.changeset/rotten-paths-pump.md new file mode 100644 index 0000000000..3d0031edfe --- /dev/null +++ b/.changeset/rotten-paths-pump.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +--- + +Migrate audit events reference docs to http://backstage.io/docs. diff --git a/.changeset/yellow-ties-dream.md b/.changeset/yellow-ties-dream.md new file mode 100644 index 0000000000..8326b28319 --- /dev/null +++ b/.changeset/yellow-ties-dream.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Migrate audit events reference docs to http://backstage.io/docs. diff --git a/docs/features/software-catalog/audit-events.md b/docs/features/software-catalog/audit-events.md new file mode 100644 index 0000000000..9fc003f595 --- /dev/null +++ b/docs/features/software-catalog/audit-events.md @@ -0,0 +1,49 @@ +--- +id: audit-events +title: Audit Events +description: Tracking access to your Software Catalog. +--- + +The Catalog backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction within an operation group. + +## Entity Events + +- **`entity-fetch`**: Retrieves entities. +- **Note:** By default, "low" severity audit events like `entity-fetch` aren't logged because they map to the "debug" level, while Backstage defaults to "info" level logging. To see `entity-fetch` events, update your `app-config.yaml` by setting `backend.auditor.severityLogLevelMappings.low: info`. See the [Auditor Service documentation](https://backstage.io/docs/backend-system/core-services/auditor/#severity-levels-and-default-mappings) for details on severity mappings. + + Filter on `queryType`. + + - **`all`**: Fetching all entities. (GET `/entities`) + - **`by-id`**: Fetching a single entity using its UID. (GET `/entities/by-uid/:uid`) + - **`by-name`**: Fetching a single entity using its kind, namespace, and name. (GET `/entities/by-name/:kind/:namespace/:name`) + - **`by-query`**: Fetching multiple entities using a filter query. (GET `/entities/by-query`) + - **`by-refs`**: Fetching a batch of entities by their entity refs. (POST `/entities/by-refs`) + - **`ancestry`**: Fetching the ancestry of an entity. (GET `/entities/by-name/:kind/:namespace/:name/ancestry`) + +- **`entity-mutate`**: Modifies entities. + + Filter on `actionType`. + + - **`delete`**: Deleting a single entity. Note: this will not be a permanent deletion and the entity will be restored if the parent location is still present in the catalog. (DELETE `/entities/by-uid/:uid`) + - **`refresh`**: Scheduling an entity refresh. (POST `/entities/refresh`) + +- **`entity-validate`**: Validates an entity. (POST `/entities/validate`) + +- **`entity-facets`**: Retrieves entity facets. (GET `/entity-facets`) + +## Location Events + +- **`location-fetch`**: Retrieves locations. + + Filter on `actionType`. + + - **`all`**: Fetching all locations. (GET `/locations`) + - **`by-id`**: Fetching a single location by ID. (GET `/locations/:id`) + - **`by-entity`**: Fetching locations associated with an entity ref. (GET `/locations/by-entity`) + +- **`location-mutate`**: Modifies locations. + + - **`create`**: Creating a new location. (POST `/locations`) + - **`delete`**: Deleting a location and its associated entities. (DELETE `/locations/:id`) + +- **`location-analyze`**: Analyzes a location. (POST `/locations/analyze`) diff --git a/docs/features/software-templates/audit-events.md b/docs/features/software-templates/audit-events.md new file mode 100644 index 0000000000..cf50d98317 --- /dev/null +++ b/docs/features/software-templates/audit-events.md @@ -0,0 +1,32 @@ +--- +id: audit-events +title: Audit Events +description: Tracking access to your Scaffolder. +--- + +The Scaffolder backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction when needed. + +## Template Events + +- **`template-parameter-schema`**: Retrieves template parameter schemas. (GET `/v2/templates/:namespace/:kind/:name/parameter-schema`) + +## Action Events + +- **`action-fetch`**: Retrieves installed actions. (GET `/v2/actions`) + +## Task Events + +- **`task`**: Operations related to Scaffolder tasks. + + Filter on `actionType`. + + - **`create`**: Creates a new task. (POST `/v2/tasks`) + - **`list`**: Fetches details of all tasks. (GET `/v2/tasks`) + - **`get`**: Fetches details of a specific task. (GET `/v2/tasks/:taskId`) + - **`cancel`**: Cancels a running task. (POST `/v2/tasks/:taskId/cancel`) + - **`retry`**: Retries a failed task. (POST `/v2/tasks/:taskId/retry`) + - **`stream`**: Retrieves a stream of task logs. (GET `/v2/tasks/:taskId/eventstream`) + - **`events`**: Retrieves a snapshot of task logs. (GET `/v2/tasks/:taskId/events`) + - **`dry-run`**: Creates a dry-run task. (POST `/v2/dry-run`) All audit logs for events associated with dry runs have the `meta.isDryLog` flag set to `true`. + - **`stale-cancel`**: Automated cancellation of stale tasks. + - **`execute`**: Tracks the initiation and completion of a real scaffolder task execution. This event will not occur during dry runs. diff --git a/microsite/sidebars.ts b/microsite/sidebars.ts index 33bee593f8..5432edd6db 100644 --- a/microsite/sidebars.ts +++ b/microsite/sidebars.ts @@ -247,6 +247,7 @@ export default { 'features/software-catalog/extending-the-model', 'features/software-catalog/external-integrations', 'features/software-catalog/catalog-customization', + 'features/software-catalog/audit-events', { type: 'category', label: 'API', @@ -289,6 +290,7 @@ export default { 'features/software-templates/dry-run-testing', 'features/software-templates/experimental', 'features/software-templates/templating-extensions', + 'features/software-templates/audit-events', { type: 'category', label: 'API', diff --git a/plugins/catalog-backend/README.md b/plugins/catalog-backend/README.md index 00b88cf060..3d42d90252 100644 --- a/plugins/catalog-backend/README.md +++ b/plugins/catalog-backend/README.md @@ -87,52 +87,6 @@ yarn start This will launch both frontend and backend in the same window, populated with some example entities. -## Audit Events - -The Catalog backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction within an operation group. - -**Entity Events:** - -- **`entity-fetch`**: Retrieves entities. -- **Note:** By default, "low" severity audit events like `entity-fetch` aren't logged because they map to the "debug" level, while Backstage defaults to "info" level logging. To see `entity-fetch` events, update your `app-config.yaml` by setting `backend.auditor.severityLogLevelMappings.low: info`. See the [Auditor Service documentation](https://backstage.io/docs/backend-system/core-services/auditor/#severity-levels-and-default-mappings) for details on severity mappings. - - Filter on `queryType`. - - - **`all`**: Fetching all entities. (GET `/entities`) - - **`by-id`**: Fetching a single entity using its UID. (GET `/entities/by-uid/:uid`) - - **`by-name`**: Fetching a single entity using its kind, namespace, and name. (GET `/entities/by-name/:kind/:namespace/:name`) - - **`by-query`**: Fetching multiple entities using a filter query. (GET `/entities/by-query`) - - **`by-refs`**: Fetching a batch of entities by their entity refs. (POST `/entities/by-refs`) - - **`ancestry`**: Fetching the ancestry of an entity. (GET `/entities/by-name/:kind/:namespace/:name/ancestry`) - -- **`entity-mutate`**: Modifies entities. - - Filter on `actionType`. - - - **`delete`**: Deleting a single entity. Note: this will not be a permanent deletion and the entity will be restored if the parent location is still present in the catalog. (DELETE `/entities/by-uid/:uid`) - - **`refresh`**: Scheduling an entity refresh. (POST `/entities/refresh`) - -- **`entity-validate`**: Validates an entity. (POST `/entities/validate`) - -- **`entity-facets`**: Retrieves entity facets. (GET `/entity-facets`) - -**Location Events:** - -- **`location-fetch`**: Retrieves locations. - - Filter on `actionType`. - - - **`all`**: Fetching all locations. (GET `/locations`) - - **`by-id`**: Fetching a single location by ID. (GET `/locations/:id`) - - **`by-entity`**: Fetching locations associated with an entity ref. (GET `/locations/by-entity`) - -- **`location-mutate`**: Modifies locations. - - - **`create`**: Creating a new location. (POST `/locations`) - - **`delete`**: Deleting a location and its associated entities. (DELETE `/locations/:id`) - -- **`location-analyze`**: Analyzes a location. (POST `/locations/analyze`) - ## Links - [catalog](https://github.com/backstage/backstage/tree/master/plugins/catalog) diff --git a/plugins/scaffolder-backend/README.md b/plugins/scaffolder-backend/README.md index 3c4a2cb283..1e7dc91384 100644 --- a/plugins/scaffolder-backend/README.md +++ b/plugins/scaffolder-backend/README.md @@ -124,32 +124,3 @@ Default secrets are resolved from environment variables and accessible via `${{ ``` **Security Note:** Secrets are automatically masked in logs and are only available to backend actions, never exposed to the frontend. - -## Audit Events - -The Scaffolder backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction when needed. - -**Template Events:** - -- **`template-parameter-schema`**: Retrieves template parameter schemas. (GET `/v2/templates/:namespace/:kind/:name/parameter-schema`) - -**Action Events:** - -- **`action-fetch`**: Retrieves installed actions. (GET `/v2/actions`) - -**Task Events:** - -- **`task`**: Operations related to Scaffolder tasks. - - Filter on `actionType`. - - - **`create`**: Creates a new task. (POST `/v2/tasks`) - - **`list`**: Fetches details of all tasks. (GET `/v2/tasks`) - - **`get`**: Fetches details of a specific task. (GET `/v2/tasks/:taskId`) - - **`cancel`**: Cancels a running task. (POST `/v2/tasks/:taskId/cancel`) - - **`retry`**: Retries a failed task. (POST `/v2/tasks/:taskId/retry`) - - **`stream`**: Retrieves a stream of task logs. (GET `/v2/tasks/:taskId/eventstream`) - - **`events`**: Retrieves a snapshot of task logs. (GET `/v2/tasks/:taskId/events`) - - **`dry-run`**: Creates a dry-run task. (POST `/v2/dry-run`) All audit logs for events associated with dry runs have the `meta.isDryLog` flag set to `true`. - - **`stale-cancel`**: Automated cancellation of stale tasks. - - **`execute`**: Tracks the initiation and completion of a real scaffolder task execution. This event will not occur during dry runs.