--- title: "Cloud Migration Trail Authoring Guide" description: "Cloud Migration Trail Authoring Guide: sequenzielle Architektur-Journey-Timelines im STACKIT Cloud Framework komponieren, strukturieren und verlinken." scfAsset: category: "guide" external: false tags: ["Trails", "Timelines", "Astro", "Blueprint"] maintainers: - user: "tobias.mueller" source_url: "https://framework.stackit.cloud/de/advisory/assetcontainer/stackit/howto-trail-setup/" source_file: "docs/de/advisory/assetcontainer/stackit/howto-trail-setup.mdx" --- Das Ausarbeiten umfassender Migrationspfade verbindet verstreute Einzel-Assets zu einer einheitlichen Workspace-Journey. Die zentrale Layout-Engine interpretiert strukturierte Parameter und baut daraus interaktive Timeline-Tracks für Entwickler. --- ## Ordnerstruktur und Lade-Anforderungen Damit der Loader eine Journey automatisch erkennt und registriert, müssen die Dokumente präzise Workspace-Dateipfade einhalten. - **Ziel-Speicherverzeichnis**: Speichere die Konfigurationsdatei im folgenden Verzeichnis des Workspace-Repos: ```text apps/docs/src/content/docs/[framework-slug]/trails/[contributor-slug]/[trail-slug].mdx ``` - **Erforderliche Konfigurations-Property**: Das Frontmatter muss den Basis-Schlüssel `scfTrail` enthalten. Fehlt er, überspringt der Indexierungs-Loader das Dokument, damit Work-in-Progress-Inhalte verborgen bleiben. - **Optionale Tags**: Bis zu 10 Tags unter `scfTrail.tags` (je max. 20 Zeichen) machen den Trail auffindbar. Die Card zeigt die ersten paar plus einen `+N`-Chip; alle Tags sind im Trail-Explorer durchsuchbar. --- ## Step-Phasen-Styles (`style`-Enum) Jeder Timeline-Step nimmt einen optionalen `style`-Schlüssel, der den Meilenstein mit seiner Journey-Phase markiert. Dies sind die vom Content-Schema validierten Werte: | Style-Schlüssel | Meilenstein-Phase | | :--- | :--- | | `compass` | **PLAN** — strategisches Alignment, Assessments und Migration-Discovery. | | `hut` | **BASE** — Baseline-Umgebung und Voraussetzungen. | | `stairs` | **STEP** — Engineering-Kernanforderungen und Plattform-Reife. | | `t-bar` | **LIFT (niedrig)** — inkrementelle Aktivierung von Capabilities. | | `chairlift` | **LIFT (mittel)** — Skalierung über Teams hinweg. | | `gondola` | **AUTO** — Continuous Delivery und automatisierte Workflow-Pipelines. | | `shield` | **SAFE** — Governance-Validierung, Security-Baselines und C5-Compliance. | | `crevasse` | **WARN** — Risiken, Fallstricke und Remediation-Checkpoints. | | `chart` | **OPS** — Observability, Kosten und operative Steuerung. | | `rocket` | **LIVE** — Produktiv-Launches und Go-Live-Meilensteine. | | `summit` | **GOAL** — Meilenstein-Abschluss, Übergabe und Monitoring. | Der `style`-Wert ist optional. Steps ohne ihn rendern weiterhin korrekt. --- ## Step-Konfigurationstypen Timeline-Items enthalten entweder eigene Beschreibungen oder dynamische Links zu Framework-Dokumenten. ### 1. Deskriptive Kontext-Items Ideal für Steps, die ein übergeordnetes Konzept oder eine Phase beschreiben, für die noch kein Code-Repository existiert. Der Autor liefert `title` und ein `description`-Feld manuell. ### 2. Verknüpfte Komponenten-Items Verweist über die Astro-ID (`assetId`) direkt auf ein dynamisches Codebeispiel oder Pattern. Der Parser ruft die Asset-Informationen ab, löst die Creator-Daten auf und rendert eine interaktive `SCFAssetCard` direkt auf dem Meilenstein-Track. Ein optionaler `#section-anchor` an der `assetId` bettet nur diesen Abschnitt des Assets statt des ganzen Dokuments ein, genau wie bei den Seiten-Referenzen unten (z. B. `.../assetcontainer/stackit/howto-contributors#directory-structure--asset-placement`). ### 3. Seiten-Referenz-Items Verknüpft über `pageId` eine reguläre Framework-Seite (kein Asset). Der Step rendert eine interaktive `SCFPageCard` und bettet den Seiteninhalt direkt in die Timeline ein. Ein optionaler `#section-anchor` rendert nur diesen Abschnitt der Seite statt des ganzen Dokuments, z. B. `migration/migrate/#core-modules-in-this-phase`. --- ## Steps als Unterpunkte verschachteln (`role`) Lange Trails arbeiten oft mehrere Abschnitte *derselben* Quelle ab, und wenn sich für jeden davon der volle Step-Kopf (Stage-Marker + Asset-Card + Contributor-Card) wiederholt, wird die Timeline unübersichtlich. Gib so einem Step **`role: sub`**, und er nistet als kompakte, mit Buchstaben (a, b, …) markierte Zeile unter dem nächsten vorherigen Hauptschritt — nur Titel und eine Zeile Kontext, kein Stage-Marker, keine Cards. Steps sind standardmäßig `role: main`, Bestandstrails bleiben also unverändert. - **Gruppierung** — Sub-Steps hängen sich an den Hauptschritt darüber. Ein `sub` ohne vorherigen Hauptschritt wird als Hauptschritt behandelt. - **Fremdquellen** — zeigt ein Sub-Step auf eine andere `assetId` / `pageId` als sein Hauptschritt, erscheint ein Quell-Chip in der Zeile und ein schlanker Source-Banner (Logo · Titel · Contributor · Kategorie · Öffnen-Link) über seinem Inhalt, damit der Leser die Herkunft kennt. Gleiche Quelle wie der Hauptschritt = nichts Zusätzliches. - **Alle aufklappen** — ein einzelner Button über der Timeline öffnet oder schließt alle Sub-Steps auf einmal. - **Präsentations-Bezug** — die `role` eines Steps ist auch die Standard-Agenda-Rolle, wenn der Trail präsentiert wird (siehe [Präsentations-Guide](/de/assets?asset=de/advisory/assetcontainer/stackit/howto-presentation)), sodass `sub`-Steps ohne Zusatzaufwand als eingerückte Unterpunkte durchkommen. ```yaml - style: "stairs" title: "Landing Zone bereitstellen" assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu" trailContext: "Der Accelerator stellt die Baseline bereit. Die nächsten Zeilen gehen seine Schichten durch." - role: "sub" title: "Module im Einzelnen" assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu#module-by-module-breakdown" trailContext: "Governance, Konnektivität und DevOps: was jedes Modul bereitstellt." - role: "sub" title: "Account-Governance" pageId: "migration/design-and-mobilize/design/account-governance" trailContext: "Eine andere Quelle, daher zeigt diese Zeile einen Source-Banner." ``` --- ## Einem Step ein eigenes Bild geben Ein Step kann ein Schaubild tragen. In der Timeline erscheint es unter dem Step; in der Präsentation wird es zur zweiten Spalte der Folie oder zu einem vollbreiten Cover. Zwei Felder steuern das Layout in beiden Fällen: - **`imagePosition`**: Weglassen zentriert das Bild — ein Cover, das die Folie unter dem Titel spannt, der Step-Text folgt darunter (`full` sagt dasselbe explizit). `right` oder `left` stellt das Bild stattdessen neben den Text. - **`imageWidth`**: die Breite der Bildspalte in Prozent für `left` / `right` (20–70, Standard 45). Bei zentrierten Covern ignoriert. Beide Felder sind optional, Bestandstrails funktionieren also unverändert weiter. Die andere Spalte ist der Inhalt, den der Step ohnehin zeigt — du wählst ihn mit den bekannten Feldern: ein `trailContext`-Absatz, ein Asset-Abschnitt via `assetId` mit `#section-anchor` oder ein Seiten-Abschnitt via `pageId` mit `#section-anchor`. "Bild rechts, Asset-Abschnitt links" sind also einfach beide Felder an einem Step: ```yaml - style: "gondola" title: "Migrate-Phase durchführen" pageId: "migration/migrate/#core-modules-in-this-phase" imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg" imageAlt: "Security-Themen, die die Migrate-Phase begleiten" imagePosition: right imageWidth: 40 ``` Das Bild selbst wird mit **`imageSrc`** benannt, einem Pfad relativ zum Content-Root, sodass du die Datei neben deinem Trail ablegen kannst: ```yaml - style: "shield" title: "Security und Compliance früh verankern" trailContext: "Die Themenkarte unten zeigt, was vor dem ersten Workload stehen muss." imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg" imageAlt: "Security- und Compliance-Themenkarte" imagePosition: full ``` `imageAlt` ist zugleich Alt-Text und Bildunterschrift. Erlaubt sind nur Bilder auf dieser Site — ein Pfad mit führendem `/` funktioniert auch, externe `http(s)`-Adressen werden bewusst ignoriert. Animierte SVGs funktionieren: Die in der Datei eingebackene Animation läuft in der Timeline und auf der Folie. --- ## Inhalt in Spalten platzieren (`left` / `right` / `center`) Die Bild-Felder oben sind die Abkürzung für „ein Inhalt plus ein Bild". Für volle Kontrolle über beide Seiten kann ein Step **beliebige** Inhaltstypen in benannte Slots legen — nicht nur Bilder. Jeder von `left`, `right` und `center` hält genau eine Sache: - **`text: "…"`** — freier Prosatext - **`assetId: "…"`** — eine Asset-**Card** (ein Zeiger). Mit einem `#section-anchor` wird stattdessen genau dieser eine Abschnitt eingebettet (die Card ist standardmäßig ausgeblendet; mit `cards: true` bleibt sie sichtbar). - **`pageId: "…"`** — eine Page-**Card** (ein Zeiger). Mit einem `#section-anchor` wird stattdessen genau dieser eine Abschnitt eingebettet (die Card ist standardmäßig ausgeblendet; mit `cards: true` bleibt sie sichtbar). - **`trailId: "…"`** — eine Trail-**Card** (ein Zeiger auf einen anderen Trail). - **`imageSrc: "…"`** (+ `imageAlt`) — ein Schaubild (Klick zum Zoomen) **Card = Zeiger, `#anchor` = Inhalt.** Das ist die Kernregel für Spalten: eine *nackte* `assetId` / `pageId` / `trailId` rendert nur die Card — einen kompakten Zeiger, der sagt „hier ist die Sache". Soll der Leser tatsächlich etwas von diesem Inhalt in der Spalte sehen, hänge einen `#section-anchor` an eine `assetId` oder `pageId`, und genau dieser eine Abschnitt wird eingebettet — **die Card ist dabei standardmäßig ausgeblendet**, sodass die Spalte nur den Abschnitt zeigt (an ihrer Stelle steht eine kompakte Herkunfts-Breadcrumb `Framework › Titel`, damit der Leser trotzdem sieht, woher er stammt). Trail-Cards sind immer Zeiger (ein Trail hat keine Abschnitte zum Einbetten). Ein ganzer Asset- oder Seiten-Body ist für eine Spalte zu hoch — willst du den vollständigen Inhalt im Deck, referenziere ihn als **flachen Step** (`assetId` / `pageId` auf Step-Ebene, nicht in einer Spalte). **Card zeigen mit `cards: true`.** Weil ein Step, der mehrere Abschnitte derselben Quelle stapelt, sonst vor jedem einzelnen dieselbe Card stünde, blendet eine Abschnitts-Spalte die Card standardmäßig aus. Willst du den Zeiger doch über dem Abschnitt sehen, setze **`cards: true`** auf die Spalte, dann erscheint er über dem eingebetteten Inhalt. Das Flag greift nur, wenn die Spalte wirklich einen Abschnitt trägt; ein nackter Zeiger behält seine Card immer und rendert damit nie als leere Spalte. **Mehrere Einträge in einem Slot.** `left`, `right` und `center` akzeptieren jeweils auch eine Liste. Die Einträge stapeln in der angegebenen Reihenfolge innerhalb der Spalte, getrennt durch einen dünnen Trenner, und sie dürfen aus verschiedenen Quellen kommen: drei Abschnitte eines Assets links, zwei Seiten rechts. Wo jeder Slot rendert: | Frontmatter | Layout | | :--- | :--- | | `left:` + `right:` | zwei Spalten nebeneinander (Split) | | nur `left:` | dieser Inhalt in der linken Hälfte, links | | nur `right:` | dieser Inhalt in der rechten Hälfte, rechts | | `center:` | dieser Inhalt zentriert als Cover | | nichts davon | der Step rendert wie zuvor (rückwärtskompatibel) | Unter ~900px stapeln die Spalten. Für einen Split setzt `splitRatio` die Breite der linken Spalte in Prozent (10–90, Standard 50). Timeline und Präsentationsfolie nutzen dasselbe Layout, was du hier komponierst, zeigt also auch das Deck. ```yaml # Split: ein Seiten-Abschnitt links, ein Asset rechts, 55/45 - style: "stairs" title: "Entscheidung, dann das umsetzende Werkzeug" splitRatio: 55 left: pageId: "migration/design-and-mobilize/design/overview/#decision-criteria-by-r-strategy" right: assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu" # Text links, ein Schaubild rechts - style: "shield" title: "Security früh verankern" left: text: "Die Themenkarte vor dem ersten Workload abbilden, nicht erst im Audit." right: imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg" imageAlt: "Security- und Compliance-Themenkarte" # Center: ein einzelnes Cover-Schaubild (oder zentrierter Text) - style: "chart" title: "Das ganze Terrain" center: imageSrc: "advisory/trails/stackit/getting_started/map-overview.svg" imageAlt: "Framework-Übersichtskarte" # Mehrere Abschnitte in einer Spalte: Cards standardmäßig aus, je unter der Herkunfts-Breadcrumb - style: "stairs" title: "Drei Schritte desselben Runbooks" splitRatio: 60 left: - assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu/#overview" - assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu/#deployment-flavours-and-what-they-enable" right: text: "Jeder Abschnitt behält seine Herkunfts-Breadcrumb, sodass der Leser die drei auseinanderhält, ohne drei identische Cards. Mit cards: true zeigst du die Zeiger-Card einer Spalte doch an." ``` --- ## Alternative Steps: alternative Spuren an einem Step (`alternatives`) Manchmal hat eine Etappe mehrere gleichwertige Wege: die VMs mit dem Standard-Guide migrieren, mit einem Live-Migration-Tool oder mit einem Replikations-Tool. Ohne Alternativen müsstest du drei Steps für eine Entscheidung bauen oder die Alternativen weglassen. Mit Alternativen bleibt der Step **ein Wegpunkt** (ein Titel, ein Stage-Marker, ein Agenda-Eintrag) und trägt mehrere **Spuren**, zwischen denen die Leser umschalten. - Das `assetId` / `pageId` des Steps (oder ohne beides sein `trailContext`-Text) ist die **Standard-Spur**. Für bestehende Trails ändert sich nichts: `alternatives` ist rein additiv. - Jede Alternative braucht eine stabile **`id`** (Deep-Links und Präsentations-Views hängen daran) und trägt genau eine der drei Inhaltsarten eines flachen Steps: ein **`assetId`**, ein **`pageId`** (beide mit optionalem `#section-anchor`) oder ohne beides reinen Text aus **`label` + `trailContext`**. - `label` ist der Name in der Auswahl; bei Asset- und Seiten-Spuren fällt er auf den referenzierten Titel zurück. - Ein eigener `trailContext` an einer Alternative ersetzt für diese Spur den des Steps. Er ist zugleich die Sprechernotiz dieser Spur in der Präsentation. - **Grenzen:** bis zu 4 Alternativen je Step und nur an flachen Haupt-Steps. Sub-Steps (`role: sub`) und Spalten-Steps (`left` / `right` / `center`) unterstützen keine Alternativen; der Validator sagt es dir, wenn du es versuchst. Auf der Seite rendert der Step seine aktive Spur genau wie ein normaler Step, mit den Asset- und Contributor-Karten der Spur. Eine leise Zeile unter den Karten („2 alternatives for this step") öffnet die Auswahl; ein Klick tauscht Karten und Inhalt an Ort und Stelle. Die Wahl landet als `?alt=:` in der URL (kommagetrennt über mehrere Steps), ein Link kann also eine bestimmte Route teilen — gib Alternative-Steps dafür eine eigene Step-`id`. „Copy for AI" exportiert immer die gerade gezeigte Spur und nennt die Alternativen. In der Präsentation bietet der Launch-Screen je Alternative-Step eine Spurauswahl (Voreinstellung ist, was die Seite gerade aktiv hat), und eine vorbereitete Ansicht kann per `alternative:` an ihrer Step-Referenz eine Spur festlegen — siehe den Präsentations-Guide weiter unten. ```yaml - style: "stairs" id: "migrate-vms" title: "Migrate the Virtual Machines" trailContext: "Move the compute layer in waves. Pick the alternative that matches your downtime budget." assetId: "migration/assetcontainer/stackit/migration-asset" alternatives: - id: "hystax" label: "Live migration with Hystax Acura" assetId: "migration/assetcontainer/hystax/hystax-acura-live-migration" trailContext: "For near-zero downtime windows." - id: "coriolis" assetId: "migration/assetcontainer/cloudbase/cloudbase-coriolis" - id: "manual" label: "Manual wave migration" trailContext: "Plan and execute the waves by hand with the runbooks." ``` --- ## Produktives Frontmatter-Blueprint Kopiere dieses Metadaten-Layout als Basis-Vorlage für eine neue Tracking-Timeline. Ergänze optional eine `maintainers`-Liste unter `scfTrail`, um die Maintainer als Ansprechpartner zu würdigen (über der Git-Historie angezeigt), dasselbe Feld nutzen auch Assets: Mit einem STACKIT-Git-Account trägst du dich nur mit dem Usernamen ein. Voller Name, Biography, Website und Adresse kommen aus deinem Git-Profil und werden täglich von der Pipeline gespiegelt. Die drei Schalter unten sind standardmäßig aus und folgen einer Regel: `true` nimmt den Wert aus dem Profil, ein String setzt ihn fest. ```markdown scfTrail: maintainers: - user: "jane.doe" ``` | Feld | Zweck | | :--- | :--- | | `user` | STACKIT-Git-Username. Schlüssel für das gespiegelte Profil und Rückfallanzeige, solange noch nichts gespiegelt wurde. | | `role` | Setzt den Rollentext wörtlich. Für Personen ohne Konto: bei einem `user` erscheint stattdessen die Biography aus dem eigenen Profil, und nur mit deren Freigabe. | | `website` | Setzt eine URL wörtlich, gleiche Regel wie `role`. | | `email` | Setzt eine Adresse wörtlich, gleiche Regel wie `role`. Sie erscheint als eigene Mail-Aktion und steht damit neben einem Profil-Link, statt mit ihm zu konkurrieren. | | `name` | Überschreibt den gespiegelten Namen und würdigt Personen ohne Git-Account. Damit wird der Eintrag zur Person: Initialen-Avatar, Rollenzeile *Rolle · Organisation*. | | `contributor` | Slug eines `/contributors/`-Profils, für Personen ohne Konto. Allein gesetzt würdigt es die Organisation mit Profiltitel, Logo-Initialen und offiziellem Partner-Kennzeichen. Neben einem `user` wird es ignoriert, dessen Organisation kommt aus der Zuordnungsdatei. | | `link` | Ein Profil- oder Homepage-Link, typischerweise LinkedIn. Er hat Vorrang vor der gespiegelten Website und vor dem Contributor-Profil. | Jedes Feld ist einzeln optional und beliebig kombinierbar; ein Eintrag braucht nur mindestens `user`, `name`, `contributor` oder `email`, und pro Trail sind bis zu **6** Einträge erlaubt. Felder, die das Schema nicht kennt, werden ohne Fehler verworfen: ein Tippfehler lässt den Build grün und zeigt nichts an. Maintainer sind eine Würdigung, keine Berechtigung, die Liste schränkt also nicht ein, wer den Trail bearbeiten darf. Der [Asset-Integrations-Leitfaden](/de/advisory/assetcontainer/stackit/howto-asset-integration#maintainer-würdigen) zeigt zusätzlich, wie externe Partner ohne Account gewürdigt werden. ```markdown --- title: "Standard Kubernetes Onboarding Track" description: "A comprehensive guided journey trail directing engineering workloads from legacy virtualization targets into sovereign managed STACKIT clusters." scfTrail: # Optional: Maintainer als Ansprechpartner würdigen (über der Git-Historie angezeigt). maintainers: - name: "Jane Doe" role: "Trail Owner" steps: - style: "compass" title: "Initial Assessment Phase" trailContext: "Analyze workload traits and infrastructure requirements before initializing resources." - style: "gondola" assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu" trailContext: "Deploy the landing zone automated profile using standardized infrastructure code scripts." - style: "stairs" title: "Execute the Migration Modules" trailContext: "Work through the core migration modules; the optional #anchor renders only that page section." pageId: "migration/migrate/#core-modules-in-this-phase" - style: "summit" title: "Final Cluster Validation" description: "Review compliance policies and confirm that all configuration checks pass security rules." --- ``` --- ## Referenz-Links in unterstützenden Seiten Die Trail-Datei selbst ist frontmatter-only, deshalb greift die Link-Regel dort nie: Text in `trailContext` und in Spalten-`text` wird als reiner Text gerendert, Links eingeschlossen. Sie gilt aber für die **Asset- und Content-Seiten, auf die deine Steps zeigen**: dort muss jeder Verweis, der auf einer eigenen Zeile steht, eine `` oder ein `` sein — beide automatisch importiert, beide leiten ihre Art (Portal, Marketplace, Dokumentation, Code, Drittanbieter) allein aus der URL ab. Die PR-Pipeline blockiert nackte alleinstehende Links in geänderten Dateien und prüft, dass interne Karten- und Chip-Ziele existieren. Die vollständige Regel steht im [Asset Integration Guide](/de/advisory/assetcontainer/stackit/howto-asset-integration). --- ## Einen Trail präsentieren Jeder Trail lässt sich über den Präsentations-Button in seiner Detailansicht als Foliendeck öffnen — kein zusätzliches Frontmatter nötig. Als Autor kannst du zusätzlich **vorbereitete Ansichten** (kuratierte Folien-Auswahlen) definieren, das Start-Verhalten vorpresetten und das Bild eines Steps zu einer Split-Folie machen. All das lebt in einem `presentations`-Block unter `scfTrail` und ist in einem eigenen Guide dokumentiert: dem **[Präsentations-Guide](/de/assets?asset=de/advisory/assetcontainer/stackit/howto-presentation)**. --- ## SCF Studio Nutze das **SCF Studio**, um einen Trail zu bauen, ohne YAML von Hand zu schreiben. Starte die Docs (`hike`) und öffne `/studio` in deinem Dev-Container, oder nutze es auf der Dev-Seite. Es baut die Steps, löst jedes Asset und jede Seite auf, auf die du zeigst, und es kann einen bestehenden Trail laden und nur das ändern, was du bearbeitest. --- ## Live Component Playground (lokaler Dev-Server) Starte die Docs lokal (VS-Code-Task **🥾 Hike — Start Dev Docs** oder das `hike`-Kommando im Container-Terminal, ausgeliefert auf `http://localhost:4321`) und öffne die interaktiven Playgrounds, um die Trail-Komponenten live gerendert zu sehen: - **Trail Loader** — das automatisch erkannte, höhengleiche Trail-Grid genau wie via `` eingebettet, inklusive Inline-Detailansicht: `http://localhost:4321/demo/components/demo-scf-trail-loader` - **Trail (einzelne Timeline)** — die vollständige interaktive Meilenstein-Timeline mit Accordion-Asset-Cards, die `style`, `assetId`, `title` und `trailContext` pro Step demonstriert: `http://localhost:4321/demo/components/demo-scf-trail` --- ## Zentrale Übersicht

Zur Cloud-Framework-Trails-Übersicht

Zurück zum zentralen Verzeichnis mit allen live gerenderten, interaktiven Migrations-Journeys und Entwickler-Tracks.