Share via

Erstellen einer privaten Registrierung für Bicep-Module

  • Artikel

Um Module innerhalb Ihrer Organisation freizugeben, können Sie eine private Modulregistrierung erstellen. Sie veröffentlichen Module in dieser Registrierung und gewähren Benutzern, die die Module bereitstellen müssen, Lesezugriff. Nachdem die Module in den Registrierungen freigegeben wurden, können Sie in Ihren Bicep-Dateien darauf verweisen. Wenn Sie zur öffentlichen Modulregistrierung beitragen möchten, lesen Sie den Leitfaden für Mitwirkende an Beiträgen.

Für die Arbeit mit Modulregistrierungen benötigen Sie die Bicep CLI-Version 0.4.1008 oder höher. Zur Verwendung mit der Azure CLI benötigen Sie auch mindestens Version 2.31.0. Zur Verwendung mit Azure PowerShell benötigen Sie außerdem mindestens Version 7.0.0.

Schulungsressourcen

Wenn Sie lieber Schritt-für-Schritt-Anleitungen zu Parametern lernen möchten, finden Sie weitere Informationen unter Teilen von Bizepsmodulen mithilfe privater Registrierungen.

Konfigurieren einer privaten Registrierung

Eine Bicep-Registrierung wird auf Azure Container Registry (ACR) gehostet. Verwenden Sie die folgenden Schritte, um Ihre Registrierung für Module zu konfigurieren.

  1. Wenn Sie bereits über eine Containerregistrierung verfügen, können Sie sie verwenden. Wenn Sie eine Containerregistrierung erstellen müssen, finden Sie weitere Informationen unter Schnellstart: Erstellen einer Containerregistrierung mithilfe einer Bicep-Datei.

    Sie können jede der verfügbaren Registrierungs-SKUs für die Modulregistrierung verwenden. Die Georeplikation der Registrierung bietet Benutzern eine lokale Präsenz oder eine Sicherung auf heißer Speicherebene.

  2. Rufen Sie den Namen des Anmeldeservers ab. Sie benötigen diesen Namen, wenn Sie aus Ihren Bicep-Dateien eine Verknüpfung mit der Registrierung herstellen. Das Format des Anmeldeservernamens lautet <registry-name>.azurecr.io.

    Um den Namen des Anmeldeservers abzurufen, verwenden Sie Get-AzContainerRegistry.

    Get-AzContainerRegistry -ResourceGroupName "<resource-group-name>" -Name "<registry-name>"  | Select-Object LoginServer

  3. Um Module in einer Registrierung zu veröffentlichen, benötigen Sie die Berechtigung zum Pushen eines Images. Um Module aus einer Registrierung bereitzustellen, benötigen Sie die Berechtigung zum Pullen des Images. Weitere Informationen zu den Rollen, die angemessenen Zugriff gewähren, finden Sie unter Azure Container Registry-Rollen und -Berechtigungen.

  4. Abhängig vom Typ des Kontos, das Sie zum Bereitstellen des Moduls verwenden, müssen Sie möglicherweise anpassen, welche Anmeldeinformationen verwendet werden. Diese Anmeldeinformationen werden benötigt, um die Module aus der Registrierung abzurufen. Standardmäßig werden Anmeldeinformationen aus Azure CLI oder Azure PowerShell abgerufen. Sie können die Rangfolge zum Abrufen der Anmeldeinformationen in der Datei bicepconfig.json anpassen. Weitere Informationen finden Sie unter Anmeldeinformationen zum Wiederherstellen von Modulen.

Wichtig

Die Registrierung privater Container ist nur für Benutzer mit dem erforderlichen Zugriff verfügbar. Der Zugriff darauf erfolgt jedoch über das öffentliche Internet. Um die Sicherheit zu erhöhen, können Sie Zugriff über einen privaten Endpunkt anfordern. Weitere Informationen finden Sie unter Herstellen einer privaten Verbindung mit einer Azure-Containerregistrierung über Azure Private Link.

