feat(helm-chart): add helm-chart

charts/unstructured-api/.helmignore

@@ -0,0 +1,9 @@
+# Patterns to ignore when building packages.
+*.tgz
+.git
+.gitignore
+.idea/
+*.tmproj
+.vscode/
+ci/
+.DS_Store

charts/unstructured-api/Chart.yaml

@@ -0,0 +1,26 @@
+apiVersion: v2
+name: unstructured-api
+description: A Helm chart for the self-hosted Unstructured document-partitioning REST API.
+type: application
+# Chart version. Bump on any change to the chart itself.
+version: 0.1.0
+# The version of the unstructured-api application shipped by default (see values.yaml image.tag).
+appVersion: "0.1.10"
+kubeVersion: ">=1.23.0-0"
+home: https://github.com/Unstructured-IO/unstructured-api
+sources:
+  - https://github.com/Unstructured-IO/unstructured-api
+keywords:
+  - unstructured
+  - document-processing
+  - partitioning
+  - ocr
+  - nlp
+  - fastapi
+maintainers:
+  - name: Unstructured API contributors
+    url: https://github.com/Unstructured-IO/unstructured-api
+icon: https://raw.githubusercontent.com/Unstructured-IO/unstructured-api/main/img/unstructured_logo.svg
+annotations:
+  category: MachineLearning
+  licenses: Apache-2.0

charts/unstructured-api/README.md

