docs/migration.org

#+TITLE: Migrating to Nekomata from Kubernetes
#+AUTHOR: SnapKitty Systems
#+DATE: 2026
#+OPTIONS: toc:2 num:t

* Overview

This document describes the migration path from a Kubernetes-based
deployment to Nekomata. The migration is incremental: you can run
Nekomata alongside an existing Kubernetes cluster, migrating workloads
one at a time.

* Concept Mapping

| Kubernetes | Nekomata | Notes |
|------------|----------|-------|
| Pod | =container-spec= | Nekomata does not have the Pod/Container distinction. One spec = one container. |
| Deployment | =(define-container ...)= + evolutionary population | The Deployment's replica count becomes a =(replica-constraint lo hi)= |
| Service | Network policy + port mapping | Nekomata routes traffic via the regex-math policy layer |
| Namespace | Container name prefix convention | =api-*= and =db-*= are namespaces encoded in names |
| ConfigMap | Lisp =defvar= or env alist in spec | Config is code. It lives in the image. |
| Secret | Lisp =defvar= in sealed image section | Sealed via image encryption, not Kubernetes RBAC |
| NetworkPolicy | Kleene algebra policy expression | More expressive than K8s NetworkPolicy |
| HorizontalPodAutoscaler | =replica-constraint= + evolutionary loop | Autoscaling is a fitness function, not a YAML object |
| CronJob | Lisp timer in the eval loop | =sb-ext:schedule-timer= or similar |
| PersistentVolume | Volume spec in =container-spec= | Maps directly to Docker bind mount |
| Ingress | Routing expert + port forwarding | Nekomata does not have an Ingress object |
| RBAC | Security expert + Kleene policy | Roles are regex patterns over container identities |

* Step 1: Inventory Your Workloads

Before migrating, generate a complete inventory of your Kubernetes
workloads:

#+BEGIN_SRC shell
# Export all Deployments as YAML
kubectl get deployments --all-namespaces -o yaml > k8s-deployments.yaml

# Export all Services
kubectl get services --all-namespaces -o yaml > k8s-services.yaml

# Export all NetworkPolicies
kubectl get networkpolicies --all-namespaces -o yaml > k8s-netpolicies.yaml
#+END_SRC

* Step 2: Translate Deployments to Container Specs

For each Kubernetes Deployment, create a Nekomata =define-container=:

** Kubernetes Deployment (YAML):
#+BEGIN_SRC yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
      - name: api-server
        image: mycompany/api:v2.1.0
        ports:
        - containerPort: 8080
        env:
        - name: DB_HOST
          value: "postgres:5432"
        - name: LOG_LEVEL
          value: "info"
#+END_SRC

** Nekomata Container Spec (Lisp):
#+BEGIN_SRC lisp
(define-container api-server
  :image "mycompany/api:v2.1.0"
  :ports '((8080 . 8080))
  :env '((:DB_HOST . "postgres:5432")
         (:LOG_LEVEL . "info"))
  :restart-policy :always)

;; Replica count as an evolutionary constraint
(push (replica-constraint 2 5) *active-constraints*)
#+END_SRC

The replica count becomes a constraint that the evolutionary optimizer
satisfies. Instead of specifying =replicas: 3= as a static value, you
specify a range (2 to 5) and let the optimizer find the right count
based on observed CPU and memory utilization.

* Step 3: Translate NetworkPolicies

** Kubernetes NetworkPolicy:
#+BEGIN_SRC yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-to-db
spec:
  podSelector:
    matchLabels:
      app: postgres
  ingress:
  - from:
    - podSelector:
        matchLabels:
          app: api-server
    ports:
    - protocol: TCP
      port: 5432
#+END_SRC

** Nekomata Policy:
#+BEGIN_SRC lisp
(define-policy api-to-db
  :from (re-concat (re-literal "api-") (re-star re-any))
  :to   (re-literal "postgres")
  :port (re-literal "5432")
  :op   :allow)
#+END_SRC

Note that the Nekomata policy is more expressive: it matches any
container whose name starts with "api-", not just ones with the
label =app: api-server=. You can add the label restriction by using
a more precise pattern.

* Step 4: Translate RBAC

Kubernetes RBAC is a role/binding system. Nekomata does not have
RBAC objects -- access control is encoded directly in Kleene algebra
policies over container identities.

The general mapping: a Kubernetes Role with rules for resource
=pods= and verb =list= maps to a Nekomata monitoring policy that allows
the monitoring container to inspect all containers.

* Step 5: Run Nekomata Alongside Kubernetes

During migration, run Nekomata as an additional Docker-based system
alongside your Kubernetes cluster:

1. Start the Nekomata daemon on a dedicated node outside the k8s cluster
2. Migrate non-critical services first (monitoring, batch jobs, dev environments)
3. Use Nekomata as the primary scheduler for new services
4. Gradually migrate production services as confidence increases

Nekomata and Kubernetes share the same container runtime (containerd/Docker).
Migrated containers run the same images. Only the orchestration layer changes.

* Step 6: Sunset the Kubernetes Control Plane

Once all workloads are migrated:

#+BEGIN_SRC shell
# Drain all nodes (stop scheduling new pods)
kubectl drain --all --ignore-daemonsets

# Delete the cluster (if using a managed service)
# ... provider-specific command

# Stop local etcd and control plane components
systemctl stop kube-apiserver kube-controller-manager kube-scheduler
#+END_SRC

You have recovered: ~200ms control plane latency, ~500MB memory for
etcd, ~1GB for the control plane components, and the full-time salary
of whoever was maintaining the Kubernetes cluster.

* Migration Checklist

- [ ] Inventory all Deployments, StatefulSets, DaemonSets
- [ ] Translate each workload to a =define-container= form
- [ ] Translate NetworkPolicies to Kleene algebra policies
- [ ] Translate RBAC to Nekomata security expert policies
- [ ] Set up Nekomata evolutionary constraints (replica ranges, CPU budgets)
- [ ] Run both systems in parallel for at least one week
- [ ] Verify telemetry and health checks match between systems
- [ ] Migrate production traffic to Nekomata
- [ ] Decommission Kubernetes control plane
- [ ] Save first WORM-sealed Nekomata image checkpoint

* What You Lose

Be honest about the tradeoffs:

- *Kubernetes ecosystem*: Helm charts, Operators, the CNCF tool zoo do not exist for Nekomata.
- *Multi-cluster federation*: Nekomata is single-node or manually federated.
- *Managed service*: No EKS/GKE/AKS equivalent. You operate the Nekomata daemon.
- *kubectl*: The neko CLI is simpler but not as feature-rich yet.

* What You Gain

- *Zero YAML*: All infrastructure is Lisp code. It evaluates. It composes.
- *Hot-swap*: Update any function without restarting the daemon.
- *Evolutionary optimization*: Container specs improve automatically.
- *LLM intent compilation*: Natural language to machine code.
- *Formal policy verification*: Prove your network policies are correct before applying them.
- *Image persistence*: The entire state is a single file. Restart is instant.
- *10x simpler control plane*: One Lisp image vs. etcd + apiserver + controller-manager + scheduler.