Skip to content

Commit 200d8ef

Browse files
pratik-mahallepratik-mahalle
authored
docs: Configuring the Backstage Plugin (#448)
* docs: added the microks-hub content Signed-off-by: pratik-mahalle <mahallepratik683@gmail.com> * docs: added some minor changes Signed-off-by: pratik-mahalle <mahallepratik683@gmail.com> * docs: added the backstage plugin guide Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com> * docs: added the backstage plugin guide Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com> * docs: added the backstage-plugin guide Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com> * update the suggested changes Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com> * update the yarn commandf Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com> --------- Signed-off-by: pratik-mahalle <mahallepratik683@gmail.com> Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com>
1 parent c76105d commit 200d8ef

1 file changed

Lines changed: 111 additions & 8 deletions

File tree

‎content/documentation/guides/integration/backstage-plugin.md‎

Lines changed: 111 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,117 @@
22
draft: false
33
title: "Configuring the Backstage Plugin"
44
date: 2024-04-30
5-
publishdate: 2024-04-30
6-
lastmod: 2024-04-30
5+
publishdate: 205-09-29
6+
lastmod: 2025-09-29
77
weight: 3
88
---
99

10-
> 🪄 **To Be Created**
11-
>
12-
> This is a new documentation page that has to be written as part of our [Refactoring Effort](https://github.com/microcks/microcks.io/issues/81).
13-
>
14-
> **Goal of this page**
15-
> * ...
10+
The Microcks Backstage provider discovers APIs from one or more Microcks instances and syncs them into the Backstage Software Catalog as `API` entities. This page explains how to install, configure, and verify the provider in your Backstage app.
11+
12+
- **Plugin repository**: https://github.com/microcks/microcks-backstage-provider
13+
- **Overview blog post**: https://microcks.io/blog/backstage-integration-launch/
14+
15+
## Prerequisites
16+
17+
- A running Backstage application (backend package available)
18+
- A running Microcks instance and its base URL, for example: `https://microcks.acme.com`
19+
- A Microcks Service Account in your Keycloak realm, with client id and secret
20+
- See: [/documentation/explanations/service-account](/documentation/explanations/service-account)
21+
22+
## 1. Install the provider
23+
24+
Add the provider to your Backstage backend:
25+
26+
```bash
27+
yarn --cwd packages/backend add @microcks/microcks-backstage-provider@^0.0.7
28+
```
29+
30+
> Note: Check the provider's version compatibility with your Backstage release in the compatibility matrix from the [repository README](https://github.com/microcks/microcks-backstage-provider#readme) and pick the appropriate version.
31+
32+
## 2. Configure providers in `app-config.yaml`
33+
34+
Declare one or more Microcks named providers under the Backstage catalog section. Each provider points to a Microcks instance and defines sync options.
35+
36+
```yaml
37+
catalog:
38+
providers:
39+
microcksApiEntity:
40+
dev:
41+
baseUrl: https://microcks.acme.com
42+
serviceAccount: microcks-serviceaccount
43+
serviceAccountCredentials: ab54d329-e435-41ae-a900-ec6b3fe15c54
44+
systemLabel: domain
45+
ownerLabel: team
46+
schedule: # optional; same options as in TaskScheduleDefinition
47+
frequency: { minutes: 2 }
48+
timeout: { minutes: 1 }
49+
prod:
50+
baseUrl: https://microcks.example.com
51+
serviceAccount: backstage-sync
52+
serviceAccountCredentials: ${MICROCKS_BACKSTAGE_SYNC_SECRET}
53+
systemLabel: system
54+
ownerLabel: owner
55+
```
56+
57+
- **baseUrl**: Public base URL of your Microcks instance (no trailing `/api/`).
58+
- **serviceAccount / serviceAccountCredentials**: Credentials of a Service Account in the Microcks Keycloak realm used to query Microcks. Prefer storing secrets in environment variables. See the Service Account documentation: [/documentation/explanations/service-account](/documentation/explanations/service-account).
59+
- **systemLabel / ownerLabel**: Microcks labels to map onto Backstage `system` and `owner` fields of the `API` entity. Choose labels that exist on your APIs in Microcks.
60+
- **schedule**: Optional sync cadence. If omitted, the default provider schedule applies.
61+
62+
For guidance on creating and managing Service Accounts and understanding default roles, see [/documentation/explanations/service-account](/documentation/explanations/service-account). For Keycloak-related configuration in Microcks, see [/documentation/references/configuration/security-config](/documentation/references/configuration/security-config).
63+
64+
## 3. Register the provider in your backend
65+
66+
Add the provider to the catalog plugin initialization in your Backstage backend (for example in `packages/backend/src/plugins/catalog.ts`). The exact file may vary depending on your app-template version.
67+
68+
```ts
69+
import { MicrocksApiEntityProvider } from '@microcks/microcks-backstage-provider';
70+
71+
// within your builder/initializer
72+
builder.addEntityProvider(
73+
MicrocksApiEntityProvider.fromConfig(env.config, {
74+
logger: env.logger,
75+
scheduler: env.scheduler,
76+
}),
77+
);
78+
```
79+
80+
Ensure your backend loads configuration from `app-config.yaml` and that the provider key path (`catalog.providers.microcksApiEntity`) matches your YAML.
81+
82+
## 4. Authentication and permissions
83+
84+
The provider authenticates to Microcks using a Keycloak client (Service Account). At minimum, it needs read access to list APIs and artifacts in Microcks. If you use the default realm import, the `microcks-serviceaccount` exists by default. For production, create a dedicated client for Backstage and scope it to read-only permissions.
85+
86+
- How to inspect or create accounts: [/documentation/explanations/service-account](/documentation/explanations/service-account)
87+
- How Microcks references Service Accounts in its own configs: [/documentation/references/configuration/security-config](/documentation/references/configuration/security-config)
88+
89+
## 5. Verify the synchronization
90+
91+
1. Start your Backstage backend so the provider can run on schedule.
92+
2. In Microcks, pick an API that has a name, version, and at least one artifact (OpenAPI/AsyncAPI/gRPC).
93+
3. Wait for the next scheduled run (or restart the backend to trigger immediately).
94+
4. In Backstage, open Catalog → APIs and search for the synchronized APIs.
95+
5. Inspect an API entity details page; you should see links to the API contract, mock sandbox, and test results.
96+
97+
## 6. Troubleshooting
98+
99+
- **No APIs appear in Backstage**
100+
- Verify `baseUrl` points to the public Microcks URL and is reachable from the Backstage backend.
101+
- Check that the Service Account is valid and has permissions; try using its client id/secret to get a token against Keycloak.
102+
- Ensure your labels mapping (`systemLabel`, `ownerLabel`) corresponds to actual labels in Microcks (or omit them initially).
103+
- Increase backend log level and look for logs from `MicrocksApiEntityProvider`.
104+
105+
- **Auth or 401 errors**
106+
- Re-check the Service Account credentials and Keycloak realm. If using environment variables, confirm they are exported to the backend process.
107+
108+
- **Slow or infrequent updates**
109+
- Tune the `schedule.frequency` and `schedule.timeout` values. Avoid overly aggressive schedules in production.
110+
111+
- **Conflicting ownership or duplicates**
112+
- Confirm only one provider is responsible for a given set of APIs. If combining multiple Microcks instances, use consistent labeling to distinguish systems and owners.
113+
114+
## See also
115+
116+
- Blog overview and screenshots: [/blog/backstage-integration-launch/](/blog/backstage-integration-launch/)
117+
- Provider source and issues: `https://github.com/microcks/microcks-backstage-provider`
118+
- Backstage Catalog concepts: `https://backstage.io/docs/features/software-catalog/`

0 commit comments

Comments
 (0)