1. Überblick
Dieses Dokument beschreibt die Installation und Konfiguration des Moduls aws-services-s3deployment für die Veröffentlichung der Inhalte aus FirstSpirit in ein AWS 3-Bucket. Das Modul bietet die Funktion, Dateien, die bei einer FirstSpirit-Generierung entstehen, aus dem Staging-Verzeichnis in ein S3-Bucket hochzuladen. Falls vorhanden und entsprechend konfiguriert, wird auch der Cache aus einem CloudFront CDN invalidiert. Die Funktion des Moduls umfasst Voll-, Teil- und Delta-Generierungen. Details dazu werden in den entsprechenden Kapiteln erläutert.
2. Systemvoraussetzungen
Das Modul kann nur in Kombination mit dem aws-services-base-Modul verwendet werden und setzt einen FirstSpirit-Server in mind. Version 5.2.190808 (Isolated) voraus.
Damit die Cacheinvalidierung im Rahmen des Deployments ausgeführt wird, muss in der AWS-Konsole die Richtlinie für CloudFront ggf. angepasst werden, sodass die DistributionConfig abgefragt werden kann. Mehr Details findet man in der offiziellen Dokumentation (der notwendige REST-Endpunkt ist GetDistributionConfig).
3. Installation und Konfiguration
3.1. Installation des Moduls
Die Module aws-services-base und aws-services-s3deployment-X.X.X.fsm werden über den FirstSpirit ServerManager im Bereich installiert. Gegebenenfalls muss nach der Installation das Modul noch um die Option Alle Rechte erweitert werden.
3.2. Konfigurationsmöglichkeiten für das Modul
Es gibt zwei Konfigurationsmöglichkeiten für das aws-services-s3deployment-Modul.
3.2.1. Zentrale Konfiguration über die Projekt-Komponente
Unter den Projekteigenschaften muss zuerst die Projekt-Komponente AWS Services Configuration ProjectApp hinzugefügt werden. Beim Betätigen des Buttons Konfigurieren öffnet sich ein Dialog, in dem die zentrale Konfiguration für installierte FirstSpirit-AWS-Module angelegt werden kann. Mithilfe des +-Buttons kann eine Konfiguration für das aws-services-s3deployment-Modul hinterlegt werden. Wird das Modul im SaaS-Umfeld eingesetzt, so können die Anmeldedaten (Access-Key, Secret-Key) leer gelassen werden. Diese werden aus der Umgebung ermittelt. Andernfalls müssen IAM-Credentials über die AWS-Konsole erstellt und eingetragen werden.
Im Allgemeinen bietet die Oberfläche folgende Möglichkeiten der Konfiguration:
| Feldname | Beschreibung | Beispielwert |
|---|---|---|
Configuration Name |
Der Bezeichner der hinterlegten Konfiguration (Pflichtfeld) |
AWS S3-Deployment |
Bucket-Name |
Der Bezeichner des S3-Buckets (Pflichtfeld) |
firstspirit.example.com |
Access-Key |
Anmeldename für die AWS-API |
xxxxxxx |
Secret-Key |
Passwort für die AWS-API |
xxxxxxx |
Region |
Region des S3-Buckets und der CloudFront-Distribution |
EU (Frankfurt) |
S3 Folder |
Name des Ordners im S3-Bucket. Der S3-Folder-Name muss mit dem S3-Origin beginnen. |
/de |
CloudFront Distribution ID |
ID der CloudFront-Distribution |
ES436346GR |
Deployment options |
Deployment-Typ, siehe Kapitel Auftragskonfiguration |
3.2.2. Auftragskonfiguration
Um eine Veröffentlichung in einen S3-Bucket auszuführen, öffnet man im gewünschten Projekt über den FirstSpirit ServerManager die Auftragsverwaltung und erstellt dort einen neuen Auftrag. Für eine Veröffentlichung in einen S3-Bucket muss ein Auftrag mindestens einen GenerateTask (Generierung ausführen) vor dem Deployment enthalten. Es können beliebige Aktionen davor und danach hinzugefügt werden.
| Feldname | Beschreibung | Beispielwert |
|---|---|---|
Task-Name |
Name der Aktion |
S3-Deployment Task |
Default Configuration from the Project App |
Name der Konfiguration aus der Projekt-Komponente, 'Configuration Name' |
AWS S3-Deployment |
Bucket-Name |
Name des Buckets |
|
Access-Key |
Anmeldename für die AWS-API |
xxxxxxxxx |
Secret-Key |
Passwort für die AWS-API |
xxxxxxxxx |
Region |
Region des S3-Buckets und der CloudFront-Distribution |
EU (Frankfurt) |
S3 Folder |
Pfad, unterhalb dem der Content publiziert wird. Der S3-Folder-Name muss mit dem S3-Origin beginnen. |
/de |
CloudFront Distribution ID |
ID der CloudFront-Distribution |
ES436346GR |
Deployment options |
siehe unten |
Keys
Wenn der FirstSpirit-Server in einer AWS EC2-Instanz betrieben wird, können die Informationen, die für das Modul relevant sind, über die AWS IAM-Rolle der EC2-Instanz ermittelt werden. In diesem Fall können die Felder Access-Key und Secret-Key, wie oben erwähnt, leer gelassen werden.
Deployment options
-
(leer):
Es wird die Einstellung aus der Projekt-Komponente verwendet. -
Auto detect (any partial generation leads to Deploy only):
Es wird die automatische Erkennung verwendet: Es werden alle aktiven Generierungsaufträge betrachtet, die in der Reihenfolge vor dem S3 Deployment Task liegen. Handelt es sich bei einem dieser Aufträge um eine partielle Generierung ('Teilgenerierung'), wird ein Deployment ohne Löschen durchgeführt. -
Complete sync (with deletion, use with full generation only!):
Das S3 Deployment wird mit Löschen von obsoleten Dateien im S3-Bucket durchgeführt. Diese Option sollte nur für Vollgenerierungen gewählt werden. -
Deploy only (no files will be deleted, usually used with partial generation):
Das S3 Deployment wird ohne Löschen von obsoleten Dateien im S3-Bucket durchgeführt. Diese Option bietet sich normalerweise für Teilgenerierungen an.
|
Es wird empfohlen, den zu den individuellen Projektanforderungen passenden Deployment-Typ über diese Dropdown-Box manuell auszuwählen und die automatische Erkennung (Option 'Auto detect') nicht zu verwenden. |
Automatische Erkennung
Wird die Option 'Auto detect' gewählt, versucht das Modul vor einem Deployment selbstständig zu ermitteln, um welchen Generierungstyp es sich im Auftrag handelt und agiert entsprechend:
-
Vollgenerierung
Bei einer Vollgenerierung wird der Inhalt des Staging-Verzeichnisses nach der normalen FirstSpirit-Generierung mit dem Inhalt des S3-Buckets verglichen. Bei Dateien, die in beiden Ordnern vorkommen, wird eine MD5-Prüfsumme berechnet und verglichen. Ist diese identisch, so wird die Datei nicht auf den S3-Bucket hochgeladen. Andernfalls wird die Datei im S3-Bucket überschrieben. Dateien, die im Staging-Verzeichnis vorkommen, aber im S3-Bucket fehlen, werden dorthin hochgeladen. Analog dazu werden Dateien, die im S3-Bucket, aber nicht im Staging-Verzeichnis vorkommen, aus dem Bucket gelöscht. Das heißt, der Stand im S3-Bucket wird so angepasst, dass er dem Staging-Verzeichnis entspricht.
|
Es wird empfohlen, die erste Generierungsaktion des Auftrags mit der Option |
-
Teilgenerierung
Bei einer Teilgenerierung werden nur ausgewählte Objekte aus FirstSpirit generiert. Es handelt sich im Standardfall um ein inkrementelles Verfahren (siehe auch ). Dementsprechend werden bei dieser Variante lediglich Dateien vom Staging-Verzeichnis in das S3-Bucket hochgeladen und keine Dateien gelöscht.
In einzelnen Fällen kann es auch bei einer Teilprojektgenerierung notwendig sein, bestimmte Teilbereiche löschen zu können. Durch Hinzufügen eines Skripts vor dem eigentlichen Deployment-Task kann die gewünschte Funktionalität konfiguriert werden (ab Version 1.5.8). In diesem Skript kann eine Liste mit Pfaden, beginnend mit dem Namen des S3-Buckets, gepflegt werden, sodass in den zugehörigen Teilbäumen ein kompletter Abgleich stattfindet.
Damit das S3-Deployment dieses Skript erkennt, muss folgendes Namensschema verwendet werden:
s3Conf_XXXX
wobei XXXX beliebig geändert werden kann.
Ein Skript kann beispielsweise wie folgt aussehen:
List<String> list = new ArrayList();
list.add("myBucketFolder/pl-pl");
list.add("myBucketFolder/en-pl");
context.setProperty("fullMatching", list);
Dieses Skript sorgt dafür, dass während des S3-Deployments die Ordner pl-pl und en-pl vollständig abgeglichen werden (inklusive Löschen). Alle übrigen Ordner werden nur inkrementell abgeglichen, also ohne zu löschen.
|
Entsprechende Skripte haben nur einen Effekt, wenn |
4. Benutzerdefiniertes Caching
AWS S3 ermöglicht es den Cache-Control-Header von Dateien zu manipulieren.
Für folgende Dateitypen werden vom aws-s3-deployment-Modul automatisch Header gesetzt:
| Dateityp | Metadaten |
|---|---|
.js |
Cache-Control: max-age=2592000 |
Cache-Control: no-cache |
|
.gif |
Cache-Control: max-age=2592000 |
jpeg, .jpg |
Cache-Control: max-age=2592000 |
.png |
Cache-Control: max-age=2592000 |
.svg |
Cache-Control: max-age=2592000 |
.ico |
Cache-Control: max-age=2592000 |
.woff |
Cache-Control: max-age=2592000 |
.woff2 |
Cache-Control: max-age=2592000 |
.eot |
Cache-Control: max-age=2592000 |
.ttf |
Cache-Control: max-age=2592000 |
.htm, .html, .shtml, .xhtml |
Cache-Control: no-cache |
.css |
Cache-Control: max-age=2592000 |
.txt |
Cache-Control: no-cache |
.mp4 |
Cache-Control: max-age=2592000 |
.json |
Cache-Control: no-cache |
.xml |
Cache-Control: no-cache |
5. CloudFront-Invalidierung
Ist, wie in Kapitel Installation und Konfiguration beschrieben, eine CloudFront Distribution ID angegeben, so führt jede Generierung auch zu einer Invalidierung der geänderten Dateien im AWS-CloudFront-Cache. Eine ausführliche Beschreibung zu diesem Thema finden Sie bei AWS.
Die Invalidierung kann dabei auf drei Arten stattfinden.
- Datei-Invalidierung
-
Hat sich eine Datei in einem Ordner geändert, so wird nur der Pfad zu der Datei invalidiert.
Beispiel
-
Generierungsordner
/my_site/index.html*geändert -
S3-Bucket
/my_site/index.html` -
Invalidierungen
/my_site/index.html
-
- Ordner-Invalidierung
-
Befindet sich in ein Ordner auf der Ebene einer Datei-Invalidierung, so wird der gesamte Pfad zum Vaterknoten invalidiert. Ändert sich mehr als eine Datei, erstellt das Modul eine Wildcard-Invalidierung.
Beispiel
-
Generierung
/my_site/index.html*geändert
/my_other_site/index.html*geändert
/my_other_site/index_2.html*geändert -
S3-Bucket
/my_site/index.html+/my_other_site/index.html
/my_other_site/index_2.html -
Invalidierungen
/my_site/index.html
/my_other_site*
/my_other_site
/my_other_site/
-
- Globale Invalidierung
-
Wird bei einer Ordner-Invalidierung das Limit für Wildcard-Invalidierungen erreicht (vorgegeben durch AWS), so löst das Modul eine globale Invalidierung aus, bei der alle Pfade betroffen sind. Dadurch kann auch der Cache von unveränderten Dateien betroffen sein. Das Modul sieht aktuell ein Limit von 15 Wildcard-Invalidierungen vor.
Invalidierung bei CloudFront
/*
5.1. Pfad-Diskrepanzen
Pfade in Invalidierungen können sich von Pfaden zu Dateien in einem S3-Bucket unterscheiden. Das liegt daran, dass die beiden Services nur lose miteinander verbunden sind. Bei einer CloudFront-Distribution wird konfiguriert, wo sich der Hauptknoten (auch: root-Knoten) des verknüpften S3-Buckets befindet. Von dort aus arbeitet CloudFront relativ.
Beispiel
-
S3 Bucket
s3:/
s3:/de
s3:/en` -
CloudFront
Hauptknoten:/de
https://my-example-de.e-spirit.cloud
Ist ein Auftrag so eingerichtet, dass er in den S3-Ordner /de deployed, so wird ein Generat entsprechend unter diesem Knoten hochgeladen. Die verknüpfte CloudFront-Distribution my-example-de.e-spirit.cloud arbeitet, wie dargestellt, dann relativ zu diesem Ordner.
Beispiel
-
Generierung
file:///my-page/index.html(FirstSpirit)
s3:/de/my-page/index.html(S3-Bucket)
https:/my-example-de.e-spirit.cloud/my-page/index.html(CloudFront)
Eine passende Invalidierung im Auftragslog sollte wie folgt aussehen: Invalidated /my-page/index.html
Gerade bei sprachabhängigen Generierungen kann dies zu Verwirrung führen:
Beispiel
-
Generierung
file:////en/my-page/index.html(FirstSpirit)
s3:/de/en/my-page/index.html(S3-Bucket)
https://my-example-de.e-spirit.cloud/en/my-page/index.html(CloudFront)
5.1.1. Ordner-Weiterleitung
(Der nachfolgende Absatz betrifft hauptsächlich FirstSpirit-Cloud-Kunden.)
Bei Webservern ist es gängig, dass der Aufruf eines Ordners in einer URL zur Weiterleitung z.B. auf die Datei index.html führt. Da es sich bei CloudFront jedoch nicht um einen Webserver handelt, gewährt Crownpeak die Weiterleitung über eine Lambda-Funktion (vgl. defaultRootObject im Kapitel Architektur in der FS Cloud). Die Funktion gewährt nicht nur die Weiterleitung, sondern führt auch zu einem neuen Cache-Eintrag in der CloudFront-Distribution. Somit finden sich gleiche Ressourcen unter verschiedenen URLs mit - potenziell - unterschiedlichen Cache-Zeitpunkten.
Beispiel
Die Datei /my-page/index.html wird in S3 neu erstellt und ist nun unter my-example.e-spirit.cloud/my-page/index.html sowie my-example.e-spirit.cloud/my-page/ erreichbar. Beide Pfade werden über einen Nutzer aufgerufen. Der CloudFront-Cache tritt nun in Kraft.
Es gibt eine Änderung der Datei /my-page/index.html. Der Auftragslog zeigt:
Invalidated /my-page/index.html
Invalidated /my-page
Invalidated /my-page/5.1.2. Weiterleitungen (mit aws-services-urlredirect)
(Der nachfolgende Absatz betrifft hauptsächlich FirstSpirit-Cloud-Kunden.)
Sollten Sie in ihrem Projekt das Modul aws-services-urlredirect verwenden, so gelten hier andere Regeln für eine Invalidierung als für die Ordner-Weiterleitung, da hier nur der Viewer-Request invalidiert wird. Für einen tieferen Einblick empfiehlt sich an dieser Stelle die AWS Dokumentation zu CloudFront.
5.2. Erlaubte Pfade/Zeichen
CloudFront limitiert die Menge der zulässigen Zeichen in einem Invalidierungspfad auf den Zeichensatz nach RFC 1738 2.2. URL Character Encoding Issues (aus Amazon Cloud Front Dev Guide Specifying the Files to Invalidate (p. 85)).
Zitat:
Non-ASCII or unsafe characters in the path: If the path includes non-ASCII characters or unsafe characters as defined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL-encode those characters. Do not URL-encode any other characters in the path, or CloudFront will not invalidate the old version of the updated file.
Das AWS Services S3-Deployment-Modul konvertiert lediglich nicht-ASCII Zeichen wie z. B. die deutschen Sonderzeichen (ä, ö, ü, ß), den asiatischen Zeichensatz, usw. Diese Konvertierung basiert auf der Implementierung der java.net.URI.toASCIIString()-JDK-Methode nach RFC 2396. Die sogenannten unsicheren (en. unsafe) und reservierten (en. reserved) Zeichen werden von der Implementierung - und damit vom Modul - nicht konvertiert und dürfen somit bei einer Generierung weder im Pfad noch im Dateinamen enthalten sein. Die Invalidierung in der CloudFront wird dann für alle gelisteten Pfade der Anfrage fehlschlagen.
|
Bitte beachten Sie, dass ein S3-Deployment dennoch erfolgreich sein kann und die Dateien auf dem S3-Bucket aktualisiert werden. Sollte ein Gebrauch von unsicheren oder reservierten Zeichen notwendig sein, so ist die Konvertierung begrenzt über eine eigene Implementierung des UrlFactory-Interfaces möglich. |
7. Hilfe
Der Technical Support der e-Spirit AG bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.