docs(exapp-operations): registry mappings on Kubernetes daemons

skills/exapp-maintenance/references/exapp-ai-maintenance.md

@@ -15,7 +15,8 @@ that loop. It is written for an AI agent executing it on a user's behalf; the us
 
 Works against any docker-install HaRP daemon you control, including the development environment from
 [dev-environment.md](../../nextcloud-dev-setup/references/dev-environment.md). Not covered: Kubernetes daemons
-(their images come from an in-cluster registry; the local-image switch below is Docker-only) and manual-install
+(the build-and-tag steps below need the Docker daemon host; a Kubernetes daemon takes a rebuilt image through a
+registry mapping instead, see [kubernetes.md](../../exapp-operations/references/kubernetes.md)) and manual-install
 apps (just edit and restart the process; see
 [exapp-development.md](../../exapp-development/references/exapp-development.md)).
 
@@ -168,7 +169,7 @@ instance through exactly steps 4 to 7.
 | Update succeeded but behavior unchanged | Rebuilt image under a different name/tag than info.xml declares, or the mapping was absent so the registry copy was pulled; check `docker inspect nc_app_<id> --format '{{.Config.Image}}'` and `docker images`. |
 | App store update button "reinstalled" the stock app | Expected: the UI updates from the store. Local builds are occ-driven (`--info-xml`). |
 | App `[enabled]` and heartbeating, but AI tasks are never picked up | The fault can be inside or outside the container. Inside: a silently crashed task loop still registers providers but never claims tasks; look for a startup traceback in `docker logs nc_app_<appid>` (real case: nextcloud/llm2#284). Outside: `occ taskprocessing:task:list` and `taskprocessing:task:get <id>` show tasks stuck scheduled, `occ background-job:list` and cron health show whether the server side runs at all, and the admin AI settings select which provider handles each task type. |
-| App on a Kubernetes daemon | This runbook does not apply; build and push to a registry the cluster can pull, or move the app to a docker daemon for the debugging session. |
+| App on a Kubernetes daemon | This runbook does not apply as written. Push the rebuilt image to a registry the nodes can pull and map the upstream registry to it (`app_api:daemon:registry:add <daemon> --registry-from ghcr.io --registry-to <mirror>`, AppAPI with nextcloud/app_api#1046), or pre-load it on every node and map to `local` (HaRP newer than 0.4.5 then sets `imagePullPolicy: Never`), then `app:update`. Or move the app to a docker daemon for the debugging session. |
 
 ## Related
 

skills/exapp-operations/references/kubernetes.md

@@ -222,7 +222,17 @@ common cases map directly to HaRP env:
   switch to `nodeport`/`loadbalancer`, use `manual` with `--k8s_upstream_host`, or run HaRP on a node.
 - **ExApp pod cannot resolve your Nextcloud host**: add it via `HP_K8S_HOST_ALIASES`, or ensure
   `<nextcloud-url-reachable-from-exapps>` uses a name cluster DNS can resolve.
-- **Image pull fails in the cluster**: private registry or missing pull secret; configure registry access in
-  the namespace.
+- **Image pull fails in the cluster**: private registry or missing pull secret. HaRP sets no `imagePullSecrets`
+  on ExApp pods, so an authenticated registry needs them on the namespace's `default` ServiceAccount
+  (`kubectl -n <ns> create secret docker-registry <name> ...`, then
+  `kubectl -n <ns> patch serviceaccount default -p '{"imagePullSecrets":[{"name":"<name>"}]}'`).
+- **Mirrored or air-gapped registry**: `app_api:daemon:registry:add <daemon> --registry-from ghcr.io
+  --registry-to <mirror>` applies to Kubernetes daemons since AppAPI nextcloud/app_api#1046; earlier versions
+  stored the mapping but kept pulling from the upstream registry (nextcloud/app_api#1039). Mappings that were
+  already stored take effect on the next ExApp install or update, and the mirror must be reachable from the
+  nodes. A mapping to `local` keeps the image name: with HaRP newer than 0.4.5 (nextcloud/HaRP#122) the pod gets
+  `imagePullPolicy: Never`, so the image has to be present on every node that can schedule it and a missing
+  image fails within seconds; older HaRP keeps `IfNotPresent` and pulls when the node lacks the image. The
+  `-cuda`/`-rocm` image variants are not used on Kubernetes.
 
 For the daemon-register flag reference and general ExApp lifecycle, see [operations.md](operations.md).

skills/exapp-operations/references/operations.md

@@ -343,7 +343,10 @@ Notes:
   key/value configuration.
 - **Private/mirror Docker registries**: `app_api:daemon:registry:add|remove|list` map registries for a
   daemon so ExApp images can be pulled from somewhere other than the default
-  (`registry:add <daemon> --registry-from <url> --registry-to <url>`).
+  (`registry:add <daemon> --registry-from <url> --registry-to <url>`). Applies to Docker and, since AppAPI
+  nextcloud/app_api#1046, Kubernetes daemons. The target `local` keeps the image name: Docker skips the pull,
+  Kubernetes sets `imagePullPolicy: Never` with HaRP newer than 0.4.5. Values are trimmed and trailing
+  slashes dropped when stored.
 - **Daemons**: `app_api:daemon:list` / `app_api:daemon:unregister` manage daemon configs; re-run
   `app_api:daemon:register ... --set-default` to change the default. Note that `daemon:register` is a no-op if
   a daemon with that `name` already exists (see [Troubleshooting](#10-troubleshooting-symptom-first)).