Backstage-Katalog in Archyl importieren: Backstage zu C4

Machen Sie aus Ihrem Backstage Software Catalog ein navigierbares C4-Modell. System, Component, Resource und Inline-API-Specs kommen aus entities.json.

Importiere deinen Backstage-Katalog in Archyl

Backstage listet auf, was du betreibst. Archyl macht aus demselben Katalog ein navigierbares C4-Modell: System-Entitäten werden zu Systemen, Component- und Resource-Entitäten werden zu Containern, und jede API-Entität wird zu einem Vertrag, dessen Spec unverändert erhalten bleibt und mit den Services verknüpft ist, die sie bereitstellen und konsumieren. Du behältst Backstage. Die Eigentümer werden nicht übernommen, und du bekommst zwei C4-Ebenen, auf denen du aufbauen kannst.

Backstage-Katalog in Archyl importieren | Backstage zu C4

Mach aus deinem Backstage Software Catalog ein navigierbares C4-Architekturmodell. System, Component, Resource und Inline-API-Specs werden aus entities.json importiert. Das Eigentum bleibt in Backstage.

Backstage zu C4, Backstage Katalog Import, Backstage Katalog exportieren, Backstage Architekturdiagramm, Backstage Software Catalog C4-Modell, Backstage Architekturdokumentation

Jede System-Entität wird zu einem C4-Softwaresystem mit Beschreibung und Tags. Zwei System-Entitäten mit demselben Namen in verschiedenen Namespaces werden umbenannt statt zusammengeführt, und der Import sagt dir, welche.

Component-Entitäten werden zu Containern unter dem System, dem sie gehören, aufgelöst über spec.system oder eine partOf-Relation. Ihr spec.type wird gemappt: service zu Service, website zu Webanwendung, cronworkflow zu Worker, library zu Library.

Resource-Entitäten werden ebenfalls zu Containern, typisiert über spec.type. RDS-Instanzen und Valkey-Cluster werden zu Datenbanken, Kafka-Topics und SQS-Queues zu Nachrichtenwarteschlangen, S3-Buckets zu Dateispeicher.

API-Entitäten werden zu Archyl-API-Verträgen. Die Inline-spec.definition bleibt wortgetreu erhalten, wird als HTTP, gRPC, GraphQL oder async typisiert und mit den Containern verknüpft, die sie bereitstellen und konsumieren.

dependsOn, consumesApi, producesTo, consumesFrom und versionedIn werden zu typisierten Beziehungen. Backstage gibt die meisten Relations in beide Richtungen aus, der Import behält eine davon. Eine consumesApi-Kante wird über die API bis zu dem Container aufgelöst, der sie tatsächlich bereitstellt.

Namespaces und Lifecycle

Deine metadata.tags kommen unverändert an, dazu namespace, lifecycle und type als präfixierte Tags, damit die Gruppierung, die du in Backstage gepflegt hast, im Architekturmodell überlebt.

Rufe die catalog-API deines Backstage auf und speichere die Antwort. Der entities-Endpunkt liefert jedes System, jede Component, jede Resource und jede API, die er kennt, als ein einziges JSON-Array.

Backstage-Format wählen

Wähle im Import-Dialog von Archyl den Tab "Backstage". Er nimmt das entities-Array genau so, wie Backstage es exportiert, ohne Umformung.

entities.json hochladen oder einfügen

Lade die Datei hoch oder füge sie ein und validiere anschließend. Archyl meldet alle Fehler im JSON, bevor du den Import startest.

Importieren und die Warnungen lesen

Archyl baut das Modell und meldet, wie viele Systeme, Container, API-Verträge und Beziehungen es angelegt hat, dazu jede Entität, die es umbenennen musste. Weise die Eigentümer danach zu: Backstage-Groups und -Users werden nicht importiert.

Erhalte einen Gesundheitswert von 0-100%, der zeigt, wie genau deine Dokumentation deine tatsächliche Codebasis widerspiegelt. Erkenne Drift, bevor er sich aufbaut.

Definiere Architekturregeln und führe automatisierte Prüfungen durch, um sicherzustellen, dass dein System innerhalb der definierten Leitplanken bleibt.

Verfolge Deployment-Häufigkeit, Vorlaufzeit, Fehlerrate und Wiederherstellungszeit zusammen mit der Gesundheit deiner Architektur.

MCP-Server (181 Tools)

Frage Architekturdaten von Claude, Cursor oder Windsurf über 181 spezialisierte MCP-Tools ab.

Architecture Decision Records

Verknüpfe ADRs direkt mit C4-Elementen, damit jede Designentscheidung einen nachvollziehbaren Kontext hat.

Hänge OpenAPI-, AsyncAPI- oder GraphQL-Schemas an Container und Komponenten an. Halte Verträge versioniert mit deiner Architektur.

Müssen wir Backstage verlassen?

Nein, und die meisten Teams sollten es nicht. Backstage ist ein Entwicklerportal; Archyl ist ein Architekturmodell. Der Import liest einen Katalog-Export und rührt deine Backstage-Instanz nie an, beide laufen also weiter. Archyl beantwortet die Fragen, die ein flacher Katalog nicht beantworten kann: wie diese Services zusammenpassen, was vom Code abgedriftet ist und welche Verträge brechen, wenn sich einer davon ändert.

Wie viele C4-Ebenen bekomme ich durch den Import?

Zwei. System-Entitäten landen auf C4-Ebene 1, und sowohl Component- als auch Resource-Entitäten landen als Container auf Ebene 2. Backstage hat keinen Entitäts-Kind unterhalb von Component, es gibt also nichts, womit sich Ebene 3 füllen ließe. Komponenten und Code-Elemente ergänzt du danach von Hand, oder du richtest die KI-Erkennung von Archyl auf das Repository und bestätigst, was sie vorschlägt.

Wird das Eigentum übernommen?

Nein. User- und Group-Entitäten werden übersprungen und ownedBy-Relationen werden nicht gemappt, spec.owner wird also nicht zu einem Eigentümer in Archyl. Das ist der eine Punkt, den du einplanen solltest: Wenn du die Eigentumskarte von Archyl nutzt, weist du die Eigentümer nach dem Import zu.

Was passiert mit unseren OpenAPI- und gRPC-Specs?

Eine API-Entität mit einer Inline-spec.definition behält diese Spec wortgetreu als Archyl-API-Vertrag, typisiert aus spec.type als HTTP, gRPC, GraphQL oder async, und verknüpft mit den Containern, die sie bereitstellen und konsumieren. Eine API-Entität ohne Inline-Definition kommt trotzdem mit Name, Beschreibung und Typ an, aber ohne Body.

Was überspringt der Import?

User- und Group-Entitäten samt der ownedBy-Relationen, die auf sie zeigen. Location- und Template-Entitäten. Die Blöcke metadata.annotations und metadata.links, womit auch der TechDocs-Verweis nicht ankommt. Relations außerhalb des gemappten Sets werden ignoriert. Vor doppelten und umbenannten Entitäten warnt dich der Import. Die oben genannten Kinds werden ohne Warnung verworfen, deshalb benennt diese Seite sie.

Unser Katalog hat Tausende automatisch erkannter Resources. Kommen die alle rein?

Ja. Jede Resource wird importiert, denn Daten, die du gepflegt hast, still zu verwerfen ist schlimmer, als zu viel zu importieren. Jeder Container behält ein type-Tag aus seinem Backstage-spec.type, die lauten Kategorien bleiben also erkennbar, und du kannst den Import schon an der Quelle mit Backstages filter-Query-Parameter eingrenzen, bevor du exportierst.

Können wir erneut importieren, wenn sich der Katalog ändert?