Dev / Migration Container

This guide explains how to build and use the migration runtime image for in-cluster development. The runtime provides access to:

1. Specify 7 source code (with ORM support).
2. Internal cluster services (MariaDB, Redis).
3. External Oracle databases (subject to firewall and whitelist rules).

1. Build the Image (Podman)

Build for linux/amd64 to match cluster compatibility requirements.

Prerequisites:

• podman installed.
• Submodules initialized (git submodule update --init --recursive).

Build Command:

podman build --platform linux/amd64 -t ghcr.io/unimus-natur/migration:latest .

Note: If you are pushing to a registry (e.g., GHCR), tag accordingly:

podman tag ghcr.io/unimus-natur/migration:latest ghcr.io/unimus-natur/migration:latest
podman push ghcr.io/unimus-natur/migration:latest

2. Deploy to Cluster

The migration toolbox container is no longer deployed by the specify7 Helm chart by default. For a fast in-cluster loop, use the Prefect devWorker (process type), which runs from the migration image.

1. Load Image (Local Dev): If using kind or minikube and not pushing to a registry, load the image:

   # For kind
   kind load docker-image migration:latest
   # (Podman users might need to save/load archive if direct load isn't supported)
   podman save migration:latest -o migration.tar
   kind load image-archive migration.tar
   

2. Configure Prefect dev worker image: Ensure prefect.devWorker.image.repository and prefect.devWorker.image.tag point to your migration image.

3. Upgrade/Install:

   helm upgrade --install staging ./charts/specify7 --values ./charts/specify7/values.yaml
   

3. Accessing the Runtime

The old long-lived migration toolbox pod is no longer part of the default chart. Use the Prefect devWorker pod as the runtime:

export POD_NAME=$(kubectl get pods -l component=prefect-dev-worker -o jsonpath="{.items[0].metadata.name}")
kubectl exec -it "$POD_NAME" -- bash

4. Database Proxies (Port Forwarding)

From your laptop, Oracle is normally reachable only from the cluster network. Use scripts/port-forward.sh from a clone of this repo on your machine: it picks the prefect-dev-worker pod (migration image, includes socat), runs socat inside that pod toward the Oracle hosts, then kubectl port-forward exposes 1553 / 1554 on your localhost. MariaDB and other in-cluster services use regular service port-forwards in the same script.

# In your repo checkout (uses current kubectl context / namespace)
source scripts/port-forward.sh db
# or everything:  source scripts/port-forward.sh

Optional: export PF_ORACLE_PROXY_POD=<pod-name> if you are not using the default component=prefect-dev-worker selector.

Connect (local):

• Oracle PROD: localhost:1553
• Oracle TEST: localhost:1554
• MariaDB: localhost:3306 (when included in the same source invocation)

Tear down: pf_stop in that shell.

For SQL from the terminal after forwarding: oracle_sql "SELECT sysdate FROM dual" (see scripts/oracle_sql.py for thick-mode / Instant Client requirements on your laptop).

5. Running Migration Flows

When using Prefect with git_clone, flow runs execute from a temporary cloned directory, not /app. For ad-hoc shell work, the image still includes the required repository tooling and dependencies.

To run flows using the Specify ORM:

# Example
python flows/test_infrastructure.py

6. Remote Build (Kaniko on K8s)

You can trigger a remote build (Kaniko on K8s) directly from your terminal using the helper script.

1. Prerequisites (One-time Setup)

Create Secret: The cluster needs your GitHub Container Registry credentials.

# Replace YOUR_TOKEN with a GitHub Classic PAT (read:packages, write:packages)
kubectl create secret docker-registry ghcr-secret \
  --docker-server=ghcr.io \
  --docker-username=unimus-natur \
  --docker-password=YOUR_TOKEN

> **Note for Organizations**:
> GitHub Container Registry always requires authenticating as a **User**.
> If you are pushing to an Organization (`ghcr.io/unimus-natur/...`), you must use a Personal Access Token (PAT) from a user account that has write access to the organization's packages.
> For shared/automated setups, it is best practice to use a **Machine User** (a dedicated bot account) added to your organization.

2. Usage

Build Current Branch: Builds the current remote state of your branch and pushes to ghcr.io/unimus-natur/migration:latest.

./scripts/build-k8s.sh

Build Specific Branch:

./scripts/build-k8s.sh feature/new-setup

Build Custom Branch & Tag:

./scripts/build-k8s.sh feature/new-setup ghcr.io/unimus-natur/migration:test-1

Note on Resources: The build pod is configured with resource limits. The cluster enforces a policy where the Limit cannot exceed 2x the Request. If you adjust resources in scripts/build-k8s.sh, ensure you maintain this ratio (e.g., Request 2Gi -> Limit 4Gi).