Deployment-Pipeline

Der TemplateDesigner kann über die Azure-DevOps-Pipeline TemplateDesigner.CD automatisiert für einen oder mehrere Kunden ausgerollt werden. Die Pipeline lädt das gewünschte Universal Package, erstellt die kundenspezifische appsettings.json und kopiert die Anwendung an das konfigurierte Ziel.

Die technische Dokumentation für Entwickler befindet sich auf dieser Seite. Informationen zur Einrichtung und zum Betrieb durch die IT sind in der TemplateDesigner-Dokumentation im Confluence beschrieben.

Unterstützte Versionen

Das automatisierte Deployment wird erst ab den folgenden TemplateDesigner-Releases unterstützt:

52.1.2 innerhalb der Release-Linie 52.1
52.2.0 innerhalb der Release-Linie 52.2
ab 53.0.0 alle Versionen, einschliesslich späterer Hauptversionen wie 54.x, 55.x usw.

Ältere Releases müssen weiterhin nach dem bisherigen manuellen Verfahren ausgerollt werden.

Alle verfügbaren TemplateDesigner-Versionen können im Azure-DevOps-Artifact-Feed eingesehen werden.

Pipeline ausführen

Die Pipeline wird manuell gestartet und erwartet folgende Parameter:

Parameter	Beschreibung
`version`	Version des Universal Packages aus dem Azure-DevOps-Artifact-Feed. Mit `*` wird die neueste Release-Version ermittelt. Pre-Release-Versionen müssen vollständig angegeben werden.
`environment`	Zielumgebung `TEST` oder `PROD`.
`customers`	Ein oder mehrere Kunden, für die das Deployment ausgeführt wird.

Für jeden ausgewählten Kunden wird eine eigene Stage erzeugt. Dadurch sind Status und Fehler pro Kunde getrennt ersichtlich.

Bei einem PROD-Deployment ist vor dem Kopieren eine manuelle Freigabe durch Sec_ICT_Application erforderlich. Die Freigabe läuft nach acht Stunden automatisch ab und das Deployment wird abgelehnt.

Es wird empfohlen, zuerst nach TEST und erst nach erfolgreicher Prüfung nach PROD zu deployen. Für ein reproduzierbares Deployment sollte nach Möglichkeit eine konkrete Version anstelle von * verwendet werden.

Ablauf

Die Pipeline führt pro Kunde folgende Schritte aus:

Die gewünschte Version des Universal Package eis.elego.templatedesigner wird ermittelt und heruntergeladen.
Die appsettings.json wird kundenspezifisch konfiguriert.
Die erzeugte JSON-Datei wird validiert und formatiert.
Der Inhalt des Packages wird in das konfigurierte Zielverzeichnis kopiert. Das Zielverzeichnis wird zuvor bereinigt.

Für QS wird DefaultEndpointConfigs aus der lokalen Datei auf dem QS-Server gelesen:

C:\Program Files (x86)\TemplateDesigner\TemplateDesigner-config\config.json

Bei allen anderen Kunden wird der Token __DefaultEndpointConfigs__ mit dem Wert aus der kundenspezifischen Azure-DevOps-Variablengruppe ersetzt. Fehlende Variablen oder ein fehlender QS-Token brechen das Deployment ab.

Deployment-Arten und Zielpfade

Der Kunde wird in environment-map.yaml einer Deployment-Art zugeordnet. Abhängig davon wird auf einer Azure-DevOps-VM-Ressource oder über einen Windows-Agent auf ein Netzwerkverzeichnis ausgerollt. Die folgende Tabelle zeigt die exakten Zielpfade, die von der Pipeline verwendet werden:

Deployment-Art	Ausführung	TEST-Zielpfad	PROD-Zielpfad
`TemplateDesigner-Testing`	VM-Ressource, derzeit QS	`$(DeploymentPathTest)/$(templateDesignerVersion)`	`$(DeploymentPathProd)/$(templateDesignerVersion)`
`TemplateDesigner-Local`	`EIS Azure Pool`, Zugriff auf Netzwerkpfad	`$(DeploymentPathTest)/$(customer)/$(templateDesignerVersion)`	`$(DeploymentPathProd)/$(customer)/$(templateDesignerVersion)`
`TemplateDesigner-Shared`	VM-Ressource	`$(DeploymentPathTest)`	`$(DeploymentPathProd)`
`TemplateDesigner-ECX`	VM-Ressource	`$(DeploymentPathTest)/$(templateDesignerVersion)`	`$(DeploymentPathProd)/$(templateDesignerVersion)`

