Hinzufügen und Konfigurieren eines Katalogs aus GitHub oder Azure Repos
Artikel
In diesem Leitfaden erfahren Sie, wie Sie einen Katalog in Ihrem Dev Center für Azure Deployment Environments hinzufügen und konfigurieren. Ein Katalog ist ein Repository, das auf GitHub oder in Azure DevOps gehostet wird.
Sie können Ihren Entwicklungsteams über einen Katalog einen kuratierten Satz von Infrastructure-as-Code-Vorlagen (IaC) zur Verfügung stellen, sogenannte Umgebungsdefinitionen.
Deployment Environments unterstützt Kataloge, die in Azure Repos (dem Repositorydienst in Azure, allgemein als Azure DevOps bezeichnet) gehostet werden, sowie auf GitHub gehostete Kataloge. Azure Repos unterstützt die Authentifizierung durch Zuweisen von Berechtigungen zu einer verwalteten Identität. Azure Repos und GitHub unterstützen beide die Verwendung eines persönlichen Zugriffstokens (Personal Access Token, PAT) für die Authentifizierung. Zum besseren Schutz Ihrer Vorlagen ist der Katalog verschlüsselt. Azure Deployment Environments unterstützt die Verschlüsselung ruhender Daten mit plattformseitig verwalteten Verschlüsselungsschlüsseln, die von Microsoft für Azure-Dienste verwaltet werden.
Informationen zum Hosten eines Git-Repositorys in einem Azure Repos-Projekt finden Sie unter Azure Repos.
Microsoft bietet einen Schnellstartkatalog, den Sie dem Dev Center hinzufügen können, und einen Beispielkatalog, den Sie als Repository verwenden können. Sie können auch mit Ihrem eigenen privaten Repository arbeiten oder die Umgebungsdefinitionen im Beispielkatalog forken und anpassen.
Konfigurieren einer verwalteten Identität für ein Dev Center
Nachdem Sie eine DevCenter-Instanz erstellt haben, müssen Sie vor dem Anfügen eines Katalogs eine verwaltete Identität (auch Managed Service Identity oder MSI genannt) für die DevCenter-Instanz konfigurieren. Sie können entweder eine systemseitig zugewiesene verwaltete Identität (systemseitig zugewiesene MSI) oder eine benutzerseitig zugewiesene verwaltete Identität (benutzerseitig zugewiesene MSI) verwenden. Anschließend weisen Sie der verwalteten Identität Rollen zu, damit die DevCenter-Instanz Umgebungstypen in Ihrem Abonnement erstellen und das Azure Repos-Projekt lesen kann, das das Katalogrepository enthält.
Wenn keine MSI an Ihr Dev Center angefügt ist, führen Sie die Schritte unter Konfigurieren einer verwalteten Identität aus, um eine verwaltete Identität zu erstellen und Rollen für die verwaltete Dev Center-Identität zuzuweisen.
Sie können einen Katalog aus einem Azure Repos-Repository oder aus einem GitHub-Repository hinzufügen. Sie können sich authentifizieren, indem Sie einer MSI Berechtigungen zuweisen oder ein PAT verwenden, das Sie in einem Schlüsseltresor speichern.
Wählen Sie die Registerkarte für den Typ des Repositorys und der Authentifizierung aus, die Sie verwenden möchten.
Ihre Azure DevOps-Organisation muss sich im selben Verzeichnis wie das Azure-Abonnement befinden, das Ihr Dev Center enthält.
Wählen Sie Organisationseinstellungen aus.
Wählen Sie auf der Seite Übersicht die Option Benutzer aus.
Wählen Sie auf der Seite Benutzer die Option Benutzer hinzufügen aus.
Vervollständigen Sie neue Benutzer hinzufügen, indem Sie die folgenden Informationen eingeben oder sie auswählen, und wählen Sie dann Hinzufügen aus:
Name
Wert
Benutzer oder Dienstprinzipale
Geben Sie den Namen Ihres Entwicklungscenters ein. Wenn Sie eine systemseitig zugewiesene MSI verwenden, geben Sie den Namen des Dev Center und nicht die Objekt-ID des verwalteten Kontos an. Wenn Sie eine benutzerseitig zugewiesene MSI verwenden, verwenden Sie den Namen des verwalteten Kontos.
Zugriffsebene
Wählen Sie Basic aus.
Zu Projekten hinzufügen
Wählen Sie das Projekt aus, das Ihr Repository enthält.
Azure DevOps-Gruppen
Wählen Sie Projektleser aus.
Senden von E-Mail-Einladungen (nur an Benutzer)
Deaktivieren Sie das Kontrollkästchen.
Hinzufügen des Repositorys als Katalog
Azure Deployment Environments unterstützt das Anfügen von Azure Repos- und GitHub-Repositorys. Sie können eine Reihe kuratierter IaC-Vorlagen (Infrastructure-as-Code) in einem Repository speichern. Durch Anfügen des Repositorys an ein Dev Center als Katalog erhalten Ihre Entwicklungsteams Zugriff auf die Vorlagen und können so schnell konsistente Umgebungen einrichten.
In den folgenden Schritten wird ein Azure Repos-Repository angefügt.
Navigieren Sie im Azure-Portal zu Ihrem Dev Center.
Wählen Sie im linken Menü unter Umgebungskonfiguration die Option Kataloge und dann Hinzufügen aus.
Geben Sie unter Katalog hinzufügen die folgenden Informationen ein, und wählen Sie dann Hinzufügen aus:
Feld
Wert
Name
Geben Sie einen Namen für den Katalog ein.
Katalogspeicherort
Wählen Sie Azure DevOps aus.
Authentifizierungstyp
Wählen Sie Verwaltete Identität aus.
Organisation
Wählen Sie Ihre Azure DevOps-Organisation aus.
Projekt
Wählen Sie in der Liste der Projekte das Projekt aus, welches das Repository speichert.
Repository
Wählen Sie in der Liste der Repositorys das Repository aus, das Sie hinzufügen möchten.
Branch
Wählen Sie den Branch aus.
Ordnerpfad
Dev Box ruft eine Liste der Ordner in Ihrem Branch ab. Wählen Sie den Ordner aus, der Ihre IaC-Vorlagen speichert.
Vergewissern Sie sich im Dev Center unter Kataloge, dass Ihr Katalog angezeigt wird. Wenn die Verbindung erfolgreich hergestellt wurde, wird unter Status der Wert Synchronisierung erfolgreich angezeigt. Das Herstellen einer Verbindung mit einem Katalog kann beim ersten Mal ein paar Minuten dauern.
Führen Sie zum Hinzufügen eines Katalogs die folgenden Aufgaben aus:
Rufen Sie die Klon-URL für Ihr Azure Repos-Repository ab.
Erstellen eines persönlichen Zugriffstokens (Personal Access Token, PAT)
Speichern des PAT als Schlüsseltresorgeheimnis in Azure Key Vault
Hinzufügen des Repositorys als Katalog
Abrufen der Klon-URL für Ihr Azure Repos-Repository
Wechseln Sie zur Startseite Ihrer Teamsammlung (z. B. https://contoso-web-team.visualstudio.com), und wählen Sie dann das Projekt aus.
Kopieren und speichern Sie das generierte Token zur späteren Verwendung.
Erstellen eines Schlüsseltresors
Sie benötigen eine Azure Key Vault-Instanz, um das PAT zu speichern, das verwendet wird, um Azure Zugriff auf Ihr Repository zu gewähren. Schlüsseltresore können den Zugriff entweder mit Zugriffsrichtlinien oder mit der rollenbasierten Zugriffssteuerung (RBAC) steuern. Wenn Sie bereits einen Schlüsseltresor haben, können Sie ihn verwenden. Sie sollten jedoch überprüfen, ob er Zugriffsrichtlinien oder RBAC-Zuweisungen verwendet, um den Zugriff zu steuern. Hilfe beim Konfigurieren einer Zugriffsrichtlinie für einen Schlüsseltresor finden Sie unter Zuweisen einer Key Vault Zugriffsrichtlinie.
Verwenden Sie die folgenden Schritte, um einen RBAC-Schlüsseltresor zu erstellen:
Wählen Sie im linken Menü unter Umgebungskonfiguration die Option Kataloge und dann Hinzufügen aus.
Geben Sie unter Katalog hinzufügen die folgenden Informationen ein, und wählen Sie dann Hinzufügen aus:
Feld
Wert
Name
Geben Sie einen Namen für den Katalog ein.
Katalogspeicherort
Wählen Sie Azure DevOps aus.
Authentifizierungstyp
Wählen Sie Persönliches Zugriffstoken aus.
Organisation
Wählen Sie die Organisation aus, in der das Katalogrepository gehostet wird.
Projekt
Wählen Sie das Projekt aus, in der das Katalogrepository gespeichert ist.
Rep.
Wählen Sie das Repository aus, in dem der Katalog gespeichert ist.
Ordnerpfad
Wählen Sie den Ordner aus, der Ihre IaC-Vorlagen enthält.
Geheimnis-ID
Geben Sie die Geheimnis-ID ein, die Ihr PAT für das Repository enthält. Wenn Sie einen Geheimnisbezeichner kopieren, enthält die Verbindungszeichenfolge am Ende einen Versionsbezeichner wie in diesem Beispiel: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. Wenn Sie den Versionsbezeichner entfernen, wird sichergestellt, dass Azure Deployment Environments die neueste Version des Geheimnisses aus dem Schlüsseltresor abruft. Wenn Ihr PAT abläuft, muss nur der Schlüsseltresor aktualisiert werden. Beispiel eines Geheimnisbezeichners:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat
Vergewissern Sie sich im Dev Center unter Kataloge, dass Ihr Katalog angezeigt wird. Wenn die Verbindung erfolgreich hergestellt wurde, wird Verbunden als Status angezeigt.
Führen Sie zum Hinzufügen eines Katalogs die folgenden Aufgaben aus:
Installieren und Konfigurieren der Microsoft DevCenter-App
Weisen Sie in GitHub Berechtigungen für die Repositorys zu.
Wählen Sie im linken Menü unter Umgebungskonfiguration die Option Kataloge und dann Hinzufügen aus.
Geben Sie im Bereich Katalog hinzufügen die folgenden Informationen ein, oder wählen Sie sie aus:
Feld
Wert
Name
Geben Sie einen Namen für den Katalog ein.
Katalogquelle
Wählen Sie GitHub aus.
Authentifizierungstyp
Wählen Sie GitHub-App aus.
Wählen Sie zum Installieren der Microsoft DevCenter-App den Link Ihre Repositorys konfigurieren aus.
Wenn Sie aufgefordert werden, sich bei GitHub zu authentifizieren, führen Sie die Authentifizierung durch.
Wählen Sie auf der Seite Microsoft DevCenter die Option Konfigurieren aus.
Wählen Sie die GitHub-Organisation aus, die das Repository enthält, das Sie als Katalog hinzufügen möchten. Sie müssen ein Besitzer der Organisation sein, um diese App installieren zu können.
Wählen Sie auf der Seite „Microsoft DevCenter installieren“ die Option Nur ausgewählte Repositorys aus, wählen Sie das Repository aus, das Sie als Katalog hinzufügen möchten, und wählen Sie anschließend Installieren aus.
Sie können mehrere Repositorys auswählen, um sie als Kataloge hinzuzufügen. Sie müssen jedes Repository als separaten Katalog hinzufügen, wie in Hinzufügen des Repositorys als Katalog beschrieben.
Überprüfen Sie auf der Seite Microsoft DevCenter von Microsoft benötigt Berechtigung für Folgendes: die erforderlichen Berechtigungen, und wählen Sie dann Microsoft DevCenter autorisieren aus.
Hinzufügen des Repositorys als Katalog
Kehren Sie zum Azure-Portal zurück.
Geben Sie unter Katalog hinzufügen die folgenden Informationen ein, und wählen Sie dann Hinzufügen aus:
Feld
Wert
Repository
Wählen Sie das Repository aus, das Sie als Katalog hinzufügen möchten.
Branch
Wählen Sie den Branch aus.
Ordnerpfad
Wählen Sie den Ordner aus, der Unterordner mit Ihren Umgebungsdefinitionen enthält.
Vergewissern Sie sich im Dev Center unter Kataloge, dass Ihr Katalog angezeigt wird. Wenn die Verbindung erfolgreich hergestellt wurde, wird unter Status der Wert Synchronisierung erfolgreich angezeigt.
Führen Sie zum Hinzufügen eines Katalogs die folgenden Aufgaben aus:
Abrufen der Klon-URL Ihres GitHub-Repositorys
Erstellen eines persönlichen Zugriffstokens (Personal Access Token, PAT) in GitHub
Speichern des PAT als Schlüsseltresorgeheimnis in Azure Key Vault
Hinzufügen des Repositorys als Katalog
Abrufen der Klon-URL Ihres GitHub-Repositorys
Navigieren Sie zur Startseite des GitHub-Repositorys, das die Vorlagendefinitionen enthält.
Erstellen eines persönlichen Zugriffstokens in GitHub
Azure Deployment Environments unterstützt die Authentifizierung bei GitHub-Repositorys mithilfe von klassischen Token oder differenzierten Token. In diesem Beispiel erstellen Sie ein differenziertes Token.
Navigieren Sie zur Startseite des GitHub-Repositorys, das die Vorlagendefinitionen enthält.
Wählen Sie das Profilbild in der oberen rechten Ecke von GitHub aus, und wählen Sie Einstellungen.
Wählen Sie auf der linken Randleiste Entwicklereinstellungen>Persönliche Zugriffstoken>Differenzierte Token aus.
Wählen Sie Generate new token.
Geben Sie auf der Seite Neues differenziertes persönliches Zugriffstoken die folgenden Informationen an:
Name
Wert
Token name
Geben Sie einen aussagekräftigen Namen für das Token ein.
Ablauf
Wählen Sie den Tokenablaufzeitraum in Tagen aus.
Beschreibung
Geben Sie eine Beschreibung für das Token ein.
Ressourcenbesitzer
Wählen Sie den Besitzer des Repositorys aus.
Repositoryzugriff
Wähle Nur Repositorys auswählen aus.
Repositorys auswählen
Wählen Sie das Repository aus, das die Umgebungsdefinitionen enthält.
Repositoryberechtigungen
Erweitern Sie Repositoryberechtigungen, und wählen Sie in der Liste Zugriff für Inhalt die Option Code lesen aus.
Wählen Sie Generate token (Token generieren) aus.
Kopieren und speichern Sie das generierte Token zur späteren Verwendung.
Wichtig
Wenn Sie mit einem privaten Repository arbeiten, das in einer GitHub-Organisation gespeichert ist, müssen Sie sicherstellen, dass das GitHub-PAT so konfiguriert ist, dass der Zugriff auf die richtige Organisation und die darin enthaltenen Repositorys ermöglicht wird.
Für klassische Token innerhalb der Organisation muss nach ihrer Erstellung einmaliges Anmelden autorisiert werden.
Bei differenzierten Token muss der Besitzer des Tokens auf die Organisation festgelegt werden, damit die Autorisierung funktioniert.
Falsch konfigurierte PATs können zu einem Fehler vom Typ Repository nicht gefunden führen.
Erstellen eines Schlüsseltresors
Sie benötigen eine Azure Key Vault-Instanz zum Speichern des PAT, das zum Erteilen von Azure-Zugriff auf Ihr Repository verwendet wird. Schlüsseltresore können den Zugriff entweder mit Zugriffsrichtlinien oder mit der rollenbasierten Zugriffssteuerung (RBAC) steuern. Wenn Sie bereits einen Schlüsseltresor haben, können Sie ihn verwenden. Sie sollten jedoch überprüfen, ob er Zugriffsrichtlinien oder RBAC-Zuweisungen verwendet, um den Zugriff zu steuern. Hilfe beim Konfigurieren einer Zugriffsrichtlinie für einen Schlüsseltresor finden Sie unter Zuweisen einer Key Vault-Zugriffsrichtlinie.
Verwenden Sie die folgenden Schritte, um einen RBAC-Schlüsseltresor zu erstellen:
Wählen Sie im linken Menü unter Umgebungskonfiguration die Option Kataloge und dann Hinzufügen aus.
Geben Sie unter Katalog hinzufügen die folgenden Informationen ein, und wählen Sie dann Hinzufügen aus.
Feld
Wert
Name
Geben Sie einen Namen für den Katalog ein.
Katalogspeicherort
Wählen Sie GitHub aus.
Repository
Geben oder fügen Sie die Klon-URL für Ihr GitHub-Repository oder für Ihr Azure Repos-Repository ein. Katalogbeispiel:https://github.com/Azure/deployment-environments.git
Branch
Geben Sie den Repositorybranch ein, mit dem eine Verbindung hergestellt werden soll. Katalogbeispiel:main
Ordnerpfad
Geben Sie den Ordnerpfad relativ zum Klon-URI ein, der Unterordner mit Ihren Umgebungsdefinitionen enthält. Der Ordnerpfad gilt für den Ordner mit Unterordnern, die Umgebungsdateien der Umgebungsdefinitionen enthalten, und nicht für den Ordner mit der Umgebungsdatei der Umgebungsdefinitionen selbst. Die folgende Abbildung zeigt die Struktur des Beispielkatalogordners. Katalogbeispiel:/Environments Der Ordnerpfad kann einen Schrägstrich (/) am Anfang haben.
Geheimnis-ID
Geben Sie die Geheimnis-ID ein, die Ihr PAT für das Repository enthält. Wenn Sie einen Geheimnisbezeichner kopieren, enthält die Verbindungszeichenfolge am Ende einen Versionsbezeichner wie in diesem Beispiel: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. Wenn Sie den Versionsbezeichner entfernen, wird sichergestellt, dass Deployment Environments die neueste Version des Geheimnisses aus dem Schlüsseltresor abruft. Wenn Ihr PAT abläuft, muss nur der Schlüsseltresor aktualisiert werden. Beispiel eines Geheimnisbezeichners:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat
Vergewissern Sie sich im Dev Center unter Kataloge, dass Ihr Katalog angezeigt wird. Wenn die Verbindung erfolgreich hergestellt wurde, wird unter Status der Wert Synchronisierung erfolgreich angezeigt.
Aktualisieren eines Katalogs
Wenn Sie den Inhalt oder die Definition der Azure Resource Manager-Vorlage (ARM-Vorlage) im angefügten Repository aktualisieren, können Sie die neuesten Umgebungsdefinitionen für Ihre Entwicklungsteams bereitstellen, indem Sie den Katalog synchronisieren.
So synchronisieren Sie einen aktualisierten Katalog in Azure Deployment Environments
Wählen Sie im linken Menü für das Dev Center unter Umgebungskonfiguration die Option Kataloge aus.
Wählen Sie den entsprechenden Katalog und dann Synchronisieren aus. Der Dienst überprüft das Repository und stellt die aktuelle Liste der Umgebungsdefinitionen für alle zugeordneten Projekte im Dev Center zur Verfügung.
Löschen eines Katalogs
Sie können einen Katalog löschen, um ihn aus dem Dev Center für Azure Deployment Environments zu entfernen. Vorlagen in einem gelöschten Katalog sind beim Bereitstellen neuer Umgebungen nicht für Entwicklungsteams verfügbar. Aktualisieren Sie den Verweis auf die Umgebungsdefinitionen für alle bestehenden Umgebungen, die mithilfe der Umgebungsdefinitionen im gelöschten Katalog erstellt wurden. Wenn der Verweis nicht aktualisiert und die Umgebung neu bereitgestellt wird, schlägt die Bereitstellung fehl.
Katalog löschen:
Wählen Sie im linken Menü für das Dev Center unter Umgebungskonfiguration die Option Kataloge aus.
Wählen Sie den entsprechenden Katalog und dann Löschen aus.
Wählen Sie im Dialogfeld Katalog löschen die Option Weiter aus, um den Katalog zu löschen.
Katalogsynchronisierungsfehler
Wenn Sie einen Katalog hinzufügen oder synchronisieren, tritt möglicherweise ein Synchronisierungsfehler auf. Ein Synchronisierungsfehler gibt an, dass einige oder alle Umgebungsdefinitionen Fehler aufweisen. Verwenden Sie die Azure CLI oder die REST-API, um den Katalog abzurufen (mit GET). Die GET-Antwort zeigt die Art des Fehlers an:
Ignorierte Umgebungsdefinitionen, die als Duplikate erkannt wurden
Ungültige Umgebungsdefinitionen, die aufgrund von Schema-, Verweis- oder Überprüfungsfehlern fehlgeschlagen sind
Beheben von Fehlern aufgrund ignorierter Umgebungsdefinitionen
Ein Fehler aufgrund von ignorierten Umgebungsdefinitionen tritt auf, wenn Sie zwei oder mehr Umgebungsdefinitionen hinzufügen, die denselben Namen haben. Sie können dieses Problem beheben, indem Sie Umgebungsdefinitionen umbenennen, sodass jede Umgebungsdefinition einen eindeutigen Namen im Katalog aufweist.
Beheben von Fehlern aufgrund ungültiger Umgebungsdefinitionen
Ein Fehler aufgrund ungültiger Umgebungsdefinitionen kann aus verschiedenen Gründen auftreten:
Manifestschemafehler. Stellen Sie sicher, dass die Umgebungsdatei der Umgebungsdefinitionen mit dem erforderlichen Schema übereinstimmt.
Überprüfungsfehler. Überprüfen Sie die folgenden Elemente, um Überprüfungsfehler zu beheben:
Stellen Sie sicher, dass der Modultyp der Umgebungsdatei ordnungsgemäß als ARM konfiguriert ist.
Stellen Sie sicher, dass der Name der Umgebungsdefinitionen zwischen 3 und 63 Zeichen lang ist.
Stellen Sie sicher, dass der Name der Umgebungsdefinitionen nur Zeichen enthält, die für eine URL gültig sind. Dies sind alphanumerische Zeichen und folgende Symbole: ~!,.';:=-_+()*&$@.
Verweisfehler. Stellen Sie sicher, dass der von der Umgebungsdatei referenzierte Vorlagenpfad ein gültiger relativer Pfad zu einer Datei im Repository ist.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.