From a4ecca0e3c2511866a18b155045484d7c39387d4 Mon Sep 17 00:00:00 2001 From: Oleksandr Piskun Date: Fri, 25 Sep 2026 08:11:18 +0000 Subject: [PATCH] docs(exapp-operations): registry mappings on Kubernetes daemons Signed-off-by: Oleksandr Piskun --- .../references/exapp-ai-maintenance.md | 5 +++-- skills/exapp-operations/references/kubernetes.md | 14 ++++++++++++-- skills/exapp-operations/references/operations.md | 5 ++++- 3 files changed, 19 insertions(+), 5 deletions(-) diff --git a/skills/exapp-maintenance/references/exapp-ai-maintenance.md b/skills/exapp-maintenance/references/exapp-ai-maintenance.md index 4fb5f37..e7aa692 100644 --- a/skills/exapp-maintenance/references/exapp-ai-maintenance.md +++ b/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_ --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_` (real case: nextcloud/llm2#284). Outside: `occ taskprocessing:task:list` and `taskprocessing:task:get ` 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 --registry-from ghcr.io --registry-to `, 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 diff --git a/skills/exapp-operations/references/kubernetes.md b/skills/exapp-operations/references/kubernetes.md index 419c5be..e820231 100644 --- a/skills/exapp-operations/references/kubernetes.md +++ b/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 `` 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 create secret docker-registry ...`, then + `kubectl -n patch serviceaccount default -p '{"imagePullSecrets":[{"name":""}]}'`). +- **Mirrored or air-gapped registry**: `app_api:daemon:registry:add --registry-from ghcr.io + --registry-to ` 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). diff --git a/skills/exapp-operations/references/operations.md b/skills/exapp-operations/references/operations.md index 007c7aa..efdef53 100644 --- a/skills/exapp-operations/references/operations.md +++ b/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 --registry-from --registry-to `). + (`registry:add --registry-from --registry-to `). 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)).