@@ -0,0 +1,115 @@
+# unstructured-api
+
+Helm chart for the self-hosted [Unstructured API](https://github.com/Unstructured-IO/unstructured-api),
+a REST API that partitions documents with the
+[`unstructured`](https://github.com/Unstructured-IO/unstructured) library.
+
+It deploys a stateless Deployment behind a Service. The image bundles ML models, Tesseract OCR,
+and LibreOffice, so it is CPU/memory heavy — size `resources` accordingly for `hi_res` workloads.
+
+## Quick start
+
+```bash
+helm install unstructured-api ./charts/unstructured-api
+kubectl port-forward svc/unstructured-api 8000:80
+curl --fail http://localhost:8000/healthcheck
+```
+
+Requirements: Kubernetes >= 1.23, Helm >= 3.8, and a node that can fit
+`resources.requests` (default `500m` / `3Gi`).
+
+## Configuration
+
+Common values. See [`values.yaml`](./values.yaml) for the rest.
+
+### Image
+
+| Key | Default | Description |
+|---|---|---|
+| `image.repository` | `quay.io/unstructured-io/unstructured-api` | Image repository. |
+| `image.tag` | `""` | Image tag; defaults to the chart `appVersion`. |
+| `image.pullPolicy` | `IfNotPresent` | Pull policy. |
+| `imagePullSecrets` | `[]` | Secrets for a private registry. |
+
+### Workload
+
+| Key | Default | Description |
+|---|---|---|
+| `replicaCount` | `1` | Replicas (ignored when autoscaling is on). |
+| `resources.requests` | `500m` / `3Gi` | CPU / memory requests. |
+| `resources.limits` | `4` / `8Gi` | CPU / memory limits. |
+| `terminationGracePeriodSeconds` | `120` | Time to finish in-flight requests on shutdown. |
+| `progressDeadlineSeconds` | `900` | Rollout deadline (the image is slow to pull). |
+| `podSecurityContext` / `securityContext` | non-root uid/gid `1000`, drop `ALL` | Security contexts. |
+| `nodeSelector` / `tolerations` / `affinity` | `{}` | Scheduling. |
+| `podAntiAffinity` | `soft` | Spread replicas across nodes: `soft`, `hard`, `""`. |
+
+### Application (env vars)
+
+| Key | Default | Env var | Description |
+|---|---|---|---|
+| `config.port` | `8000` | `PORT` | Listen port. |
+| `config.host` | `0.0.0.0` | `HOST` | Bind interface. |
+| `config.workers` | `1` | `WORKERS` | Uvicorn workers per pod. |
+| `config.memoryFreeMinimumMb` | `2048` | `UNSTRUCTURED_MEMORY_FREE_MINIMUM_MB` | Return 503 below this free memory; `0` disables. |
+| `config.allowedOrigins` | `""` | `ALLOWED_ORIGINS` | Comma-separated CORS origins. |
+| `config.maxLifetimeSeconds` | `""` | `MAX_LIFETIME_SECONDS` | Graceful self-restart after N seconds. |
+| `config.env` | `prod` | `ENV` | Silences the noisy uvicorn error logger. |
+| `config.parallelMode.*` | off | `UNSTRUCTURED_PARALLEL_MODE_*` | Experimental parallel PDF mode. |
+| `extraEnv` / `extraEnvFrom` | `[]` | | Extra environment variables. |
+
+### Service, Ingress, autoscaling
+
+| Key | Default | Description |
+|---|---|---|
+| `service.enabled` | `true` | Create a Service (required by Ingress and the helm test). |
+| `service.type` / `service.port` | `ClusterIP` / `80` | Service type and port. |
+| `ingress.enabled` | `false` | Create an Ingress. |
+| `autoscaling.enabled` | `false` | Create a HorizontalPodAutoscaler. |
+| `autoscaling.minReplicas` / `maxReplicas` | `1` / `5` | HPA bounds. |
+| `autoscaling.targetCPUUtilizationPercentage` | `80` | CPU target (% of the CPU request). |
+| `podDisruptionBudget.enabled` | `false` | Create a PodDisruptionBudget. |
+
+## API-key auth
+
+Set `UNSTRUCTURED_API_KEY` so clients must send the `unstructured-api-key` header. The chart
+creates the Secret, or point it at an existing one:
+
+```yaml
+apiKey:
+  enabled: true
+  value: "super-secret-key"
+# or
+apiKey:
+  enabled: true
+  existingSecret: my-unstructured-secret
+  existingSecretKey: UNSTRUCTURED_API_KEY
+```
+
+## Probes
+
+All probes hit `GET /healthcheck`. This only confirms the HTTP server is up — it does not check
+that models are loaded (they load on the first request) or that memory is free (the 503 guard is
+in the partition endpoint). So readiness won't drain an overloaded pod; deeper checks would need
+an app-side endpoint. The `startupProbe` covers process start only, not model loading.
+
+## Scaling
+
+Each worker loads its own copy of the models, so scale out (`replicaCount` / `autoscaling`) rather
+than raising `config.workers`. HPA CPU utilisation is relative to the CPU request, so tune
+`targetCPUUtilizationPercentage` and `resources.requests.cpu` together.
+
+Scale-out isn't instant: the image is ~10GB, so a replica on a node without it cached can't serve
+until the pull finishes (minutes). Pre-pull or cache the image, or keep a warm node pool.
+`progressDeadlineSeconds: 900` keeps rollouts from failing mid-pull.
+
+`podAntiAffinity: hard` gives one pod per node, but needs at least `maxReplicas` schedulable nodes
+or the extras stay `Pending`.
+
+## Test
+
+```bash
+helm test my-release
+```
+
+Runs a Pod that curls `/healthcheck` through the Service.

charts/unstructured-api/templates/NOTES.txt

@@ -0,0 +1,62 @@
+✅ {{ include "unstructured-api.fullname" . }} has been deployed.
+
+The Unstructured API listens on container port {{ .Values.config.port }}.
+{{- if .Values.service.enabled }}
+It is exposed by a {{ .Values.service.type }} Service on port {{ .Values.service.port }}.
+
+In-cluster endpoint:
+
+  http://{{ include "unstructured-api.fullname" . }}.{{ .Release.Namespace }}.svc.cluster.local{{ if ne (.Values.service.port | int) 80 }}:{{ .Values.service.port }}{{ end }}
+
+Partition endpoint:
+
+  http://{{ include "unstructured-api.fullname" . }}.{{ .Release.Namespace }}.svc.cluster.local{{ if ne (.Values.service.port | int) 80 }}:{{ .Values.service.port }}{{ end }}/general/v0/general
+{{- else }}
+No Service was created (service.enabled=false). Expose the pods yourself to reach the API.
+{{- end }}
+
+{{- if .Values.ingress.enabled }}
+
+Reachable via Ingress at:
+{{- range .Values.ingress.hosts }}
+{{- $host := .host }}
+  {{- range .paths }}
+  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host }}{{ .path }}
+  {{- end }}
+{{- end }}
+{{- else if .Values.service.enabled }}
+{{- if contains "NodePort" .Values.service.type }}
+
+Get the application URL by running:
+  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "unstructured-api.fullname" . }})
+  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo "http://$NODE_IP:$NODE_PORT"
+{{- else if contains "LoadBalancer" .Values.service.type }}
+
+Get the application URL by running (the LoadBalancer may take a moment to provision):
+  kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "unstructured-api.fullname" . }}
+{{- else }}
+
+Port-forward to reach the API locally:
+  kubectl port-forward --namespace {{ .Release.Namespace }} svc/{{ include "unstructured-api.fullname" . }} 8000:{{ .Values.service.port }}
+
+Then verify it is ready:
+  curl --fail http://localhost:8000/healthcheck
+
+Partition a document:
+  curl --request POST \
+    --url http://localhost:8000/general/v0/general \
+{{- if .Values.apiKey.enabled }}
+    --header 'unstructured-api-key: <your-api-key>' \
+{{- end }}
+    --header 'accept: application/json' \
+    --form 'files=@sample-docs/family-day.eml'
+{{- end }}
+{{- end }}
+
+{{- if .Values.apiKey.enabled }}
+
+🔐 API-key authentication is enabled. Clients must send the key in the `unstructured-api-key` header.
+{{- end }}
+
+Interactive docs: <base-url>/general/docs

