Bicep parhaat käytännöt

Bicep kehityksessä voit hyödyntää samoja hyviä käytäntöjä, kuin missä tahansa sovelluskehityksessä. Tässä muutama käytäntö, joita kannattaa hyödyntää

Modulaarisuus:

Jaa infrastruktuuri pienempiin, uudelleenkäytettäviin moduuleihin. Modulaarisuus helpottaa koodin ylläpitämistä, testausta ja uudelleenkäyttöä eri projekteissa. Määrittele jokainen resurssi tai resurssiryhmä omassa Bicep-moduulirakenteessa, kun se on järkevää. Mieti moduulirakenne etukäteen ja pidä moduulirakenne mahdollisimman matalana.

Esimerkkinä Storage Accountin luominen moduulin avulla

param location string
param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

Moduulin käyttö main.bicep tiedostossa on helppoa.

param location string = 'westeurope'
param storageAccountName string = 'mystorageaccount${uniqueString(resourceGroup().id)}'

module storageAccountModule './storageAccount.bicep' = {
  name: 'storageAccountDeployment'
  params: {
    location: location
    storageAccountName: storageAccountName
  }
}

output storageAccountId string = storageAccountModule.outputs.storageAccountId

Parametrisointi:

Käytä parametreja mukautettavien arvojen, kuten ympäristönimien, koon ja muiden konfiguroitavien asetusten, välittämiseen skripteihisi. Parametrisointi tekee skripteistäsi joustavampia ja helpottaa niiden uudelleenkäyttöä eri ympäristöissä. Mieti miten moduuli on mahdollisimman monikäyttöinen, jotta samaa moduulia voi hyödyntää myös muissa projekteissa.

Alla muutama esimerkki parametrien käytöstä Bicepissa.

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

@allowed([
  'dev'
  'qa'
  'prod'
])
@description('Required. The environment of created resources.')
param env string = 'dev'

@description('The name of the static web app')
param staticWebAppName string = 'stapp-awe-frontend-${env}'

Turvallisuus:

Käytä Azure Key Vaultia salassa pidettävien tietojen, kuten salasanojen ja avainten, hallintaan. Viittaa näihin salaisuuksiin Bicep-skripteissäsi sen sijaan, että kirjoittaisit ne suoraan koodiin. Infrastruktuuri koodissa ei saa olla mitään salaisuudeksi luokiteltavaa tietoa. Lisää salaisuudet joko Keyvaultiin tai injektoi salaisuudet Devops automaation avulla ajettaviin bicep tiedostoihin.

Keyvault salaisuuksien käyttö on helppa Bicepissa. Tässä esimerkissä luetaan jo luodusta Keyvaultista pari salaisuutta ja annetaan ne referenssinä API moduulille.

resource sharedKv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
  name: 'kv-awe-shared-${env}'
  scope: resourceGroup('rg-awe-backend-shared')
}

module deployApi 'api_app_service.bicep' = {
  name: 'deploy_backend_api'
  params: {
    AAD_Authority: sharedKv.getSecret('AAD--Authority') 
    AAD_DirectoryId: sharedKv.getSecret('AAD--DirectoryId')
  }
}

Ympäristöjen erottelu:

Hallitse tuotanto- ja kehitysympäristöjä käyttämällä erillisiä parametritiedostoja tai -arvoja. Tämä parantaa hallintaa ja vähentää virheiden riskiä, kun muutoksia viedään tuotantoon.

Katsotaan esimerkkinä miten parametri tiedostot auttavat erottamaan eri ympäristöjen erilaiset parametriarvot

Pää moduuli mahdollistaa esimerkissä kahden parametrin asettamisen

param location string = 'westeurope'
param storageAccountName string = 'mystorageaccount${uniqueString(resourceGroup().id)}'

module storageAccountModule './storageAccount.bicep' = {
  name: 'storageAccountDeployment'
  params: {
    location: location
    storageAccountName: storageAccountName
  }
}

output storageAccountId string = storageAccountModule.outputs.storageAccountId

Development Environment (dev.parameters.json):

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "value": "eastus"
    },
    "storageAccountName": {
      "value": "devstorageaccount"
    }
  }
}

Parametritiedoston käyttö deploymentin yhteydessä.

az deployment group create --resource-group myResourceGroupDev --template-file main.bicep --parameters @dev.parameters.json

Idempotenssi:

Varmista, että Bicep-skriptisi ovat idempotentteja, eli niiden suorittaminen useita kertoja samalla konfiguraatiolla ei muuta lopputulosta toivotun tilan saavuttamisen jälkeen. Tämä on tärkeää infrastruktuurin vakauden ja ennustettavuuden kannalta.

Alla oleva esimerkki ei ole hyvä, koska storage accountin nimi muuttuu jokaisella deployment kierrokselle. Tällöin luot aina uuden storage accountin ja et päivitä jo luotua resurssia, mikä on tietysti IaC:ssa tavoitteena. Älä siis tee alla olevan mukaisia Bicep tiedostoja, jotka eivät ole idempotentteja

var uniqueStorageName = 'storage${utcNow()}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: uniqueStorageName
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

Tietojen validointi:

Hyödynnä Bicepin tarjoamia validointiominaisuuksia, kuten minimaaliset ja maksimaaliset arvot tai sallitut arvot parametreille, varmistaaksesi, että syötetiedot ovat odotetunlaisia.

Esimerkkejä validoinneista

@description('Specifies the number of instances to deploy.')
@minValue(1)
@maxValue(5)
param instanceCount int = 3

@allowed([
  'Standard_LRS'
  'Premium_LRS'
  'Standard_GRS'
])
var allowedSkus = storageConfig.sku

@description('A tag description for the resource.')
@minLength(10)
@maxLength(256)
param tagDescription string

@description('Name of the SQL Server, must follow naming conventions.')
@pattern('^[a-zA-Z][a-zA-Z0-9]{2,62}$')
param sqlServerName string

Versiohallinta:

Tallenna Bicep-tiedostot versionhallintajärjestelmään, kuten Git, mikä mahdollistaa muutosten seurannan, koodiarvioinnit, versioiden palautuksen ja yhteistyön muiden kehittäjien kanssa.

Käytä outputteja moduuleissa:

Hyödynnä output-määritteitä moduuleissa tietojen välittämiseksi moduulien välillä, mikä helpottaa riippuvuuksien hallintaa ja datan jakamista.

output vnetName string = virtualNetwork.name
output vnetId string = virtualNetwork.id
output vnetAddressSpace array = virtualNetwork.properties.addressSpace.addressPrefixes

Automaatio ja CI/CD:

Integroi Bicep-skriptisi CI/CD-putkeen (Continuous Integration/Continuous Deployment), mikä mahdollistaa infrastruktuurin automaattisen provisionoinnin ja päivitykset osana ohjelmistokehitysprosessia.

// Module: storageAccountModule.bicep

param storageAccountName string
param location string = resourceGroup().location
param skuName string = 'Standard_LRS'
param kind string = 'StorageV2'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: skuName
  }
  kind: kind
}

output storageAccountId string = storageAccount.id

// Main deployment file: main.bicep

param storageAccountName string = 'uniquestorageaccountname'

module storageAccountModule './storageAccountModule.bicep' = {
  name: 'storageAccountDeployment'
  params: {
    storageAccountName: storageAccountName
  }
}

output deployedStorageAccountId string = storageAccountModule.outputs.storageAccountId