Catalog en entiteitenmodel

Het portaal is gebouwd op de Backstage software catalog. De catalog is de ruggengraat van elke andere functie: de weergaven voor kosten, security, compliance en netwerk, en de agents, beginnen allemaal bij een entiteit in de catalog en volgen de relaties ervan. Deze pagina legt uit welke entiteitstypen er zijn, hoe ze worden gevuld vanuit Azure en Entra ID, en wat een workload team moet doen zodat de workload met de juiste eigenaar zichtbaar wordt.

Entiteitstypen

Kind	API-versie	Betekenis	Aangemaakt uit
Workload	xebia.com/v1	Een applicatie, service of capability die cloudresources gebruikt. De eenheid waarmee de meeste weergaven beginnen.	Getagde Azure-subscriptions, optioneel verrijkt vanuit repositorybestanden
Domain	backstage.io/v1alpha1	Een bedrijfsgebied dat workloads groepeert	De domain-tag op subscriptions, of een repositorybestand
Organisation	xebia.com/v1	Een klant of interne organisatie die een of meer domeinen beheert	De organisation-tag op subscriptions. Domeinen zonder tag vallen terug op één standaardorganisatie.
Group	backstage.io/v1alpha1	Een team, als security group in Entra ID	Microsoft Graph
User	backstage.io/v1alpha1	Een persoon	Microsoft Graph
Fragment	xebia.com/v1	Een gedeeltelijke beschrijving van een andere entiteit, gebruikt om meerdere bronnen samen te voegen	De Azure-providers en repositorybestanden
Customer	xebia.com/v1	Een klant van de leverancier, met een eigenaar	Catalog-bestanden. Dit kind wordt alleen geladen in de eigen omgeving van de leverancier

Een workload heeft deze vorm:

apiVersion: xebia.com/v1
kind: Workload
metadata:
  name: my-workload
spec:
  owner: group:default/my-team   # required, a Group
  dependsOn:                     # optional, other workloads
    - other-workload
  domain: platform               # optional
  externalUris:                  # optional, see Network insights
    - https://api.example.com
    - https://api.example.com/orders

Alleen owner is verplicht. Alle stringvelden hebben een minimale lengte. De catalog weigert entiteiten die niet valideren.

Relaties

De catalog processor maakt deze relaties aan op basis van de Workload spec.

Uit de spec	Relatie (en inverse)
owner	ownedBy / ownerOf tussen workload en groep
dependsOn	dependsOn / dependencyOf tussen workloads
domain	partOf / hasPart tussen workload en domein

De weergaven gebruiken een hiërarchie van vijf niveaus: organisatie, domein, team, workload, subscription. Een kosten-, security- of complianceweergave voor een domein of team is de samenvatting van de workloads en hun subscriptions.

Subscription-annotaties

Een workload wordt aan zijn Azure-subscriptions gekoppeld met annotaties van de vorm azure.com/subscription-selector.<key>, met als waarde <tenant-id>/<subscription-id>. De key benoemt een slot, bijvoorbeeld één per omgeving. Alle Azure-plugins lezen deze annotaties om te weten welke subscriptions ze moeten bevragen. Een workload met meer dan één subscription (bijvoorbeeld non-productie en productie) toont elke subscription apart en de som per workload.

Hoe entiteiten in de catalog komen

flowchart LR
    arg["Azure Resource Graph<br/>subscription tags and<br/>Application Gateway listeners"] --> frag["Fragment entities"]
    ado["Azure DevOps<br/>catalog-info.yaml files"] --> frag
    frag --> merge["Merged Entities module<br/>groups by kind, namespace, name"]
    merge --> wl["Workload, Domain,<br/>Organisation entities"]
    wl --> proc["Entity model module<br/>validates, adds relations"]
    graph["Microsoft Graph<br/>users and groups"] --> cat["Catalog"]
    proc --> cat

De Backstage catalog accepteert een entiteit één keer per kind, namespace en naam. Een tweede bron met dezelfde naam zou als conflict worden geweigerd. Het portaal laat daarom elke bron een Fragment van de entiteit beschrijven, en een Merged Entities-module combineert de fragmenten tot één entiteit voordat de catalog die verwerkt.

Stap	Wat er gebeurt
1	De Azure Resource Graph-module leest subscriptions en leidt workload-, domein- en organisatiefragmenten af uit de tags. Een tweede provider leest hostnamen van Application Gateway-listeners en leidt daar fragmenten uit af. Beide draaien volgens een schema dat in de configuratie is ingesteld. De gedeelde productieconfiguratie stelt één uur in voor de Application Gateway-provider.
2	De Azure DevOps catalog-provider leest catalog-info.yaml-bestanden uit repositories (elke 30 minuten in de referentieconfiguratie) en kan fragmenten of entiteiten toevoegen.
3	De merged entity provider vraagt de catalog om alle fragmenten, groepeert ze per doelkind, namespace en naam en voegt ze samen tot één entiteit. Fragmenten uit een YAML-bestand winnen van andere fragmenten. Binnen elke groep is de volgorde op fragmentnaam, zodat het resultaat stabiel is.
4	De entity model-module valideert de Workload en maakt de relaties aan.