Für die private Containerregistrierung muss die Richtlinie azureADAuthenticationAsArmPolicy auf enabled festgelegt sein. Wenn azureADAuthenticationAsArmPolicy auf disabled festgelegt ist, erhalten Sie beim Veröffentlichen von Modulen eine Fehlermeldung vom Typ 401 (Nicht autorisiert). Siehe Azure Container Registry führt die Richtlinie für bedingten Zugriff ein.

Veröffentlichen von Dateien in der Registrierung

Nachdem Sie die Containerregistrierung eingerichtet haben, können Sie darin Dateien veröffentlichen. Verwenden Sie den Befehl publish, und geben Sie alle Bicep-Dateien an, die Sie als Module verwenden möchten. Geben Sie den Zielspeicherort für das Modul in Ihrer Registrierung an. Der Befehl zum Veröffentlichen erstellt eine ARM-Vorlage, die in der Registrierung gespeichert wird. Dies bedeutet, dass die Veröffentlichung einer Bicep-Datei, die auf andere lokale Module verweist, vollständig als eine JSON-Datei erweitert und in der Registrierung veröffentlicht wird.

Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 -DocumentationUri https://www.contoso.com/exampleregistry.html

Mit Bicep CLI Version 0.27.1 oder höher können Sie zusätzlich zur kompilierten JSON-Vorlage ein Modul mit dem Bicep-Quellcode veröffentlichen. Wenn ein Modul mit dem Bicep-Quellcode in einer Registrierung veröffentlicht wird, können Sie in Visual Studio Code F12 drücken (Zur Definition), um den Bicep-Code anzuzeigen. Version 0.27 oder höher der Bicep-Erweiterung ist erforderlich, um die Bicep-Datei anzuzeigen.

Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 -DocumentationUri https://www.contoso.com/exampleregistry.html -WithSource

Mit dem source-Schalter wird im Manifest eine zusätzliche Ebene angezeigt:

Screenshot der Bicep-Modulregistrierung mit Quelle

Beachten Sie, dass der ACR-Endpunkt sichtbar ist, wenn das Bicep-Modul auf ein Modul in einer privaten Registrierung verweist. Um den vollständigen Endpunkt auszublenden, können Sie einen Alias für die private Registrierung konfigurieren.

Anzeigen von Dateien in der Registrierung

So zeigen Sie das veröffentlichte Modul im Portal an

  1. Melden Sie sich beim Azure-Portal an.

  2. Suchen Sie nach Containerregistrierungen.

  3. Wählen Sie Ihre Registrierung aus.

  4. Wählen Sie im Menü links Dienste>Repositorys aus.

  5. Wählen Sie den Modulpfad (Repository) aus. Im vorherigen Beispiel lautet der Name des Modulpfads bicep/modules/storage.

  6. Wählen Sie das Tag aus. Im vorherigen Beispiel lautet das Tag v1.

  7. Der Artefaktverweis entspricht dem Verweis, den Sie in der Bicep-Datei verwenden.

    Artefaktverweis der Bicep-Modulregistrierung

Sie können nun aus einer Bicep-Datei auf die Datei in der Registrierung verweisen. Beispiele für die Syntax, die zum Verweisen auf ein externes Modul verwendet wird, finden Sie unter Bicep-Module.

Arbeiten mit Bicep-Registrierungsdateien

Wenn Sie Bicep-Dateien, die in einer Remoteregistrierung gehostet werden, nutzen möchten, müssen Sie unbedingt verstehen, wie Ihr lokaler Computer mit der Registrierung interagiert. Wenn Sie den Verweis auf die Registrierung zum ersten Mal deklarieren, versucht Ihr lokaler Editor, mit der Azure Container Registry zu kommunizieren und eine Kopie der Registry in den lokalen Cache herunterzuladen.

Der lokale Cache befindet sich hier:

  • Unter Windows

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

  • Unter Linux

    /home/<username>/.bicep

  • Unter Mac

    ~/.bicep

Alle Änderungen, die an der Remoteregistrierung vorgenommen wurden, werden von Ihrem lokalen Computer erst erkannt, wenn ein restore-Befehl mit der angegebenen Datei ausgeführt wurde, die den Registrierungsverweis enthält.

az bicep restore --file <bicep-file> [--force]

Weitere Informationen finden Sie in der Dokumentation zum Befehl restore.

Nächste Schritte