CopyFiles@2 kopiert jeweils den Inhalt des heruntergeladenen templateDesigner-Verzeichnisses direkt in diesen Zielpfad. Es wird kein zusätzliches Verzeichnis namens templateDesigner erzeugt.

Neuen Kunden aufnehmen

Für einen neuen Kunden sind Anpassungen im Repository und in Azure DevOps erforderlich.

Repository anpassen

Den Kundennamen in .azure-pipelines/templatedesigner.yaml unter parameters.customers.values ergänzen.
Den gleichen Kundennamen in .azure-pipelines/variables/templateDesigner/environment-map.yaml ergänzen und dem passenden deploymentEnvironment zuordnen.
In beiden Listen die alphabetische Reihenfolge einhalten. QS bleibt als Ausnahme immer an erster Stelle.

TemplateDesigner-Testing ist derzeit QS vorbehalten. Neue reguläre Kunden werden abhängig von ihrer Infrastruktur TemplateDesigner-Local, TemplateDesigner-Shared oder TemplateDesigner-ECX zugeordnet. Die Zuordnung ist mit der IT abzustimmen.

Die Schreibweise des Kunden muss in beiden Dateien exakt übereinstimmen. Dieser Wert wird auch zum Auflösen der Variablengruppe verwendet:

TemplateDesigner_<Kunde>

Beispiel für den Kunden Muster:

Pipeline-Eintrag: Muster
Variablengruppe:  TemplateDesigner_Muster

Azure DevOps durch die IT konfigurieren lassen

Die IT erstellt die Variablengruppe TemplateDesigner_<Kunde>, setzt die Werte und gibt die Gruppe für die Pipeline frei. Die Variablengruppe enthält immer folgende Variablen:

Variable	Zweck
`DeploymentPathTest`	Basis-Zielpfad für TEST-Deployments
`DeploymentPathProd`	Basis-Zielpfad für PROD-Deployments
`DefaultEndpointConfigs`	Gültiger JSON-Wert für den Token `__DefaultEndpointConfigs__`

Format von `DefaultEndpointConfigs`

Der Wert muss ein gültiges JSON-Array sein und daher mit [ beginnen und mit ] enden. Das Array enthält mindestens eine Konfiguration. Das Feld ElegoEndpoints ist ebenfalls ein Array und enthält pro Konfiguration mindestens einen, bei Bedarf mehrere Endpoints.

[
  {
    "Name": "",
    "ClientId": "templateDesigner_local",
    "Authority": "",
    "ElegoEndpoints": [
      {
        "Name": "",
        "ServiceUrl": "",
        "ElegoRoleScope": "",
        "ValidateIssuerName": false
      }
    ]
  }
]

Die kundenspezifischen Werte werden durch die IT eingesetzt. Anschliessend muss das vollständige JSON minifiziert und als einzeiliger Wert in der Variablengruppe gespeichert werden. Dafür kann beispielsweise JSON Minify verwendet werden. Vertrauliche Inhalte dürfen nicht in öffentliche Onlinedienste eingefügt oder dort gespeichert werden.

ValidateIssuerName ist ein Boolean und darf deshalb nicht in Anführungszeichen gesetzt werden. Vor dem Speichern muss geprüft werden, dass das minifizierte Ergebnis weiterhin mit [ beginnt, mit ] endet und gültiges JSON ist.

Die konkreten Werte werden ausschliesslich durch die IT gepflegt. Entwickler müssen jedoch sicherstellen, dass der Kundenname im YAML und das Suffix der Variablengruppe identisch sind.

Zusätzlich stellt die IT abhängig von der gewählten Deployment-Art Folgendes bereit:

eine erreichbare VM-Ressource im passenden Azure-DevOps-Environment,
beim Typ TemplateDesigner-Local stattdessen den Netzwerkzugriff für den Windows-Agent,
Lesezugriff auf das Universal Package und
Schreibberechtigung auf die konfigurierten TEST- und PROD-Zielpfade.

Nach der Einrichtung muss mindestens ein TEST-Deployment für den neuen Kunden durchgeführt und die erzeugte appsettings.json sowie der Zielpfad geprüft werden.