Parameters en uitvoer toevoegen aan modules

  • 7 minuten

Elke module die u maakt, moet een duidelijk doel hebben. U kunt een module beschouwen als een contract. Er wordt een set parameters geaccepteerd, er wordt een set resources gemaakt en er kunnen enkele uitvoer naar de bovenliggende sjabloon worden geretourneerd. Wie de module gebruikt, hoeft zich geen zorgen te maken over hoe deze werkt, alleen dat deze doet wat ze verwachten.

Wanneer u een module plant, kunt u het volgende overwegen:

  • Wat u moet weten om te kunnen voldoen aan het doel van de module.
  • Wat iedereen die uw module verbruikt, verwacht te leveren.
  • Wat iedereen die uw module verbruikt, verwacht toegang te krijgen als uitvoer.

Moduleparameters

Denk na over de parameters die uw module accepteert en of elke parameter optioneel of vereist moet zijn.

Wanneer u parameters voor sjablonen maakt, is het een goed idee om standaardparameters toe te voegen, waar u dat kunt. In modules is het niet altijd zo belangrijk om standaardparameters toe te voegen, omdat uw module wordt gebruikt door een bovenliggende sjabloon die mogelijk eigen standaardparameters gebruikt. Als u vergelijkbare parameters in beide bestanden hebt, beide met standaardwaarden, kan het lastig zijn voor de gebruikers van uw sjabloon om te achterhalen welke standaardwaarde wordt toegepast en om consistentie af te dwingen. Het is vaak beter om de standaardwaarde op de bovenliggende sjabloon te laten staan en deze uit de module te verwijderen.

U moet ook nadenken over hoe u parameters beheert waarmee de SKU's voor uw resources en andere belangrijke configuratie-instellingen worden beheerd. Wanneer u een zelfstandige Bicep-sjabloon maakt, is het gebruikelijk om bedrijfsregels in uw sjabloon in te sluiten. Bijvoorbeeld: Wanneer ik een productieomgeving implementeer, moet het opslagaccount de GRS-laag gebruiken. Maar modules bieden soms verschillende zorgen.

Als u een module bouwt die herbruikbaar en flexibel moet zijn, moet u er rekening mee houden dat de bedrijfsregels voor elke bovenliggende sjabloon mogelijk anders zijn, dus het is misschien niet zo logisch om bedrijfsregels in te sluiten in algemene modules. Overweeg om de bedrijfsregels in uw bovenliggende sjabloon te definiëren en vervolgens expliciet moduleconfiguratie door te geven via parameters.

Als u echter een module maakt die bedoeld is om uw eigen organisatie eenvoudig resources te implementeren die aan uw specifieke behoeften voldoen, is het zinvol om bedrijfsregels op te nemen om de bovenliggende sjablonen te vereenvoudigen.

Ongeacht de parameters die u in uw module opneemt, moet u ervoor zorgen dat u een zinvolle beschrijving toevoegt met behulp van het @description kenmerk:

@description('The name of the storage account to deploy.')
param storageAccountName string

Voorwaarden gebruiken

Een van de doelen bij het implementeren van een infrastructuur met behulp van code zoals Bicep is het dupliceren van inspanningen te voorkomen of zelfs om meerdere sjablonen te maken voor dezelfde of vergelijkbare doeleinden. De functies van Bicep bieden u een krachtige werkset om herbruikbare modules te maken die voor verschillende situaties werken. U kunt functies zoals modules, expressies, standaardparameterwaarden en voorwaarden combineren om herbruikbare code te bouwen die u de flexibiliteit biedt die u nodig hebt.

Stel dat u een module maakt waarmee een Azure Cosmos DB-account wordt geïmplementeerd. Wanneer het is geïmplementeerd in uw productieomgeving, moet u het account configureren om de logboeken naar een Log Analytics-werkruimte te verzenden. Als u wilt configureren dat logboeken naar Log Analytics worden verzonden, definieert u een diagnosticSettings-resource .

U kunt uw behoeften bereiken door een voorwaarde toe te voegen aan de resourcedefinitie en de parameter werkruimte-id optioneel te maken door een standaardwaarde toe te voegen:

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

