Skip to main content

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 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.
  • 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​

TierGenerated setup
BasicCPU app, persistent store and local models
GPUBasic plus CUDA inference and captions; video rendering stays on the app CPU
FullGPU 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.

Choose a tier

Start with Basic if you are unsure. Every tier makes a complete film.

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.

TaskGuide
Manual manifests, namespaces, Secret rotationKubernetes operations
Ingress, probes, logs and outagesNetworking and monitoring
GPU rendering, PostgreSQL, workers or batch jobsTopology and add-ons
Storage sizing, requests and scratchResource budgets
Repeatable release inputsGitOps
Upgrade, backup or removalMaintenance, backups, uninstall