====== CHP: Static CDN ======
Omdat traffic kosten uit een public cloud meestal erg hoog zijn en
~90% van alle traffic uit websites statische content is (css, js,
png, gif, etc.) hebben wij het "Static CDN" opgezet. Dit hebben wij
opgezet met een partner die in Nederland uitgebreide CDN capaciteit
heeft en op deze manier is er de mogelijkheid om stevig te besparen
op de traffic kosten van de omroep websites.

Deze omgeving is opgezet op basis van een S3 compatible backend en
een caching frontend zodat alle objecten binnen de S3 omgeving snel
uitgeserveerd kunnen worden.  Dit static CDN is opgezet om uitsluitend
publieke bestanden uit te serveren. Het is mogelijk om de buckets in
de S3 backend als private te gebruiken, maar daar adviseren wij de
AWS S3 omgeving voor, omdat deze dichter bij je applicatie draait.

Om toegang tot het Static CDN aan te vragen hebben wij een aantal gegevens nodig:
  * CDN url: Deze is zelf te kiezen en kan iets zijn als bijv. cdn.omroep.tld
  * Cache tijd: Hoe lang de caching laag objecten mag cachen in minuten, bijv. 120 minuten
  * Toegang: Is een unieke access_key + secret gewenst, of mag deze met een bestaande bucket gedeeld worden.

Vervolgens na het aanmaken krijg je van ons terug: 
  * De Cached CDN URL
  * S3 Bucket URL
  * S3 Base URL
  * S3 Bucket Name
  * Access_key (als hier een nieuwe voor moest worden aangemaakt)
  * Secret_key (als hier een nieuwe voor moest worden aangemaakt)

De Access_key en Secret_key zullen wij in het CHP als secret toevoegen
zodat die ook verder geheim blijven.

====== Handleiding ======

===== Interactie met S3 =====
Interactie met S3 buckets is mogelijk door gebruik te maken van
diverse gestandaardiseerde CLI, SDK, API of visuele tools. Ondanks de
hosting van S3 storage buiten Amazon AWS, zijn de diverse tools die
gecertificeerd zijn voor het product van Amazon ook direct toepasbaar.

===== Voorbeeld interactie =====
Een voorbeeld van een CLI-tool is S3CMD, deze opensource tool
ondersteunt onder andere de koppeling met het storage platform en
alsmede interactie met buckets, objects en meer. Hieronder wordt
daarom kort de configuratie en interactie gebruikmakend van S3CMD
gedemonstreerd.

==== Configuratie van S3CMD ====
Het gebruik van S3CMD is afhankelijk van een configuratie bestand. Als
voorbeeld wordt er een nieuw configuratie bestand aangemaakt genaamd
‘configfile’. Hieraan wordt de volgende configuratie toegevoegd:

<code bash>
[default]
# Object Storage Region NL-AMS-1
host_base = objectstorage.nl-ams-1.scalia.io
host_bucket = %(bucket)s.objectstorage.nl-ams-1.scalia.io
use_https = True

# Login credentials
access_key = {YOUR ACCESS KEY}
secret_key = {YOUR SECRET KEY}
</code>


==== Voorbeeld uploaden bestand ====
Gebruikmakend van de eerder aangemaakte configuratie, kunnen er bestanden worden geüpload zoals in het voorbeeld hieronder: 
<code bash>
# Simple upload
s3cmd --config ./configfile PUT image.jpg s3://bucket
# Simple upload with path notation
s3cmd --config ./configfile PUT file.txt s3://bucket/path/folder
</code>

==== Voorbeeld policy wijziging ====
Afhankelijk van de bucket configuratie zijn alle bestanden standaard "public". Het is mogelijk om een specifiek bestand of folder andere ACL policies toe te kennen. De volgende ACL policies zijn mogelijk: 
  * READ, gerechtigde kan objecten lezen 
  * WRITE, gerechtigde kan objecten schrijven of verwijderen
  * READ_ACP, gerechtigde kan bucket ACL lezen
  * WRITE_ACP, gerechtigde kan bucket ACL wijzigen
  * FULL_CONTROL, gerechtigde heeft alle rechten objecten in de bucket

Hieronder volgt een voorbeeld om een ACL-entry te wijzigen: 
<code bash>
# Change ACL to public on a single file
s3cmd --config ./configfile setacl s3://bucket/path/to/file --acl-public
# Change ACL to public recursive
s3cmd --config ./configfile setacl -r s3://bucket --acl-public
</code>