Wanneer u deze module opneemt in een Bicep-sjabloon, kunt u deze eenvoudig configureren om de Azure Cosmos DB-accountlogboeken naar Log Analytics te verzenden door een werkruimte-id in te stellen. Als u geen logboeken nodig hebt voor de omgeving die u implementeert, laat u de parameter weg. Deze heeft een standaardwaarde. De module bevat de logica die nodig is om het juiste te doen voor uw vereisten.

Tip

Vergeet niet om te testen of uw sjabloon geldig is voor beide scenario's; wanneer de if instructie wordt geëvalueerd als of true false.

Module-uitvoer

Modules kunnen uitvoer definiëren. Het is een goed idee om een uitvoer te maken voor de informatie die de bovenliggende sjabloon mogelijk moet gebruiken. Als uw module bijvoorbeeld een opslagaccount definieert, kunt u overwegen om een uitvoer te maken voor de naam van het opslagaccount, zodat de bovenliggende sjabloon er toegang toe heeft.

Waarschuwing

Gebruik geen uitvoer voor geheime waarden. Uitvoer wordt geregistreerd als onderdeel van de implementatiegeschiedenis, zodat deze niet geschikt zijn voor veilige waarden. U kunt in plaats daarvan een van de volgende opties overwegen:

  • Gebruik een uitvoer om de naam van de resource op te geven. Vervolgens kan de bovenliggende sjabloon een existing resource met die naam maken en de beveiligde waarde dynamisch opzoeken.
  • Schrijf de waarde naar een Azure Key Vault-geheim. Laat de bovenliggende sjabloon het geheim uit de kluis lezen wanneer deze nodig is.

Een bovenliggende sjabloon kan module-uitvoer in variabelen gebruiken, eigenschappen voor andere resourcedefinities gebruiken of variabelen en eigenschappen beschikbaar maken als uitvoer zelf. Door uitvoer beschikbaar te maken en te gebruiken in uw Bicep-bestanden, kunt u herbruikbare sets Bicep-modules maken die met uw team kunnen worden gedeeld en opnieuw kunnen worden gebruikt voor meerdere implementaties. Het is ook een goede gewoonte om een zinvolle beschrijving toe te voegen aan uitvoer met behulp van het @description kenmerk:

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

Tip

U kunt ook speciale services gebruiken voor het opslaan, beheren en openen van de instellingen die door uw Bicep-sjabloon worden gemaakt. Key Vault is ontworpen om beveiligde waarden op te slaan. Azure-app Configuratie is ontworpen om andere (niet-beveiligde) waarden op te slaan.

Modules aan elkaar koppelen

Het is gebruikelijk om een bovenliggend Bicep-bestand te maken dat meerdere modules samenstelt. Stel dat u een nieuwe Bicep-sjabloon bouwt om virtuele machines te implementeren die gebruikmaken van toegewezen virtuele netwerken. U kunt een module maken om een virtueel netwerk te definiëren. Vervolgens kunt u de resource-id van het subnet van het virtuele netwerk als uitvoer van die module gebruiken en gebruiken als invoer voor de virtuele-machinemodule:

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

In dit voorbeeld worden symbolische namen gebruikt voor de verwijzing tussen de modules. Deze verwijzing helpt Bicep om automatisch inzicht te hebben in de relaties tussen de modules.

Omdat Bicep begrijpt dat er een afhankelijkheid is, worden de modules op volgorde geïmplementeerd:

  1. Bicep implementeert alles in de virtualNetwork module.
  2. Als deze implementatie slaagt, opent Bicep de subnetResourceId uitvoerwaarde en geeft deze als parameter door aan de virtualMachine module.
  3. Bicep implementeert alles in de virtualMachine module.

Notitie

Wanneer u afhankelijk bent van een module, wacht Bicep totdat de volledige module-implementatie is voltooid. Het is belangrijk om dit te onthouden wanneer u uw modules plant. Als u een module maakt die een resource definieert die lang duurt om te implementeren, wachten alle andere resources die afhankelijk zijn van die module totdat de implementatie van de hele module is voltooid.