Add some deployments docs & example (#96)

Signed-off-by: Igor Shishkin <me@teran.dev>

README.md

@@ -50,11 +50,96 @@ if storing copies.
 archived is built with microservice architecture containing the following
 components:
 
-* publisher - HTTP server to allow data listing and fetching
-* manager - gRPC API to manage containers, versions and objects
+* archived-publisher - HTTP server to allow data listing and fetching
+* archived-manager - gRPC API to manage containers, versions and objects
+* archived-exporter - Prometheus metrics exporter for metadata entities
 * CLI - CLI application to interact with manage component
 * migrator - metadata migration tool
 
+## Deploy
+
+archived is distributed as a number of prebuilt binaries which allows to choose
+any particular way to deploy it from systemd services to Kubernetes.
+
+The main things are required to know before deployment:
+
+* archived-publisher can use RO replica of PostgreSQL for operation
+    and can scale
+* archived-manager requires RW PostgreSQL instance since it performs
+    writes, can also scale
+* archived-exporter is sufficient to run in the only copy since it just
+    provides metrics for the database stuff, RO replica access is also enough
+* archived-migrator must be ran each time archived is upgrading right before
+    other components
+* archived-cli could run anywhere and will require network access to
+    archived-manager
+* there's no authentication on any stage at the moment (yes, even for
+    cli/manager)
+
+An example for Kubernetes deployment specs is available in
+[docs/examples/deploy/k8s](docs/examples/deploy/k8s) directory.
+
+## CLI
+
+archived-cli provides an CLI interface to operate archived including creating
+containers, versions and objects. It works with archived-manager to handle
+requests.
+
+```shell
+usage: archived-cli --endpoint=ENDPOINT [<flags>] <command> [<args> ...]
+
+CLI interface for archived
+
+
+Flags:
+      --[no-]help          Show context-sensitive help (also try --help-long and --help-man).
+  -d, --[no-]debug         Enable debug mode ($ARCHIVED_CLI_DEBUG)
+  -t, --[no-]trace         Enable trace mode (debug mode on steroids) ($ARCHIVED_CLI_TRACE)
+  -s, --endpoint=ENDPOINT  Manage API endpoint address ($ARCHIVED_CLI_ENDPOINT)
+      --[no-]insecure      Do not use TLS for gRPC connection
+      --[no-]insecure-skip-verify
+                           Do not perform TLS certificate verification for gRPC connection
+      --cache-dir="~/.cache/archived/cli/objects"
+                           cache directory for objects
+
+Commands:
+help [<command>...]
+    Show help.
+
+container create <name>
+    create new container
+
+container delete <name>
+    delete the given container
+
+container list
+    list containers
+
+version create [<flags>] <container>
+    create new version for given container
+
+version delete <container> <version>
+    delete the given version
+
+version list <container>
+    list versions for the given container
+
+version publish <container> <version>
+    publish the given version
+
+object list <container> <version>
+    list objects in the given container and version
+
+object create <container> <version> <path>
+    create object(s) from location
+
+object url <container> <version> <key>
+    get URL for the object
+
+object delete <container> <version> <key>
+    delete object
+```
+
 ## How build the project manually
 
 archived requires the following dependencies to build:

docs/examples/deploy/k8s/000-namespace.yaml

@@ -0,0 +1,7 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: archived
+  labels:
+    app: archived

docs/examples/deploy/k8s/001-postgresql-cluster.yaml

@@ -0,0 +1,69 @@
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: metadatadb
+  namespace: archived
+spec:
+  instances: 3
+  imageName: ghcr.io/cloudnative-pg/postgresql:16.3-7
+
+  minSyncReplicas: 2
+  maxSyncReplicas: 2
+
+  postgresql:
+    syncReplicaElectionConstraint:
+      enabled: true
+      nodeLabelsAntiAffinity:
+        - topology.kubernetes.io/node
+
+  replicationSlots:
+    highAvailability:
+      enabled: true
+    updateInterval: 10
+
+  primaryUpdateStrategy: unsupervised
+  switchoverDelay: 60
+  storage:
+    pvcTemplate:
+      resources:
+        requests:
+          storage: 30Gi
+      storageClassName: openebs-hostpath
+      volumeMode: Filesystem
+    resizeInUseVolumes: false
+
+  resources:
+    requests:
+      memory: "1Gi"
+      cpu: 1
+    limits:
+      memory: "1Gi"
+      cpu: 1
+
+  backup:
+    barmanObjectStore:
+      destinationPath: "s3://<CHANGEME: backup bucket>"
+      endpointURL: https://s3.example.com # (CHANGEME: s3 endpoint)
+      s3Credentials:
+        accessKeyId:
+          name: cnpg-backup-creds
+          key: ACCESS_KEY_ID
+        secretAccessKey:
+          name: cnpg-backup-creds
+          key: ACCESS_SECRET_KEY
+    retentionPolicy: "30d"
+
+  monitoring:
+    enablePodMonitor: true
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: ScheduledBackup
+metadata:
+  name: metadatadb-backups
+  namespace: archived
+spec:
+  schedule: "0 58 */9 * * *"
+  backupOwnerReference: self
+  cluster:
+    name: metadatadb