==== CORS headers ====
Je kunt CORS headers via S3 en het CDN mee laten sturen door dit in te stellen op het bucket. Dit staat los van andere policies. Dit doe je als volgt:
  - Maak een xml met de gewenste cors policy
  - roep s3cmd aan met deze policy
  - Laat op CDN niveau de instellingen aanpassen om bij de "Cache key" te kiezen voor "Include Origin"

Voorbeeld: (pas WWW.WEBSITE.NL aan naar jouw website die requests gaat
doen naar deze bucket)
<code>
# file: cors.xml
<CORSConfiguration>
    <CORSRule>
        <ID>Allow WWW.WEBSITE.NL cors</ID>
        <AllowedOrigin>https://WWW.WEBSITE.NL</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedMethod>HEAD</AllowedMethod>
        <AllowedHeader>*</AllowedHeader>
        <MaxAgeSeconds>86400</MaxAgeSeconds>
    </CORSRule>
</CORSConfiguration>
</code>

Apply dit op de juiste bucket:
<code>
s3cmd --config ./configfile setcors cors.xml s3://bucket
</code>

Tot slot is het belangrijk dat het CDN hier de juiste caching policy voor
heeft. Hiervoor is het nodig om een ticket bij H&S in te schieten om
voor dit CDN de "Cache Key" te laten wijzigen naar "Include Origin".
Anders kunnen er namelijk cached responses met en zonder CORS headers
door elkaar gaan lopen.

===== Ondersteunde functies =====
De onderstaande functies worden ondersteund door het storage platform en kunnen door gebruik van een RESTful API worden benut. 

^ Functie                  ^ Status      ^
|List Buckets              | Ondersteund |
|Delete Bucket             | Ondersteund |
|Create Bucket             | Ondersteund |
|Bucket Lifecycle          | Ondersteund |
|Policy (Buckets, Objects) | Ondersteund |
|Bucket Website            | Ondersteund |
|Bucket ACLs (Get, Put)    | Ondersteund |
|Bucket Location           | Ondersteund |
|Bucket Notification       | Ondersteund |
|Bucket Object Versions    | Ondersteund |
|Get Bucket Info (HEAD)    | Ondersteund |
|Bucket Request Payment    | Ondersteund |
|Put Object                | Ondersteund |
|Delete Object             | Ondersteund |
|Get Object                | Ondersteund |
|Object ACLs (Get, Put)    | Ondersteund |
|Get Object Info (HEAD)    | Ondersteund |
|POST Object               | Ondersteund |
|Copy Object               | Ondersteund |
|Multipart Uploads         | Ondersteund |
|Object Tagging            | Ondersteund |
|Bucket Tagging            | Ondersteund |
|Storage Class             | Ondersteund |

===== Uitserveren bestanden =====
Dit hoofdstuk gaat over welke mogelijkheden er zijn om bestanden uit
te serveren. Het is een globale weergave van statische bestanden en
media streams. Er wordt vanuit gegaan dat er een basiskennis aanwezig
is over bestanden, bestandsstructuren en media encoding.

==== Statische bestanden ====
In het volgende overzicht staan de verschillende notaties van hoe
een URL is opgebouwd. Deze URL-templates kan men gebruiken voor
het implementeren van het S3 bucket op de plek waar de bestanden
uitgeserveerd moeten gaan worden.

^ URL Type       ^ URL                                             ^
| Private files  |<nowiki>https://<bucket>.<S3 base url>/bestandsnaam.ext</nowiki>|
| Public files   |<nowiki>https://<bucket>.<S3 base url>/bestandsnaam.ext</nowiki>|
| Cached CDN URL |<nowiki>https://<cached CDN url>/bestandsnaam.ext</nowiki>|
 
Indien bestanden publiekelijk uitgeserveerd worden op kleine of
grote schaal heeft het de voorkeur deze te serveren door middel van
het CDN-netwerk. Door gebruik te maken van het CDN-netwerk worden
uw bestanden nationaal gedistribueerd en over versnelde caches
uitgeserveerd aan uw gebruikers. Om het CDN-netwerk toegankelijker te
maken kunt u gebruik maken van de aan u specifiek toegewezen “Cached
CDN URL”.