Zum Inhalt

Spoke-Integrationen: Azure DevOps und GitHub

Ein spoke kann die Ressourcen erstellen, die sein Team braucht, um einen Workload zu deployen: ein Azure-DevOps-Repository und eine Service Connection oder ein GitHub-Repository mit Federated Credentials. Beides ist optional. Diese Seite beschreibt die Blöcke der spoke-Datei und was das Deployment mit ihnen macht. Die einmalige Vorbereitung (Berechtigungen, GitHub App, pipeline-Einstellungen) steht unter Spoke-Integrationen vorbereiten.

Fehlt ein Block in der spoke-Datei, wird nichts erstellt und keine Vorbereitung ist nötig.

Wie der Service Principal seine Zugangsdaten bekommt

Jeder spoke hat einen Service Principal. Wie er sich authentifiziert, hängt von der gewählten Integration ab:

Konfiguration Zugangsdaten
Azure-DevOps-Block mit useFederatedCredentials: true, oder GitHub-Extension aktiviert Kein Secret. Die Service Connection oder der Workflow nutzt Workload Identity Federation (OIDC).
Azure-DevOps-Block ohne useFederatedCredentials (Standard) Ein Secret wird erzeugt und zusammen mit der Client-ID im Key Vault des Spokes gespeichert.
Keine Integration, Key Vault deployt Ein Secret wird erzeugt und im Key Vault gespeichert.
Keine Integration, Key Vault nicht deployt Der Service Principal hat keine Zugangsdaten. Das Team richtet sie außerhalb des spoke-Deployments ein.

Bevorzuge Federated Credentials. Es muss kein Secret gespeichert, rotiert oder geleakt werden.

Azure DevOps

"azdo": {
  "projectName": "<existing project>",
  "repoName": "repo-##wlshortname##-##environment##",
  "serviceConnectionName": "sc-sub-##wlshortname##-##environment##",
  "useFederatedCredentials": true
}
Feld Beschreibung
projectName Name des bestehenden Azure-DevOps-Projekts, in dem die Ressourcen erstellt werden.
repoName Das zu erstellende Repository. Es wird einmal erstellt, falls es nicht existiert. Es gibt ein Repository, nicht eines pro Lebenszyklus-Umgebung.
serviceConnectionName Azure-Resource-Manager-Service-Connection, die für den Service Principal des Spokes erstellt wird.
useFederatedCredentials true: Workload Identity Federation, kein Secret. false (Standard): Secret-basiert. Auf der App-Registrierung des Service Principals wird ein Federated Credential erstellt.

Die Platzhalter ##wlshortname## und ##environment## werden ersetzt.

Die pipeline, die das spoke-Deployment ausführt, braucht Projekteinstellungen und Berechtigungen, um diese Ressourcen zu erstellen. Sie sind unter Spoke-Integrationen vorbereiten aufgeführt.

GitHub-Extension

"extensions": {
  "github": {
    "enabled": true,
    "repository": "##wlshortname##-##environment##-repo",
    "repository_visibility": "private",
    "environments": ["dev", "test", "prod"]
  }
}
Feld Erforderlich Beschreibung
enabled ja Standard false.
repository ja Name des zu erstellenden Repositorys.
organization nein GitHub-Organisation. Standard: ghinfo.OrganizationName aus den allgemeinen Einstellungen.
oidc_issuer nein URL des OIDC-Issuers. Standard: ghinfo.OidcIssuer.
repository_description nein Standard: Repository managed by Azure Spoke deployment.
repository_visibility nein public, private oder internal. Standard private.
repository_auto_init nein Mit einem README initialisieren. Standard true.
environment nein Ein Environment-Name für das Federated Credential. Aus Gründen der Abwärtskompatibilität beibehalten.
environments nein Liste von Environment-Namen. Wenn gesetzt, ersetzt sie environment.

Schema-Unterstützung

Der Block extensions im spoke-Schema mancher Versionen erlaubt nur apim, acr, servicebus und eventhub (Spoke-JSON-Referenz). Wenn der Config-Test extensions.github ablehnt, enthält das Schema der Code-Version, die du fixiert hast, sie noch nicht. Prüfe die Version, bevor du einen spoke mit dieser Extension planst.

Was erstellt wird

  • Ein Repository mit den obigen Einstellungen.

  • Federated Identity Credentials auf dem Service Principal des Spokes, damit Workflows sich ohne Secret bei Azure anmelden:

    Credential Subject
    Main-Branch repo:<organization>/<repository>:ref:refs/heads/main
    Eines pro Environment in environments repo:<organization>/<repository>:environment:<environment-name>

  • Actions-Secrets im Repository für die Azure-Anmeldung.

Die Secrets, die der Workflow liest, sind AZURE_CLIENT_ID, AZURE_TENANT_ID und AZURE_SUBSCRIPTION_ID.

In einem Workflow verwenden

Ein Workflow im neuen Repository meldet sich mit dem Federated Credential an. Er braucht die Berechtigung id-token: write und, für ein environment-spezifisches Credential, den Schlüssel environment: des Jobs:

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production   # must match an environment in the spoke file
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v1
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

Environment-Namen

Ein Workflow-Job kann ein Federated Credential nur für ein Environment verwenden, das die spoke-Datei auflistet. Wenn die Anmeldung mit einem Subject-Mismatch fehlschlägt, vergleiche den Environment-Namen des Jobs mit environments.

Varianten

Szenario Spoke-Datei
Standardwerte aus den allgemeinen Einstellungen enabled, repository, environments
Eine andere Organisation organization hinzufügen
GitHub Enterprise Server organization und oidc_issuer hinzufügen (https://<github host>/_services/token), oder beides in ghinfo setzen
Ein Environment (älterer Stil) environment statt environments