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.
Prerequisites
- Immich reachable from the cluster, with a scoped 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
nvidiaRuntimeClass 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. - 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 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.
This page runs entirely in your browser. What you type here is never sent anywhere: no requests, no analytics, no tracking. The files are built on this page and stay on it until you copy or download them.
Setup files for docs build v1.0.0. The app image and release assets use this same version.
The builder does not ask for your Immich API key. The files hold the placeholder replace-with-your-immich-api-key: create a key with the ten required read permissions and paste it over the placeholder in your own editor. Add the five upload permissions only to send films back; asset.delete is optional. Avoid the All preset.
Platform coverage and tested installations
See the deployment matrix for exact release and platform coverage.
Tested as a generated installation on Kubernetes (RKE2): the GPU tier and Basic, each with the CronJobs, were installed from builder output and made a film. The files are also checked with Kustomize and the form is checked in a browser. Other clusters, storage classes and tiers are not covered: see the matrix. Tried it? Report your platform, release and preflight result.
Nothing here contacts an Immich or model server.
Generate a private settings key before exporting Kubernetes setup files.
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. Make your first film
and download it from its run page.
Operate this installation
Kustomize and Terraform are the supplied deployment paths. There is no project Helm chart. Tested deployments 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 |
| Ingress, probes, logs and outages | Networking and monitoring |
| GPU rendering, PostgreSQL, workers or batch jobs | Topology and add-ons |
| Storage sizing, requests and scratch | Resource budgets |
| Repeatable release inputs | GitOps |
| Upgrade, backup or removal | Maintenance, backups, uninstall |