Dodawanie parametrów i danych wyjściowych do modułów

  • 7 min

Każdy utworzony moduł powinien mieć jasny cel. Pomyśl o module jako o umowie. Akceptuje zestaw parametrów, tworzy zestaw zasobów i może dostarczyć niektóre dane wyjściowe z powrotem do szablonu nadrzędnego. Każdy, kto korzysta z modułu, nie powinien martwić się o to, jak działa, po prostu, że robi to, czego oczekuje.

Podczas planowania modułu należy wziąć pod uwagę następujące kwestie:

  • Co musisz wiedzieć, aby móc spełnić cel modułu.
  • Czego oczekuje każda osoba, która korzysta z modułu.
  • Każda osoba, która korzysta z modułu, będzie oczekiwać dostępu do danych wyjściowych.

Parametry modułu

Pomyśl o parametrach akceptowanych przez moduł oraz o tym, czy każdy parametr powinien być opcjonalny, czy wymagany.

Podczas tworzenia parametrów dla szablonów dobrym rozwiązaniem jest dodanie domyślnych parametrów, w których można. W modułach nie zawsze jest tak ważne, aby dodać parametry domyślne, ponieważ moduł będzie używany przez szablon nadrzędny, który może używać własnych parametrów domyślnych. Jeśli masz podobne parametry w obu plikach, oba z wartościami domyślnymi, użytkownicy szablonu mogą trudno ustalić, która wartość domyślna zostanie zastosowana i wymusić spójność. Często lepiej pozostawić wartość domyślną szablonu nadrzędnego i usunąć ją z modułu.

Należy również zastanowić się, jak zarządzać parametrami sterującymi jednostkami SKU zasobów i innymi ważnymi ustawieniami konfiguracji. Podczas tworzenia autonomicznego szablonu Bicep często osadza się reguły biznesowe w szablonie. Na przykład: Podczas wdrażania środowiska produkcyjnego konto magazynu powinno używać warstwy GRS. Jednak moduły czasami przedstawiają różne obawy.

Jeśli tworzysz moduł, który musi być wielokrotnego użytku i elastyczny, pamiętaj, że reguły biznesowe dla każdego szablonu nadrzędnego mogą być inne, więc osadzanie reguł biznesowych w modułach ogólnych może nie mieć tyle sensu. Rozważ zdefiniowanie reguł biznesowych w szablonie nadrzędnym, a następnie jawne przekazanie konfiguracji modułu za pomocą parametrów.

Jeśli jednak utworzysz moduł, który ma ułatwić własnej organizacji wdrażanie zasobów pasujących do konkretnych potrzeb, warto uwzględnić reguły biznesowe, aby uprościć szablony nadrzędne.

Niezależnie od parametrów uwzględninych w module upewnij się, że dodano opis zrozumiały przy użyciu atrybutu @description :

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

Warunki użytkowania

Jednym z celów wdrażania infrastruktury przy użyciu kodu takiego jak Bicep jest unikanie duplikowania nakładu pracy, a nawet tworzenia kilku szablonów w tym samym lub podobnym celu. Funkcje Bicep zapewniają zaawansowany przybornik umożliwiający tworzenie modułów wielokrotnego użytku, które działają w różnych sytuacjach. Możesz połączyć funkcje, takie jak moduły, wyrażenia, wartości parametrów domyślnych i warunki, aby utworzyć kod wielokrotnego użytku, który zapewnia elastyczność, której potrzebujesz.

Załóżmy, że tworzysz moduł, który wdraża konto usługi Azure Cosmos DB. Po wdrożeniu w środowisku produkcyjnym należy skonfigurować konto w celu wysyłania dzienników do obszaru roboczego usługi Log Analytics. Aby skonfigurować dzienniki do wysłania do usługi Log Analytics, zdefiniujesz zasób diagnosticSettings .

Możesz osiągnąć wymaganie, dodając warunek do definicji zasobu i wprowadzając opcjonalny parametr identyfikatora obszaru roboczego, dodając wartość domyślną:

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
      }
    ]
  }
}

