Ga naar inhoud

Shared services: wat is uitgerold en hoe

Deze pagina is voor het platformteam. Ze beschrijft wat de code van de shared services uitrolt, hoe die wordt geconfigureerd en hoe de deployment-pipeline werkt. De kant van het workload team staat op Shared services. De extensies die een spoke met deze services verbinden, worden beschreven op Spoke-extensies.

Wie "het platformteam" is, hangt af van je beheermodel: XMMS in het managed model, je eigen team in het zelfbeheermodel.

Referentieontwerp, jouw deployment kan afwijken

Shared services maken geen deel uit van de core MCP hub en spoke (Servicetypen). De feiten hieronder komen uit de Terraform-code en pipeline van één referentie-implementatie. Resourcenamen, groottes en de set addons die je draait kunnen verschillen. Waarden in voorbeelden zijn placeholders.

Hoe het in elkaar zit

flowchart LR
    code["Shared services code<br/>(Terraform, one folder per addon)"] --> pipe["Deployment pipeline<br/>(plan, then apply)"]
    cfg["Shared services configuration<br/>(one variables file per addon and environment)"] --> pipe
    pipe -->|"service connection"| spoke["Shared services spoke<br/>(spoke canvas: VNet, Key Vault, Log Analytics)"]
    spoke --> svc["Addons: gateway, registry, API Management,<br/>messaging, communication, build agents"]
    ws["Workload spokes"] -->|"spoke extensions<br/>(roles, groups, identities)"| svc

Twee repositories werken samen:

Repository Inhoud
Shared services-code Herbruikbare Terraform per addon in infra/<addon>/, en de pipeline-templates in pipelines/templates/
Shared services-configuratie De omgevingsspecifieke waarden (variables.tfvars) per addon

De code bevat geen omgevingswaarden. Een deployment combineert één addonmap van de code met het bijbehorende variabelenbestand van de configuratie. De coderepository heeft een workflow die bij elke push naar main en bij tags die beginnen met v een downstream-synchronisatie triggert. Zie Codesynchronisatie voor het mechanisme.

Wat de code uitrolt

De shared services worden in een bestaande spoke gebouwd. Elke addon leest de resource group, het virtual network, het subnet, de Key Vault en de Log Analytics workspace van die spoke op naam (variabele spoke_config), dus de spoke moet bestaan voordat je een addon uitrolt (Spoke-deployment).

Addon (map in infra/) Wat het uitrolt Toegang die het aanmaakt
appgw Application Gateway met WAF-policies, publiek IP, user-assigned identity, Key Vault voor certificaten De gatewayidentiteit krijgt Key Vault-rollen. Zie hieronder
acr Container registry uit modules (Premium, private endpoint, customer-managed key) Optionele roltoewijzingen voor groepen die je op object-ID meegeeft
acr-alt Container registry, zelfstandig (Premium, private endpoint, customer-managed key) Maakt een AcrPull- en een AcrPush-groep aan
apim API Management, Application Insights met een eigen Log Analytics workspace, optionele developer portal Monitoring Reader-groep, optionele groep voor portal content editors
event-hub-namespace Event Hubs-namespace en event hubs, private endpoint, customer-managed key Een sender-groep en een receiver-groep per event hub
service-bus Service Bus-namespace (Premium), private endpoint, optionele customer-managed key Een contributors-groep op de namespace
acs Azure Communication Services en Email Communication Services, met domeinen Een contributors-groep
cae-agents Self-hosted Azure Pipelines agent pool op Container Apps jobs Managed identity met AcrPull en administrator op de pool. Zie Container agent pool

Groepen worden aangemaakt in de administrative unit die je meegeeft (administrative_unit_id), de unit van de landing zone.

Gemeenschappelijke beveiligingsinstellingen

Instelling Waar
Publieke netwerktoegang uitgeschakeld, toegang via een private endpoint Registry, Service Bus, Event Hubs, Key Vault van de gateway. API Management in de StandardV2 SKU (zie hieronder)
Lokale authenticatie (keys, SAS) uitgeschakeld Service Bus (local_auth_enabled = false), Event Hubs (local_authentication_enabled = false), Application Insights en zijn workspace
Registry: admin user uit, anonymous pull uit, export policy uit acr en acr-alt
Customer-managed key in de Key Vault van de spoke Registry, Event Hubs, Service Bus (als customer_managed_key_enabled true is)
RBAC-autorisatie, purge protection aan Key Vault van de gateway

De customer-managed keys zijn RSA 2048-sleutels met een vervaldatum een jaar na aanmaak, een automatisch rotatiebeleid en een melding vóór het verlopen. De private DNS zone group van de private endpoints wordt niet door de code beheerd (ignore_changes op de private endpoint, of private_endpoints_manage_dns_zone_group = false): DNS-registratie komt van het platform (Dekking van private endpoint DNS). Controleer of je platform de services dekt die je uitrolt.