charts/unstructured-api/templates/_helpers.tpl

@@ -0,0 +1,124 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "unstructured-api.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+*/}}
+{{- define "unstructured-api.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "unstructured-api.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "unstructured-api.labels" -}}
+helm.sh/chart: {{ include "unstructured-api.chart" . }}
+{{ include "unstructured-api.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "unstructured-api.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "unstructured-api.name" . | quote }}
+app.kubernetes.io/instance: {{ .Release.Name | quote }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use.
+*/}}
+{{- define "unstructured-api.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "unstructured-api.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Name of the Secret holding the API key.
+*/}}
+{{- define "unstructured-api.apiKeySecretName" -}}
+{{- if .Values.apiKey.existingSecret }}
+{{- .Values.apiKey.existingSecret }}
+{{- else }}
+{{- printf "%s-api-key" (include "unstructured-api.fullname" .) }}
+{{- end }}
+{{- end }}
+
+{{/*
+Affinity: explicit .Values.affinity wins, otherwise render the podAntiAffinity preset.
+*/}}
+{{- define "unstructured-api.affinity" -}}
+{{- if .Values.affinity -}}
+{{- toYaml .Values.affinity -}}
+{{- else if eq .Values.podAntiAffinity "hard" -}}
+podAntiAffinity:
+  requiredDuringSchedulingIgnoredDuringExecution:
+    - labelSelector:
+        matchLabels:
+          {{- include "unstructured-api.selectorLabels" . | nindent 10 }}
+      topologyKey: kubernetes.io/hostname
+{{- else if eq .Values.podAntiAffinity "soft" -}}
+podAntiAffinity:
+  preferredDuringSchedulingIgnoredDuringExecution:
+    - weight: 100
+      podAffinityTerm:
+        labelSelector:
+          matchLabels:
+            {{- include "unstructured-api.selectorLabels" . | nindent 12 }}
+        topologyKey: kubernetes.io/hostname
+{{- end -}}
+{{- end -}}
+
+{{/*
+Validate configuration.
+*/}}
+{{- define "unstructured-api.validateValues" -}}
+{{- if and .Values.apiKey.enabled (not .Values.apiKey.existingSecret) (not .Values.apiKey.value) -}}
+{{- fail "apiKey.enabled is true but neither apiKey.value nor apiKey.existingSecret is set." -}}
+{{- end -}}
+{{- if and .Values.apiKey.enabled .Values.apiKey.existingSecret (not .Values.apiKey.existingSecretKey) -}}
+{{- fail "apiKey.existingSecret is set but apiKey.existingSecretKey is empty." -}}
+{{- end -}}
+{{- if and .Values.autoscaling.enabled (not .Values.autoscaling.targetCPUUtilizationPercentage) (not .Values.autoscaling.targetMemoryUtilizationPercentage) -}}
+{{- fail "autoscaling.enabled requires targetCPUUtilizationPercentage or targetMemoryUtilizationPercentage to be set." -}}
+{{- end -}}
+{{- if and .Values.podDisruptionBudget.enabled (eq (toString .Values.podDisruptionBudget.minAvailable) "") (eq (toString .Values.podDisruptionBudget.maxUnavailable) "") -}}
+{{- fail "podDisruptionBudget.enabled requires minAvailable or maxUnavailable to be set." -}}
+{{- end -}}
+{{- if and .Values.config.parallelMode.enabled (not .Values.config.parallelMode.url) -}}
+{{- fail "config.parallelMode.enabled is true but config.parallelMode.url is empty." -}}
+{{- end -}}
+{{- if and .Values.ingress.enabled (not .Values.service.enabled) -}}
+{{- fail "ingress.enabled requires service.enabled=true." -}}
+{{- end -}}
+{{- if not (has .Values.podAntiAffinity (list "" "soft" "hard")) -}}
+{{- fail "podAntiAffinity must be one of: \"\", soft, hard." -}}
+{{- end -}}
+{{- end -}}