Po dołączeniu tego modułu do szablonu Bicep można go łatwo skonfigurować tak, aby wysyłał dzienniki kont usługi Azure Cosmos DB do usługi Log Analytics, ustawiając identyfikator obszaru roboczego. Lub jeśli nie potrzebujesz dzienników dla środowiska, które wdrażasz, pomiń parametr . Ma wartość domyślną. Moduł hermetyzuje logikę wymaganą do wykonania odpowiednich czynności dla wymagań.

Napiwek

Pamiętaj, aby przetestować, czy szablon jest prawidłowy w obu scenariuszach; if gdy instrukcja jest oceniana jako true lub false.

Dane wyjściowe modułu

Moduły mogą definiować dane wyjściowe. Dobrym pomysłem jest utworzenie danych wyjściowych dla informacji, których może potrzebować szablon nadrzędny. Jeśli na przykład moduł definiuje konto magazynu, rozważ utworzenie danych wyjściowych dla nazwy konta magazynu, aby szablon nadrzędny mógł uzyskać do niego dostęp.

Ostrzeżenie

Nie używaj danych wyjściowych dla wartości wpisów tajnych. Dane wyjściowe są rejestrowane w ramach historii wdrażania, więc nie są one odpowiednie dla bezpiecznych wartości. Zamiast tego możesz rozważyć jedną z następujących opcji:

  • Użyj danych wyjściowych, aby podać nazwę zasobu. Następnie szablon nadrzędny może utworzyć existing zasób o tej nazwie i dynamicznie wyszukać bezpieczną wartość.
  • Zapisz wartość w kluczu tajnym usługi Azure Key Vault. Szablon nadrzędny odczytuje wpis tajny z magazynu, gdy go potrzebuje.

Szablon nadrzędny może używać danych wyjściowych modułu w zmiennych, może używać właściwości dla innych definicji zasobów lub uwidaczniać zmienne i właściwości jako same dane wyjściowe. Uwidaczniając i używając danych wyjściowych w plikach Bicep, można utworzyć zestawy modułów Bicep wielokrotnego użytku, które mogą być udostępniane zespołowi i ponownie używane w wielu wdrożeniach. Dobrym rozwiązaniem jest również dodanie znaczącego opisu do danych wyjściowych przy użyciu atrybutu @description :

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

Napiwek

Możesz również używać dedykowanych usług do przechowywania, zarządzania i uzyskiwania dostępu do ustawień tworzonych przez szablon Bicep. Usługa Key Vault jest przeznaczona do przechowywania bezpiecznych wartości. aplikacja systemu Azure Configuration jest przeznaczona do przechowywania innych (niezabezpieczonych) wartości.

Łączenie modułów łańcuchowych

Często tworzy się nadrzędny plik Bicep, który komponuje wiele modułów razem. Załóżmy na przykład, że tworzysz nowy szablon Bicep w celu wdrożenia maszyn wirtualnych korzystających z dedykowanych sieci wirtualnych. Możesz utworzyć moduł służący do definiowania sieci wirtualnej. Następnie można pobrać identyfikator zasobu podsieci sieci wirtualnej jako dane wyjściowe z tego modułu i użyć go jako danych wejściowych do modułu maszyny wirtualnej:

@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
  }
}

W tym przykładzie nazwy symboliczne są używane do odwołania między modułami. Ta dokumentacja pomaga Bicepowi automatycznie zrozumieć relacje między modułami.

Ponieważ Bicep rozumie, że istnieje zależność, wdraża moduły w sekwencji:

  1. Bicep wdraża wszystko w virtualNetwork module.
  2. Jeśli wdrożenie zakończy się pomyślnie, Bicep uzyskuje dostęp do wartości wyjściowej subnetResourceId i przekazuje go do modułu virtualMachine jako parametr.
  3. Bicep wdraża wszystko w virtualMachine module.

Uwaga

Gdy zależysz od modułu, Bicep czeka na zakończenie całego wdrożenia modułu. Ważne jest, aby pamiętać o tym podczas planowania modułów. Jeśli tworzysz moduł definiujący zasób, który zajmuje dużo czasu do wdrożenia, wszystkie inne zasoby zależne od tego modułu będą czekać na zakończenie wdrożenia całego modułu.