Naamgeving en omgevingen

Elke addon ondersteunt twee naamgevingsmodi:

Modus Variabelen Voorbeeldresultaat
Omgevingsgebaseerd (aanbevolen voor nieuwe deployments) environment (maximaal 7 tekens) en location_short apim-nonprod-weu-001, resource group rg-apim-nonprod-weu-001
Legacy resource_postfix apim-<postfix>-001

De omgevingsgebaseerde namen worden alleen gebruikt als zowel environment als location_short zijn ingesteld. Bestaande deployments die resource_postfix gebruiken, plannen zonder wijzigingen. Een bestaande deployment van de ene modus naar de andere verplaatsen wijzigt de namen, dus Terraform maakt nieuwe resources aan: plan een migratie (nieuwe deployment, datamigratie, opruimen) en schakel niet over door de variabelen te bewerken. De Application Gateway-addon heeft geen legacy-modus: environment en location_short zijn verplicht.

Service Resourcenaampatroon (omgevingsgebaseerd)
Resource group rg-<service>-<environment>-<location_short>-001
API Management apim-<environment>-<location_short>-001
Service Bus-namespace sbns-<environment>-<location_short>-001
Event Hubs-namespace ehns-<environment>-<location_short>-001
Container registry (acr-alt) acr<environment><location_short>001 (koppeltekens verwijderd)
Communication Services acs-<environment>-<location_short>-001, e-mailservice ecs-...
Application Gateway agw-<environment>-<location_short>-001

Draai niet-productie en productie als aparte deployments: aparte subscriptions, aparte Terraform state-bestanden (bijvoorbeeld apim-nonprod.tfstate en apim-prod.tfstate) en aparte groepen. De voorbeeldwaarden in de coderepository verschillen per omgeving, bijvoorbeeld:

Instelling Voorbeeld niet-productie Voorbeeld productie
API Management SKU en units StandardV2, 1 Premium, 2, zones 1, 2, 3
Event Hubs Standard, capacity 1, 2 partities, retentie 1 Standard, capacity 2, auto-inflate tot 10 throughput units, 4 partities, retentie 7
Service Bus capacity 1, 1 messaging partition capacity 2, 4 messaging partitions
Registry (acr-alt) Geen data endpoint, quarantine, zone redundancy of trust policy, retentie 7 Data endpoint, quarantine, zone redundancy en trust policy aan, retentie 30

Beschouw deze als voorbeelden uit de deploymentgids van de repository, niet als standaardwaarden.

Notities per addon

Application Gateway (appgw)

Referentieontwerp: de gateway wordt in een spoke uitgerold, in het subnet AppGwSubnet van het virtual network van de spoke. De code maakt aan:

Resource Opmerkingen
Resource group rg-agw-<environment>-<location_short>-001 Bevat alle onderstaande resources
Publiek IP Standard SKU, statisch, zones 1, 2 en 3. Optioneel DNS-label (public_ip_dns_name). DDoS-bescherming staat standaard aan (use_ddos_protection_plan), waarvoor de plannaam, resource group en subscription nodig zijn (ddos_protection_plan, ddos_protection_plan_subscription_id).
Application Gateway Zones 1, 2 en 3. Een user-assigned identity. Al het andere komt uit JSON-bestanden.
User-assigned identity Krijgt Key Vault Certificates Officer en Key Vault Secrets User op de Key Vault van de gateway
Key Vault kv-agw-<environment>-<location_short>-<random> RBAC, purge protection, 7 dagen soft delete, publieke toegang uitgeschakeld, private endpoint in het subnet uit spoke_config.subnet_pe_name
WAF-policies Eén per JSON-bestand. Zie WAF-uitzonderingen

Een optioneel privé-frontend-IP wordt ingeschakeld met enable_private_ip en private_ip_address.

De gatewayconfiguratie is JSON, in de map die is ingesteld met application_gateway_json_file_relative_path (standaard gateway-definitions/, patroon *.json). Bestanden hebben een application_gateway-object op het hoogste niveau. De secties van alle bestanden worden sectie voor sectie samengevoegd (backend pools, HTTP settings, frontend ports, listeners, routing rules, probes, certificates, URL path maps, redirects, rewrite rules, SKU en autoscale, TLS policies en profiles). Plan met elke sectie aanwezig, want de module leest elke sectie rechtstreeks. De structuur van een workloaditem is dezelfde als beschreven in Application Gateway (een workload toevoegen of wijzigen).

De gateway gebruikt de WAF-policy die uit het bestand web_application_firewall_policy_hub.json komt (de bestandsnaam bepaalt de policy key). Andere WAF-policybestanden maken policies aan waar een listener of path rule via resource-ID naar kan verwijzen.

