# Kubernetes

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/run/kubernetes/>.

Install into an existing cluster with Kustomize and persistent storage. Choose Basic, GPU or Full;
the setup builder generates that tier's configuration and commands.
For Terraform-managed resources, use the [Terraform module](https://sam-dumont.github.io/immich-memories/docs/run/terraform.md).

## Prerequisites

- Immich reachable from the cluster, with a [scoped API key](https://sam-dumont.github.io/immich-memories/docs/run/docker.md#the-api-key).
- A default storage class for three ReadWriteOnce volumes: 60 GiB data/cache, 50 GiB output and
  5 GiB models. Use local/block storage for the SQLite data volume, not NFS/SMB. Check the
  storage class's reclaim policy before installation.
- Capacity for the app: it requests 1 CPU / 2 GiB and has a limit of 4 CPUs / 8 GiB.
- **GPU and Full:** NVIDIA GPU Operator, the `nvidia` RuntimeClass and labelled GPU nodes.
  The shipped inference and caption services share a GPU through time-slicing; configure that
  sharing first. They add two volumes (2 GiB captions and 10 GiB inference cache) and their own
  compute requirements. [GPU allocation details](https://sam-dumont.github.io/immich-memories/docs/run/local-models.md#kubernetes-services).
- **Full:** an existing reader endpoint with a served model, 32k context and any required API key.

Keep one UI replica. Sign-in is on by default; the first start generates a password and prints it once
in the pod log (`kubectl logs -n immich-memories deploy/immich-memories`). The initial route uses a private
port-forward; set your own credentials with
[authentication](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md) before adding an Ingress.

## 1. Choose the tier

| Tier | Generated setup |
| - | - |
| **Basic** | CPU app, persistent store and local models |
| **GPU** | Basic plus CUDA inference and captions; video rendering stays on the app CPU |
| **Full** | GPU plus your explicitly enabled reader connection |

Enter the namespace and addresses reachable from the cluster. For Full, fill in the reader URL
and the exact model name it serves. Leave scheduled films off until you have made your first film.

The setup builder on [the HTML page](https://sam-dumont.github.io/immich-memories/docs/run/kubernetes/) generates the setup files for your choices in the browser. Pick a platform, a tier and the options there; nothing is sent anywhere.

## 2. Save the files

Follow the generated commands to download and extract the matching release bundle. Save each
file at its labelled path. In the Secret, replace `replace-with-your-immich-api-key` with your
own key. For a reader, replace its key placeholder too, or empty it when the reader needs no key.
Keep the Secret private and retain its Settings encryption key with your backups.

## 3. Apply and check

Continue the generated commands: inspect the rendered Kustomize output, apply it, then wait for
the app and the model services your tier uses. First starts download images and model files.
Run `models fetch` and `preflight` after those rollouts finish.

Continue when the Immich connection, output and required model/service checks pass.
`capabilities` should report the tier you selected.

## 4. Open the app

Keep the generated `kubectl port-forward` command running and open
[http://localhost:8080](http://localhost:8080). Make [your first film](https://sam-dumont.github.io/immich-memories/docs/get-started/first-film.md)
and download it from its run page.

## Operate this installation

Kustomize and [Terraform](https://sam-dumont.github.io/immich-memories/docs/run/terraform.md) are the supplied deployment paths. There is no project
Helm chart. [Tested deployments](https://sam-dumont.github.io/immich-memories/docs/run/tested-deployments.md) records the exact platform and release
coverage; the generated files do not imply every cluster or tier has been exercised.

| Task | Guide |
| - | - |
| Manual manifests, namespaces, Secret rotation | [Kubernetes operations](https://sam-dumont.github.io/immich-memories/docs/run/reference/kubernetes-operations.md) |
| Ingress, probes, logs and outages | [Networking and monitoring](https://sam-dumont.github.io/immich-memories/docs/run/reference/kubernetes-operations.md#authentication-and-ingress) |
| GPU rendering, PostgreSQL, workers or batch jobs | [Topology and add-ons](https://sam-dumont.github.io/immich-memories/docs/run/reference/kubernetes.md) |
| Storage sizing, requests and scratch | [Resource budgets](https://sam-dumont.github.io/immich-memories/docs/run/reference/kubernetes-operations.md#resource-requests-qos-and-scratch) |
| Repeatable release inputs | [GitOps](https://sam-dumont.github.io/immich-memories/docs/run/gitops.md) |
| Upgrade, backup or removal | [Maintenance](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/upgrading.md#kubernetes-and-terraform), [backups](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/storage-backups.md), [uninstall](https://sam-dumont.github.io/immich-memories/docs/run/lifecycle.md) |
