S3

Bewaar projectbestanden en geschiedenis in S3-compatibele opslag in een Kubernetes-deployment.

Projectbestanden en hun geschiedenis worden opgeslagen door de history-v1-service, sjabloonbestanden door de filestore-service, beide in elke Ayakaleaf Pro-pod. Standaard schrijven ze naar het datavolume; met S3 schrijven ze naar buckets. Welke buckets en rechten nodig zijn, staat beschreven in S3.

Services	history-v1 (projectbestanden en geschiedenis), filestore (sjabloonbestanden), in elke Ayakaleaf Pro-pod
Pod → S3	het S3-endpoint, voor elk bestand dat wordt gelezen of geschreven
Vereist	voor meerdere replica’s: hun datavolumes worden niet gedeeld, de buckets wel
Periodieke taken	geen

Kies voor S3 voordat gebruikers projecten aanmaken. Een instantie die al bestanden op haar volume bewaart, heeft eerst de S3-migratie nodig.

​

Configuratie

1. Buckets en sleutels

   Maak de drie buckets overleaf-template-files, overleaf-project-blobs en overleaf-chunks en de twee beperkte gebruikers aan bij je S3-dienst zoals beschreven in S3-installatie, of draai Garage in het cluster zoals hieronder getoond. Zet de vier sleutels in een Secret:

   kubectl -n overleaf create secret generic overleaf-s3 \
     --from-literal=OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID=<filestore key> \
     --from-literal=OVERLEAF_FILESTORE_S3_SECRET_ACCESS_KEY=<filestore secret> \
     --from-literal=OVERLEAF_HISTORY_S3_ACCESS_KEY_ID=<history key> \
     --from-literal=OVERLEAF_HISTORY_S3_SECRET_ACCESS_KEY=<history secret>
   
2. ConfigMap

   30-config.yaml (additions)

     OVERLEAF_FILESTORE_BACKEND: s3
     OVERLEAF_FILESTORE_TEMPLATE_FILES_BUCKET_NAME: overleaf-template-files
     OVERLEAF_FILESTORE_S3_REGION: eu-west-1
     OVERLEAF_HISTORY_BACKEND: s3
     OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET: overleaf-project-blobs
     OVERLEAF_HISTORY_CHUNKS_BUCKET: overleaf-chunks
     OVERLEAF_HISTORY_S3_REGION: eu-west-1
     # a self-hosted S3 service also needs its endpoint and path-style addressing
     # OVERLEAF_FILESTORE_S3_ENDPOINT: http://garage:3900
     # OVERLEAF_FILESTORE_S3_PATH_STYLE: "true"
     # OVERLEAF_HISTORY_S3_ENDPOINT: http://garage:3900
     # OVERLEAF_HISTORY_S3_PATH_STYLE: "true"
   
3. Voeg de Secret toe aan de pod en herstart

   Voeg in de Deployment (of StatefulSet) de Secret toe naast de andere:

             envFrom:
               - configMapRef: {name: overleaf-env}
               - secretRef: {name: overleaf-secrets}
               - secretRef: {name: overleaf-s3}
   

   kubectl apply -f 30-config.yaml -f 40-overleaf.yaml
   kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
   

​

Garage in het cluster

Zonder S3-dienst is Garage een kleine S3-server die in het cluster draait. De opzet uit Horizontaal schalen is ermee getest. De onderstaande commando’s genereren zelf de sleutels en maken de Secret overleaf-s3 aan, dus gebruik ze in plaats van het Secret-commando in stap 1.

MinIO, dat in het voorbeeld van Overleaf wordt gebruikt, publiceert geen container-images meer: minio/minio is verdwenen van Docker Hub en quay.io.

50-garage.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: garage-config
  namespace: overleaf
data:
  garage.toml: |
    metadata_dir = "/var/lib/garage/meta"
    data_dir = "/var/lib/garage/data"
    db_engine = "lmdb"
    replication_factor = 1
    rpc_bind_addr = "[::]:3901"
    rpc_public_addr = "127.0.0.1:3901"
    # rpc_secret and admin_token come from GARAGE_RPC_SECRET / GARAGE_ADMIN_TOKEN
    [s3_api]
    s3_region = "garage"          # Overleaf's OVERLEAF_*_S3_REGION must match
    api_bind_addr = "[::]:3900"
    [admin]
    api_bind_addr = "[::]:3903"
---
apiVersion: v1
kind: Service
metadata:
  name: garage
  namespace: overleaf