Deze addon zit niet in de deployment-pipeline van de coderepository (zie Pipeline). Hoe hij in jouw platform wordt uitgerold, is in de bronnen niet gedocumenteerd.

Twee gateway-implementaties

De MCP hub kan ook een Application Gateway uitrollen vanuit de connectivity layer (Platformresources). De shared services-addon hierboven is een aparte implementatie met andere resourcenamen en instellingen. Weet welke van de twee je platform gebruikt voordat je een runbook volgt. De verschillen staan op Application Gateway.

Container registry (acr, acr-alt)

Beide maken een Premium registry aan met admin user, anonymous pull en export uitgeschakeld, publieke netwerktoegang uitgeschakeld, een private endpoint en encryptie met een customer-managed key (met een user-assigned identity die Key Vault Crypto Service Encryption User heeft op de Key Vault van de spoke).

acr acr-alt
Structuur Modules (container-registry, private_endpoint, role_assignments) aangeroepen vanuit deploy/ Eén zelfstandige map
Groepen Je geeft de object-ID's van maximaal zeven groepen mee (Owner, Contributor, Reader, AcrPush, AcrPull, AcrDelete, AcrImageSigner). Elke rol wordt alleen toegewezen voor een groep die je meegeeft. Maakt twee groepen aan (namen uit acr_pull_group_name en acr_push_group_name) met AcrPull en AcrPush
Registry-instellingen data_endpoint_enabled en quarantine_policy_enabled staan in deploy/ vast op false container_registry_config: data endpoint, quarantine, zone redundancy, retentiedagen (standaard 7), trust policy
Terraform-root infra/acr/deploy infra/acr-alt

De pull- en pushgroepen van acr-alt zijn de hoofdgroepen die de ACR-spoke-extensie verwacht (acr_pull_group_object_id en acr_push_group_object_id in het blok shared_services, zie Spoke-extensies). De bronnen zeggen niet welke variant de huidige is. De code bevat geen pull-through cache-regels voor publieke registries: als de registry op jouw platform Microsoft Container Registry of Docker Hub cachet, is dat elders geconfigureerd.

API Management (apim)

Onderwerp Gedrag
SKU StandardV2 of Premium. Units 1 tot 10 voor StandardV2, 1 tot 99 voor Premium. Availability zones alleen met Premium.
Netwerk Premium: virtual network-type Internal, geen private endpoint. StandardV2: type External met een private endpoint, en publieke netwerktoegang wordt na de eerste aanmaak uitgeschakeld (de eigenschap kan niet worden ingesteld als de service wordt aangemaakt, dus de code controleert of de service bestaat).
Identiteit Een system-assigned en een user-assigned identity
Telemetrie Application Insights (lokale authenticatie uitgeschakeld) op een eigen Log Analytics workspace, met een API Management-logger die de managed identity gebruikt. Optionele diagnostic settings naar de workspace van de spoke (diagnostic_settings). De retentie van Application Insights is standaard 90 dagen.
Developer portal Standaard uit (developer_portal.enabled). Als hij aan staat: basic authentication uit, aanmelden vereist, optionele gebruiksvoorwaarden, optionele groep voor content editors.
Toegang Een groep met Monitoring Reader op Application Insights (application_insights_monitoring_readers_group_name)
Custom domain Niet uitgerold. Het bestand custom_domain.tf is uitgecommentarieerd.

De API-definities en producten voor ontwikkelaars, en het gebruik van API Management als integratiebouwsteen, worden beschreven in het Integration Platform.

Event Hubs en Service Bus

Onderwerp Event Hubs (event-hub-namespace) Service Bus (service-bus)
SKU Ingesteld met event_hub_namespace_config (sku, capacity, auto-inflate, maximum throughput units) Premium (nodig voor customer-managed keys en private endpoints). capacity 1, 2, 4, 8 of 16. messaging_partitions 1, 2 of 4.
Inhoud Eén event hub per item in event_hub_config (naam, aantal partities, retentie in dagen, status) De namespace. Queues en topics worden niet door deze code aangemaakt.
Netwerk Private endpoint, network rule set default action Deny, trusted services uit Private endpoint, publieke toegang uit, trusted services uit
Groepen Per event hub: een sender-groep (Azure Event Hubs Data Sender) en een receiver-groep (Azure Event Hubs Data Receiver en Contributor) op die event hub Een contributors-groep met Contributor op de namespace
Encryptie Altijd customer-managed key Customer-managed key als customer_managed_key_enabled true is (standaard false)

De spoke-extensies voegen daar de rollen voor de spokes bovenop toe (Spoke-extensies). De messaging-services als integratiebouwstenen worden behandeld in het Integration Platform.

