Terraform
The module in deploy/terraform/ runs the app in an existing Kubernetes cluster. Use this
route when you already manage that cluster with Terraform. For a setup that also generates
the GPU model-service deployments, use Kustomize.
Prerequisites
Terraform 1.9+, Kubernetes provider 2.20+, a working kubeconfig and storage class.
Immich must be reachable from the pod. For NVIDIA scheduling, add GPU Operator and the nvidia RuntimeClass.
Quick start
Download and extract the matching release bundle into vendor/immich-memories,
then choose the private CPU example:
cd vendor/immich-memories/deploy/terraform/examples/basic
cp terraform.tfvars.example terraform.tfvars
Edit the Immich URL, scoped API key and pinned image_tag.
Choose the tier through the example's env map:
| Tier | Configuration |
|---|---|
| Basic | IMMICH_MEMORIES_DEPLOYMENT_TIER = "basic"; no model services |
| GPU | IMMICH_MEMORIES_DEPLOYMENT_TIER = "gpu"; set the inference and caption endpoints |
| Full | GPU configuration with IMMICH_MEMORIES_DEPLOYMENT_TIER = "full", IMMICH_MEMORIES_LLM__ENABLED = "true", plus llm_base_url, llm_model and any llm_api_key |
GPU/Full require working CUDA inference, captions and Laya; Full also needs a reader with 32k
context. The module does not deploy an inference or reader server. See the
service inputs for the optional captioner.
gpu_enabled controls app GPU scheduling for rendering; it does not start those services.
Keep replicas = 1. Terraform state and plan artifacts can contain keys, so protect them.
Then:
terraform init
terraform plan
terraform apply
terraform output -raw port_forward_command
terraform apply waits for the deployment rollout and a Ready pod. The /health/ready probe stays unready until configuration is present and Immich answers; inspect the pod events and logs if apply waits or times out. Run the printed port-forward command and open http://localhost:8080.
The production example adds ingress/TLS and sets its own sign-in credentials. Without them the
first start generates a password and prints it once in the pod log. Keep one UI replica (replicas = 1).
What it creates
Namespace (optional), Secret, three PVCs, Deployment and Service, plus optional ingress.
config_yaml creates a ConfigMap and init container to install the file. Otherwise configuration
comes from env/secret_env and saved Settings. The module does not create the Kustomize base's
NetworkPolicy; define one separately if you need an egress boundary.
Terraform state can contain API keys and Secret values even when inputs are marked sensitive. Protect the state backend and plan artifacts as credentials.
After the apply
Manage values in Terraform: a later apply overwrites kubectl set env changes.
With the default namespace and deployment names, check preparation and readiness, then open the UI:
kubectl exec -n immich-memories deploy/immich-memories -- immich-memories models fetch
kubectl exec -n immich-memories deploy/immich-memories -- immich-memories preflight
kubectl port-forward -n immich-memories svc/immich-memories 8080:80
Use your chosen names if you changed them. Your first film starts from the connected UI.
For home coordinates, timezone and uploads, use the env map.
Input examples and the variable reference.
Model preparation and tiers
The init container fetches pinned files. Without an explicit tier in env, the app uses automatic tier selection.
After adding GPU/Full services, run models fetch and preflight in the app container.
Model preparation caveats.
Daily automation
The module has no CronJob. Enable the in-process timer in env, or use
an authenticated external trigger.
Upgrading
Back up the store, change image_tag, plan/apply, fetch current pins and run preflight.
Upgrade and rollback.
Module usage
Variables
Supported inputs, including config, captioner and sidecar inputs.
Troubleshooting
Configuration ownership and monitoring covers deployment-controlled settings, probes and Immich outages. Deployment evidence records tested versions and routes.
Stop or remove this installation
Stop, reset and uninstall separates retaining data for reinstall from deleting app state.