spec:
  selector:
    app: garage
  ports:
    - name: s3
      port: 3900
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: garage
  namespace: overleaf
spec:
  serviceName: garage
  replicas: 1
  selector:
    matchLabels:
      app: garage
  template:
    metadata:
      labels:
        app: garage
    spec:
      containers:
        - name: garage
          image: dxflrs/garage:v2.5.0
          env:
            - name: GARAGE_RPC_SECRET
              valueFrom: {secretKeyRef: {name: garage-secrets, key: rpc_secret}}
            - name: GARAGE_ADMIN_TOKEN
              valueFrom: {secretKeyRef: {name: garage-secrets, key: admin_token}}
          ports:
            - containerPort: 3900
          readinessProbe:
            tcpSocket:
              port: 3900
          resources:
            requests: {cpu: 50m, memory: 64Mi}
            limits: {memory: 512Mi}
          volumeMounts:
            - {name: config, mountPath: /etc/garage.toml, subPath: garage.toml}
            - {name: data, mountPath: /var/lib/garage}
      volumes:
        - name: config
          configMap:
            name: garage-config
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: [ReadWriteOnce]
        resources:
          requests:
            storage: 10Gi

Genereer de secrets, start Garage en maak daarna de layout, de buckets en de twee beperkte sleutels aan. Garage-sleutel-ID’s zijn GK plus 24 hexadecimale tekens, secrets 64 hexadecimale tekens:

kubectl -n overleaf create secret generic garage-secrets \
  --from-literal=rpc_secret="$(openssl rand -hex 32)" \
  --from-literal=admin_token="$(openssl rand -base64 32)"
kubectl -n overleaf create secret generic overleaf-s3 \
  --from-literal=OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID="GK$(openssl rand -hex 12)" \
  --from-literal=OVERLEAF_FILESTORE_S3_SECRET_ACCESS_KEY="$(openssl rand -hex 32)" \
  --from-literal=OVERLEAF_HISTORY_S3_ACCESS_KEY_ID="GK$(openssl rand -hex 12)" \
  --from-literal=OVERLEAF_HISTORY_S3_SECRET_ACCESS_KEY="$(openssl rand -hex 32)"
kubectl apply -f 50-garage.yaml
kubectl -n overleaf rollout status statefulset/garage

g() { kubectl -n overleaf exec garage-0 -- /garage "$@"; }
s() { kubectl -n overleaf get secret overleaf-s3 -o jsonpath="{.data.$1}" | base64 -d; }
g layout assign -z dc1 -c 8G "$(g status 2>/dev/null | awk '/^[0-9a-f]{16}/{print $1; exit}')"
g layout apply --version 1
for b in overleaf-template-files overleaf-project-blobs overleaf-chunks; do g bucket create "$b"; done
g key import --yes -n overleaf-filestore "$(s OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID)" "$(s OVERLEAF_FILESTORE_S3_SECRET_ACCESS_KEY)"
g key import --yes -n overleaf-history "$(s OVERLEAF_HISTORY_S3_ACCESS_KEY_ID)" "$(s OVERLEAF_HISTORY_S3_SECRET_ACCESS_KEY)"
g bucket allow --read --write overleaf-template-files --key overleaf-filestore
g bucket allow --read overleaf-project-blobs --key overleaf-filestore
g bucket allow --read --write overleaf-project-blobs --key overleaf-history
g bucket allow --read --write overleaf-chunks --key overleaf-history

De rechten komen overeen met de policy’s in S3. Garage controleert de regio: die is hier garage, en OVERLEAF_*_S3_REGION moet hetzelfde zijn.

Stel met Garage voor beide services in de ConfigMap het endpoint, PATH_STYLE: "true" en de regio garage in, zoals in 60-config.yaml van Horizontaal schalen.

​

Meerdere replica’s

Alle replica’s moeten dezelfde buckets en sleutels gebruiken. Maak back-ups van de buckets met de tools van je S3-provider; de eigen schijven van de replica’s bevatten dan geen gegevens waarvan een back-up nodig is.

​

Getest op Kubernetes

Op Kubernetes 1.37 met drie replica’s en Garage zoals hierboven, slaagde elke end-to-endtest van deze pagina’s die projecten aanmaakt, bestanden uploadt, de geschiedenis gebruikt of sjablonen publiceert, en daarna bevatten de buckets overleaf-project-blobs, overleaf-chunks en overleaf-template-files de objecten, terwijl de eigen /var/lib/overleaf/data/history van de replica’s leeg bleef.