Communication Services (acs)

Maakt een Communication Services-resource en een Email Communication Services-resource aan in de datalocatie die je kiest (data_location), een door Azure beheerd e-maildomein (deploy_managed_domain, standaard false) en één door de klant beheerd domein voor elke naam in customer_managed_domains. Diagnostic settings sturen de e-maillogs (send mail, status update, user engagement) naar de workspace van de spoke. Een groep met Contributor geeft toegang. De codecommentaren zeggen dat de groep nodig is totdat spoke- extensies voor deze service beschikbaar zijn, wat overeenkomt met Spoke-extensies.

Container agent pool (cae-agents)

Zie Container agent pool.

Pipeline

De referentiepipeline pipelines/deployment.yaml rolt geselecteerde addons uit. Hij checkt de code en de configuratie- repository naast elkaar uit en heeft per addon één booleaanse parameter:

Parameter Addonmap State key
deployACR infra/acr acr-deploy.tfstate
deployAPIM infra/apim apim-deploy.tfstate
deployACS infra/acs acs-deploy.tfstate
deployEVHN infra/event-hub-namespace evhn-deploy.tfstate
deployASB infra/service-bus asb-deploy.tfstate
deployCAEAgents infra/cae-agents cae-agents-deploy.tfstate

Er is ook een parameter branch, om een branch of tag van de coderepository uit te rollen. Er is geen parameter voor appgw en acr-alt.

Hoe een run werkt:

  1. Plan stage: één job per geselecteerde addon. Terraform wordt geïnstalleerd (de referentie pint versie 1.9.3), de state-backend (resource group, storage account, container) wordt aangemaakt als hij niet bestaat, terraform init en terraform plan draaien met het variabelenbestand van de addon uit de configuratierepository, en het plan wordt als pipeline-artifact gepubliceerd.
  2. Apply stage: één stage per addon, die van de plan stage afhangt. De stage draait als deployment job tegen een Azure DevOps-environment, dus goedkeuringen en checks op die environment zijn van toepassing. Hij downloadt het plan-artifact en past exact dat plan toe, en publiceert de Terraform-output als artifact.
  3. Voor cae-agents start een extra job na de apply de placeholderjob van de agent pool.

Authenticatie loopt via de Azure DevOps service connection. De template gebruikt een federated token (OIDC) als de service connection er een levert, anders het client secret van de service principal. De state staat in een Azure Storage-account met Microsoft Entra ID-authenticatie.

De pipeline leest deze waarden uit een variable group: de naam van de service connection, de doelsubscription, de resource group, het storage account en de container van de state, en, voor de agent pool, de workloadnaam en resource postfix. De agent pool heeft ook een personal access token nodig voor de Azure DevOps Terraform provider (Container agent pool).

De README van de coderepository laat ook zien hoe je twee pipelines voor één addon draait, met een andere omgeving, subscription, state key en variabelenbestand (-var-file=nonprod.tfvars, -var-file=prod.tfvars). De referentiepipeline rolt één omgeving uit, in Azure DevOps prod genoemd.

Controleer de pipeline voordat je erop vertrouwt

Delen van de referentiepipeline lijken niet te kloppen met de indeling van de code: de registryjob wijst naar infra/acr, terwijl de Terraform-root infra/acr/deploy is, en de paden van de variabelenbestanden verschillen per job (../config/... tegenover ../../../config/...). De template die de state-backend aanmaakt staat ook publieke blobtoegang toe op een storage account dat hij aanmaakt. Test een plan voor elke addon en review de instellingen van het state storage account voordat je in productie gaat.

Beheren

Taak Hoe
Een instelling wijzigen Wijzig het variabelenbestand in de configuratierepository (of de code), draai de pipeline voor de addon en review het plan.
Een addon of een tweede instance toevoegen Maak een variabelenbestand en een state key aan. Volg het naampatroon met environment en location_short, houd de variabelen optioneel met null-defaults en laat de legacy-naamgeving werken.
Een workload verbinden Schakel de spoke-extensie in (Spoke-extensies). Daarvoor is de resource-ID van de service in shared_services nodig.
Een servicespecifieke rol aan een groep geven Voeg het lid toe aan de groep die de addon heeft aangemaakt. Leden die je met de hand aan deze groepen toevoegt, worden niet door de extensies verwijderd.
Een mislukte apply onderzoeken Lees het plan-artifact en de Terraform-output van de stage.
De customer-managed keys controleren Ze staan in de Key Vault van de spoke en zijn vernoemd naar de service (bijvoorbeeld <resource name>-encryption-key; de module acr gebruikt <registry name>-managedkey-001). Ze hebben een rotatiebeleid. Controleer hun vervaldatums.