docs/examples/deploy/k8s/002-configmap.yaml

@@ -0,0 +1,10 @@
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: s3-blob-repository
+  namespace: archived
+data:
+  BLOB_S3_ENDPOINT: https://s3.example.com # (CHANGEME: s3 endpoint)
+  BLOB_S3_BUCKET: "<CHANGEME: blob bucket>"
+  BLOB_S3_CREATE_BUCKET: "true"

docs/examples/deploy/k8s/003-migrator-job.yaml

@@ -0,0 +1,30 @@
+---
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: archived-migrator
+  namespace: archived
+  labels:
+    app.kubernetes.io/name: archived-migrator
+    app.kubernetes.io/app: archived-migrator
+spec:
+  template:
+    metadata:
+      name: archived-migrator
+      labels:
+        app.kubernetes.io/name: archived-migrator
+        app.kubernetes.io/app: archived-migrator
+    spec:
+      containers:
+        - name: migrator
+          image: ghcr.io/teran/archived/migrator:latest
+          imagePullPolicy: Always
+          env:
+            - name: METADATA_DSN
+              valueFrom:
+                secretKeyRef:
+                  name: metadatadb-app
+                  key: uri
+            - name: LOG_LEVEL
+              value: "trace"
+      restartPolicy: OnFailure

docs/examples/deploy/k8s/README.md

@@ -0,0 +1,14 @@
+# Kubernetes deployment example
+
+## Prerequisites
+
+* ingress-nginx
+* openebs with hostpath enabled for PVC
+* VictoriaMetrics or Prometheus operator for PodMonitors
+* CloudNativePG for PostgreSQL
+* External S3 service to store blobs
+
+## Deploy
+
+* Change all the fields marked as "CHANGEME" to appropriate values
+* `kubectl apply -f .`

docs/examples/deploy/k8s/archived-exporter.yaml

@@ -0,0 +1,69 @@
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: archived-exporter
+  namespace: archived
+  labels:
+    app.kubernetes.io/name: archived-exporter
+    app.kubernetes.io/app: archived-exporter
+spec:
+  replicas: 1
+  strategy:
+    type: RollingUpdate
+  revisionHistoryLimit: 10
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: archived-exporter
+      app.kubernetes.io/app: archived-exporter
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: archived-exporter
+        app.kubernetes.io/app: archived-exporter
+    spec:
+      affinity:
+        podAntiAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+          - labelSelector:
+              matchExpressions:
+              - key: app.kubernetes.io/app
+                operator: In
+                values:
+                - archived-exporter
+            topologyKey: "kubernetes.io/node"
+      terminationGracePeriodSeconds: 30
+      containers:
+        - name: exporter
+          image: ghcr.io/teran/archived/exporter:latest
+          imagePullPolicy: Always
+          env:
+            - name: METADATA_DSN
+              valueFrom:
+                secretKeyRef:
+                  name: metadata-database-ro
+                  key: METADATA_DSN_RO
+            - name: LOG_LEVEL
+              value: "trace"
+          ports:
+            - name: metrics
+              containerPort: 8081
+              protocol: TCP
+          resources:
+            requests:
+              cpu: 10m
+              memory: 128Mi
+            limits:
+              memory: 1Gi
+          readinessProbe:
+            httpGet:
+              path: /metrics
+              port: metrics
+            timeoutSeconds: 1
+          livenessProbe:
+            httpGet:
+              path: /metrics
+              port: metrics
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true

docs/examples/deploy/k8s/archived-gc.yaml

@@ -0,0 +1,35 @@
+---
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: archived-gc
+  namespace: archived
+  labels:
+    app.kubernetes.io/name: archived-gc
+    app.kubernetes.io/app: archived-gc
+spec:
+  schedule: "48 * * * *"
+  jobTemplate:
+    spec:
+      template:
+        metadata:
+          name: archived-gc
+          labels:
+            app.kubernetes.io/name: archived-gc
+            app.kubernetes.io/app: archived-gc
+        spec:
+          containers:
+            - name: gc
+              image: ghcr.io/teran/archived/gc:latest
+              imagePullPolicy: Always
+              env:
+                - name: METADATA_DSN
+                  valueFrom:
+                    secretKeyRef:
+                      name: metadatadb-app
+                      key: uri
+                - name: LOG_LEVEL
+                  value: "trace"
+                - name: DRY_RUN
+                  value: "false"
+          restartPolicy: OnFailure