---
name: deploy-to-kubernetes
description: |
  Deploy the realestate-crawler to the Kubernetes cluster. Use when: (1) user wants
  to deploy after building new images, (2) rollout restart to pick up new images,
  (3) check deployment status, pod health, or logs in production, (4) scale
  deployments up or down, (5) debug production issues.
author: Claude Code
version: 1.0.0
date: 2026-02-06
---

# Deploy to Kubernetes

All kubectl commands run locally against the K8s cluster at `10.0.20.100:6443`.
Namespace: `realestate-crawler`.

## Deployments

| Deployment               | Image                              | Component |
|--------------------------|------------------------------------|-----------|
| realestate-crawler-api   | viktorbarzin/realestatecrawler     | API       |
| realestate-crawler-ui    | viktorbarzin/immoweb               | Frontend  |

## Deploying New Images

### Rolling restart (picks up :latest after push)

```bash
# Restart API deployment
kubectl rollout restart deployment/realestate-crawler-api -n realestate-crawler

# Restart Frontend deployment
kubectl rollout restart deployment/realestate-crawler-ui -n realestate-crawler

# Restart both
kubectl rollout restart deployment/realestate-crawler-api deployment/realestate-crawler-ui -n realestate-crawler
```

### Full deploy workflow (build, push, restart)

```bash
GIT_SHA=$(git rev-parse --short HEAD)

# Build and push API
docker build -t viktorbarzin/realestatecrawler:${GIT_SHA} -t viktorbarzin/realestatecrawler:latest .
docker push viktorbarzin/realestatecrawler:${GIT_SHA}
docker push viktorbarzin/realestatecrawler:latest

# Build and push Frontend
docker build -t viktorbarzin/immoweb:${GIT_SHA} -t viktorbarzin/immoweb:latest frontend/
docker push viktorbarzin/immoweb:${GIT_SHA}
docker push viktorbarzin/immoweb:latest

# Restart deployments to pick up new images
kubectl rollout restart deployment/realestate-crawler-api -n realestate-crawler
kubectl rollout restart deployment/realestate-crawler-ui -n realestate-crawler
```

### Deploy a specific image tag

```bash
# Set API to a specific image version
kubectl set image deployment/realestate-crawler-api \
  realestate-crawler-api=viktorbarzin/realestatecrawler:abc1234 \
  -n realestate-crawler

# Set Frontend to a specific version
kubectl set image deployment/realestate-crawler-ui \
  realestate-crawler-ui=viktorbarzin/immoweb:abc1234 \
  -n realestate-crawler
```

## Checking Deployment Status

```bash
# List all resources in namespace
kubectl get all -n realestate-crawler

# Check deployment status
kubectl get deployments -n realestate-crawler

# Check rollout status (waits for completion)
kubectl rollout status deployment/realestate-crawler-api -n realestate-crawler
kubectl rollout status deployment/realestate-crawler-ui -n realestate-crawler

# Check pods
kubectl get pods -n realestate-crawler

# Describe a specific pod (events, conditions, image)
kubectl describe pod <pod-name> -n realestate-crawler

# Check which image a pod is running
kubectl get pods -n realestate-crawler -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
```

## Viewing Logs

```bash
# API logs
kubectl logs deployment/realestate-crawler-api -n realestate-crawler --tail=100 -f

# Frontend logs
kubectl logs deployment/realestate-crawler-ui -n realestate-crawler --tail=100 -f

# Logs from a specific pod
kubectl logs <pod-name> -n realestate-crawler --tail=100 -f

# Previous container logs (if pod crashed/restarted)
kubectl logs <pod-name> -n realestate-crawler --previous
```

## Scaling

```bash
# Scale API
kubectl scale deployment/realestate-crawler-api --replicas=2 -n realestate-crawler

# Scale down (e.g., for maintenance)
kubectl scale deployment/realestate-crawler-api --replicas=0 -n realestate-crawler
```

## Rollback

```bash
# View rollout history
kubectl rollout history deployment/realestate-crawler-api -n realestate-crawler

# Rollback to previous version
kubectl rollout undo deployment/realestate-crawler-api -n realestate-crawler

# Rollback to specific revision
kubectl rollout undo deployment/realestate-crawler-api --to-revision=3 -n realestate-crawler
```

## Debugging Production Issues

```bash
# Exec into a running API pod
kubectl exec -it deployment/realestate-crawler-api -n realestate-crawler -- bash

# Run a one-off command
kubectl exec deployment/realestate-crawler-api -n realestate-crawler -- python -c "print('hello')"

# Check pod events (useful for crash loops, image pull errors)
kubectl get events -n realestate-crawler --sort-by='.lastTimestamp' | tail -20

# Port-forward to a pod for local debugging
kubectl port-forward deployment/realestate-crawler-api 5001:5001 -n realestate-crawler
```

## Notes

- Woodpecker CI handles automated deployments on push to `master` (see `.woodpecker/`)
- Use manual deployment for hotfixes, testing, or deploying from non-master branches
- The K8s cluster is at `10.0.20.100:6443` (context: `kubernetes-admin@kubernetes`)
- If pods aren't picking up new `:latest` images, check the `kubernetes-latest-tag-image-pull` skill
- Always verify the rollout completed with `kubectl rollout status` after deploying