flickr-immich-k8s-sync-operator

Kubernetes operator that watches per-user Flickr download Jobs in a namespace, restarts failed Jobs after a configurable delay, and retrieves pod logs and exit codes for failed Jobs before restarting them. Designed to run alongside Immich (self-hosted photo management).

Screenshots

Status

Beta (v0.0.4) — the core job-restart loop is stable and actively deployed. OOMKilled-aware restart logic, structured startup/configuration logging, and full CI (black + mypy + pytest) are in place.

Architecture

• Runs as a single-replica Deployment in a dedicated namespace (default: flickr-downloader)
• Uses the Kubernetes Python client with in-cluster config
• Periodically checks configured Job names for failure conditions
• On failure (after a configurable delay), deletes the Job with Foreground propagation policy and recreates it from a cached manifest
• Logs pod exit codes and tail logs before every restart

How it works

1. An Ansible playbook (kubectlstuff_flickr_downloader.yml) creates per-user Flickr download Jobs in the flickr-downloader namespace
2. Each Job runs flickr_download with BACKOFF_EXIT_ON_429=true, so it exits immediately on HTTP 429 rate-limit errors instead of sleeping
3. Jobs mount host directories for config, backup, and cache per user
4. This operator watches all configured Jobs for failure conditions
5. When a Job fails, the operator logs pod exit codes and tail logs, waits RESTART_DELAY seconds (default 1 hour), then deletes and recreates the Job from a cached manifest
6. The operator uses namespace-scoped RBAC with minimal permissions (Jobs, Pods, Pod logs)

Prerequisites

• A running Kubernetes cluster
• Per-user Flickr download Jobs already deployed (e.g. via the Ansible playbook above) — the operator manages their lifecycle (restart on failure), not initial creation
• An Immich instance (for planned sync functionality)

Configuration

Kubernetes Deployment

RBAC

The operator requires a ServiceAccount with a Role scoped to the target namespace:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: flickr-operator
  namespace: flickr-downloader
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: flickr-operator
  namespace: flickr-downloader
rules:
  - apiGroups: ["batch"]
    resources: ["jobs"]
    verbs: ["get", "list", "create", "delete"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "delete"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: flickr-operator
  namespace: flickr-downloader
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: flickr-operator
subjects:
  - kind: ServiceAccount
    name: flickr-operator
    namespace: flickr-downloader

Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flickr-operator
  namespace: flickr-downloader
spec:
  replicas: 1
  selector:
    matchLabels:
      app: flickr-operator
  template:
    metadata:
      labels:
        app: flickr-operator
    spec:
      serviceAccountName: flickr-operator
      containers:
        - name: operator
          image: xomoxcc/flickr-immich-k8s-sync-operator:latest
          env:
            - name: JOB_NAMES
              value: "flickr-downloader-alice,flickr-downloader-bob"
            - name: LOGURU_LEVEL
              value: "DEBUG"
            # - name: NAMESPACE
            #   value: "flickr-downloader"      # default
            # - name: CHECK_INTERVAL
            #   value: "60"                      # default
            # - name: RESTART_DELAY
            #   value: "3600"                    # default
            # - name: SKIP_DELAY_ON_OOM
            #   value: "false"                   # default
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 1500m
              memory: 128Mi

Installation

From PyPI

pip install flickr-immich-k8s-sync-operator

From source

git clone https://github.com/vroomfondel/flickr-immich-k8s-sync-operator.git
cd flickr-immich-k8s-sync-operator
make venv
source .venv/bin/activate
pip install .

Docker

docker build -t flickr-immich-k8s-sync-operator .
docker run --rm flickr-immich-k8s-sync-operator

Or via Makefile:

make docker

Usage

# Run directly
flickr-immich-k8s-sync-operator

# Or via Python module
python -m flickr_immich_k8s_sync_operator

Development

Makefile targets

License

GNU Lesser General Public License v3