Een fragment heeft dezelfde envelop als de doelentiteit, maar alleen apiVersion, kind en metadata.name zijn verplicht, zodat een bron alleen de velden kan leveren die hij kent:

apiVersion: xebia.com/v1
kind: Fragment
metadata:
  name: my-unique-fragment-name
spec:
  apiVersion: xebia.com/v1
  kind: Workload
  metadata:
    name: my-target-entity-name
  spec:
    # only the fields this source knows

Fragmenten kunnen een Workload, een Domain of een Organisation als doel hebben.

Tags die de catalog aansturen

De Azure-provider leest deze tags op subscriptions. De standaardnamen kunnen in de providerconfiguratie worden gewijzigd (Configuratie).

Tag (standaard)	Effect
workload	Markeert een subscription als onderdeel van een workload en benoemt die
owner	De eigenaargroep van de workload
domain	Het domein van de workload (optioneel)
organisation	De organisatie waartoe het domein behoort (optioneel)
name	Een leesbare titel voor de entiteit (optioneel)
description	Een beschrijving (optioneel)
external-uris	Kommagescheiden lijst met absolute HTTP- of HTTPS-URI's die bij de workload horen, gebruikt om Application Gateway WAF-logs te koppelen (optioneel)

Opmerkingen over external-uris:

• Witruimte rond items wordt genegeerd en ongeldige items worden weggelaten.
• De URI's van alle subscriptions van dezelfde workload worden samengevoegd en op de workload opgeslagen als spec.externalUris.
• Voorbeeld: https://api.example.com, https://api.example.com/orders.

Spokes van het platform

Een spoke die het platform uitrolt, heeft al de tags workload en owner (zie de verplichte tags in de Spoke JSON-referentie en Naamgeving en tags). Daarnaast zet de spoke-deployment een verborgen tag met JSON-metadata:

{
  "workloadShortName": "<workload>",
  "productTeamGroupNames": ["<team group name>"]
}

De provider leest workloadShortName als de workload en het eerste niet-lege item van productTeamGroupNames als de eigenaar. Omdat de spoke-deployment dit vult, heeft een spoke geen extra handmatige tags nodig om in de catalog te verschijnen. Ongeldige JSON wordt met een waarschuwing genegeerd.

Welke bron wint als zowel de verborgen tag als de gewone tags bestaan, wordt bepaald door de optie spokeMetadataOverridable (standaard false: de verborgen metadata wint, de gewone tags zijn de terugval. true draait dat om). Houd de standaardwaarde aan voor spokes van het platform.

Gebruikers en groepen

Gebruikers en groepen worden ingelezen uit Microsoft Graph (in de referentieconfiguratie: ingeschakelde gebruikers en security-enabled groepen, één keer per uur). Het portaal meldt gebruikers aan door het e-mailadres van de aanmelding te koppelen aan een User-entiteit, zie Authenticatie en toegang.

Eigenaarwaarden in tags kunnen gewone groepsnamen of entiteitsverwijzingen zijn. Als de feature flag features.microsoftGraphGroupNameNormalization aanstaat, past het portaal een naamconventie toe op Entra ID-groepsnamen:

Invoer	Resultaat
Gewone eigenaartag, bijvoorbeeld SG-AZ-LZ_<org>_engineers	Met de conventie omgezet naar een groep in een namespace die uit de naam wordt afgeleid (bijvoorbeeld group:sg-az-lz-<org>/engineers)
Entiteitsverwijzing, bijvoorbeeld group:default/Some_Group	Structuur blijft behouden, normalisatie in catalog-stijl wordt toegepast op de delen
Flag uit	Gewone tag omgezet naar group:default/<genormaliseerde naam>

Naamconventie voor groepen

Met de flag aan wordt een groep alleen ingelezen als de naam eindigt op _engineers, _users, _admins of _standard_changes (na normalisatie). Groepen met andere namen worden door de transformer weggelaten en kunnen geen workload beheren. Deze conventie is specifiek voor de groepsnaamgeving van de leverancier. Controleer haar voordat je de flag voor een andere klant inschakelt.

Wat een workload team doet

1. Zorg dat de subscription van de workload de tags workload en owner heeft. Voor spokes van het platform gebeurt dit bij de uitrol.
2. Voeg de domain-tag toe als de workload bij een domein hoort, en external-uris als de workload achter een Application Gateway met WAF staat.
3. Voeg optioneel een catalog-info.yaml toe aan een repository om beschrijvingen, afhankelijkheden of documentatie toe te voegen. Die wordt bij de volgende scan opgepikt.
4. Wacht op de volgende run van de providers (tot een uur voor tags, tot dertig minuten voor repositorybestanden in de referentieconfiguratie) voordat je naar de wijziging zoekt.

Als een workload geen eigenaar heeft, of een eigenaar die niet als groep bestaat, kunnen de insight-weergaven de kosten niet toewijzen en tonen ze die als UNKNOWN, en niemand kan het gevoelige detail ervan zien (Authenticatie en toegang).

Gerelateerd

• Insights
• Configuratie
• Naamgeving en tags