Forem: Otobong Edoho

Kubernetes Networking Deep Dive — Part 2: MetalLB, Nginx Ingress, and NetworkPolicy

Otobong Edoho — Wed, 13 May 2026 10:50:46 +0000

Part 2 of 2 — Replacing NodePort with real LoadBalancer IPs, routing traffic through an Ingress controller with clean hostnames, and locking down pod-to-pod communication with NetworkPolicy. All on bare metal. All verified with real tests.

Series navigation:

Part 1: Cluster setup with kubeadm, foundational workloads, deploying a full-stack app with ConfigMaps, Secrets, StatefulSets, and CI pipelines → Read Part 1

Part 2 (you are here): MetalLB, Nginx Ingress Controller, clean hostnames, and NetworkPolicy enforcement with real tests

Full source code: All Kubernetes manifests referenced in this article are available at
github.com/otie16/k8s-homelab-vm-project

If you followed Part 1, you have a working two-node Kubernetes cluster running a full-stack application — Next.js frontend, Django REST API, and PostgreSQL. You can reach it at 192.168.1.100:30001 and 192.168.1.100:30000.

That works. But it's not how production Kubernetes is meant to work.

In production, you don't tell people "hit port 30247 on any node IP." You give them https://app.yourcompany.com. Traffic enters through a single controlled gateway, gets routed to the right service, and never exposes internal cluster topology.

This is what Part 2 builds. By the end you'll have:

MetalLB giving your bare metal cluster real LoadBalancer IPs
Nginx Ingress Controller as the single entry point for all HTTP traffic
Clean hostnames — app.oty-k8s.local and api.oty-k8s.local on port 80
NetworkPolicy enforcing that only the right pods can talk to each other — verified with real tests

Why NodePort Is Not Enough

NodePort binds a random high port (30000-32767) on every node in the cluster and forwards traffic to your service. It works, but:

Random high ports are ugly and hard to remember
You're exposing every node's IP — if a node changes, external config breaks
There's no hostname-based routing — you can't serve two services on port 80
No TLS termination
No single entry point to apply rate limiting, auth, or observability

The production pattern is:

Internet / Local Network
        ↓
   LoadBalancer IP (single IP, port 80/443)
        ↓
   Ingress Controller (Nginx)
        ↓ routes by hostname
   ┌──────────────────────────────────┐
   │ app.oty-k8s.local → frontend   │
   │ api.oty-k8s.local → backend    │
   └──────────────────────────────────┘

One IP. One entry point. Clean hostnames. That's what we're building.

The Problem with LoadBalancer on Bare Metal

On cloud Kubernetes (EKS, GKE, AKS), when you create a Service with type: LoadBalancer, the cloud provider automatically provisions a real load balancer and assigns it an external IP.

On bare metal with kubeadm, there's no cloud provider. Create a LoadBalancer service and you'll see this forever:

NAME                      TYPE           EXTERNAL-IP
ingress-nginx-controller  LoadBalancer   <pending>

<pending> means Kubernetes is waiting for an external controller to assign the IP. On bare metal, nothing does that by default.

MetalLB solves this. It's a load balancer implementation designed specifically for bare metal clusters. It watches for LoadBalancer services and assigns real IPs from a pool you define. Your network learns about these IPs via ARP (Layer 2 mode) and routes traffic to the right node automatically.

Step 1 — Install MetalLB

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.5/config/manifests/metallb-native.yaml

Wait for MetalLB pods to be ready:

kubectl wait --for=condition=ready pod \
  -l app=metallb \
  -n metallb-system \
  --timeout=90s

kubectl get pods -n metallb-system

Expected:

NAME                          READY   STATUS
controller-xxx                1/1     Running
speaker-xxx (on master)       1/1     Running
speaker-yyy (on worker)       1/1     Running

The controller manages IP address assignments. The speaker pods run on each node and announce IP ownership via ARP — when your laptop asks "who has 192.168.1.200?", the MetalLB speaker on the node holding that service responds.

Configure the IP Address Pool

Pick a range on your local network that's outside your DHCP range so your router doesn't assign those IPs to other devices. Most home routers use .100-.199 for DHCP so .200-.220 is typically safe:

cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: local-pool
  namespace: metallb-system
spec:
  addresses:
  - 192.168.1.200-192.168.1.220
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: local-advert
  namespace: metallb-system
spec:
  ipAddressPools:
  - local-pool
EOF

The L2Advertisement tells MetalLB to use Layer 2 mode — simple ARP-based announcement that works on any network without router configuration. No BGP setup needed.

Verify:

kubectl get ipaddresspool -n metallb-system
kubectl get l2advertisement -n metallb-system

Step 2 — Install Nginx Ingress Controller

The Ingress Controller is what actually reads your Ingress resources and configures itself to route traffic. We're using the community Nginx Ingress Controller.

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.5/deploy/static/provider/cloud/deploy.yaml

Wait for it:

kubectl wait --for=condition=ready pod \
  -l app.kubernetes.io/component=controller \
  -n ingress-nginx \
  --timeout=90s

Check if MetalLB assigned a real IP:

kubectl get svc -n ingress-nginx

Expected:

NAME                      TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)
ingress-nginx-controller  LoadBalancer   10.96.x.x      192.168.1.200   80:3xxxx/TCP,443:3xxxx/TCP

That 192.168.1.200 in EXTERNAL-IP is MetalLB working. That single IP is now your cluster's front door for all HTTP/HTTPS traffic.

Step 3 — Update Services to ClusterIP

Your Django and Next.js services are currently NodePort. With Ingress in place, external traffic flows: client → MetalLB IP → Ingress Controller → ClusterIP Service → Pod. NodePort is no longer needed.

Update both services to type: ClusterIP:

kubectl apply -f /home/oty-k8s/k8s/backend-service.yaml
kubectl apply -f /home/oty-k8s/k8s/frontend-service.yaml

See → k8s/backend-service.yaml | k8s/frontend-service.yaml

Step 4 — Create the Ingress Resource

An Ingress resource is a routing table — it tells the Ingress controller which hostnames map to which services.

kubectl apply -f /home/oty-k8s/k8s/ingress.yaml

See the full manifest → k8s/ingress.yaml

The manifest routes:

app.oty-k8s.local → nextjs-frontend service on port 3000
api.oty-k8s.local → django-backend service on port 8000

Common mistake worth knowing about: The apiVersion must be networking.k8s.io/v1 — note the s in k8s. networking.k8.io/v1 (missing the s) causes no matches for kind "Ingress" in version "networking.k8.io/v1". Kubernetes error messages don't highlight the typo so this one wastes time.

Verify the Ingress has the MetalLB IP assigned:

kubectl get ingress -n k8s-vm-app

Expected:

NAME                 CLASS   HOSTS                                    ADDRESS         PORT(S)
k8s-vm-app-ingress   nginx   app.oty-k8s.local,api.oty-k8s.local  192.168.1.200   80

Step 5 — Configure Local DNS

Since oty-k8s.local isn't a real domain, you need to tell your machine to resolve it to the MetalLB IP.

On Windows (open Notepad as Administrator):

C:\Windows\System32\drivers\etc\hosts

On macOS/Linux:

sudo nano /etc/hosts

Add:

192.168.1.200   app.oty-k8s.local
192.168.1.200   api.oty-k8s.local

Now open your browser:

http://app.oty-k8s.local              → Next.js task manager
http://api.oty-k8s.local/api/tasks/   → Django REST API
http://api.oty-k8s.local/health/      → Health check

No port numbers. Clean hostnames. Traffic flows through the Ingress controller on port 80.

Step 6 — NetworkPolicy

Your application is accessible via clean URLs. But at this point any pod in the cluster can reach any other pod — including your PostgreSQL database directly. That's not acceptable.

NetworkPolicy is Kubernetes' built-in firewall for pod-to-pod traffic. By default all pods communicate freely. Once you apply a NetworkPolicy to a pod, it becomes deny-all for the specified traffic direction, and only connections you explicitly allow get through.

The Rules We Want

Ingress Controller → Frontend  (port 3000) ✅
Ingress Controller → Backend   (port 8000) ✅
Frontend           → Backend   (port 8000) ✅
Backend            → Postgres  (port 5432) ✅
Anything else      → Postgres  (port 5432) ❌
Anything else      → Backend   (port 8000) ❌
Anything else      → Frontend  (port 3000) ❌

Apply the policies:

kubectl apply -f /home/oty-k8s/k8s/networkpolicy.yaml

kubectl get networkpolicy -n k8s-vm-app

Expected:

NAME              POD-SELECTOR
postgres-policy   app=postgres
backend-policy    app=django-backend
frontend-policy   app=nextjs-frontend

See the full manifest → k8s/networkpolicy.yaml

Critical YAML Detail — AND vs OR Logic

NetworkPolicy has a subtle YAML structure that's easy to get wrong. The indentation determines whether multiple conditions are ANDed or ORed:

# AND — pod must match BOTH selectors (namespace AND pod label)
ingress:
- from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: ingress-nginx
    podSelector:
      matchLabels:
        app: controller

# OR — pod matches EITHER selector (namespace OR pod label)
ingress:
- from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: ingress-nginx
- from:
  - podSelector:
      matchLabels:
        app: nextjs-frontend

Whether the selectors are under the same - from: list item (AND) or separate - from: items (OR) is determined by indentation. Getting this wrong silently blocks legitimate traffic and is the most common NetworkPolicy mistake.

Step 7 — Testing That NetworkPolicy Actually Works

This is the most important step. Applying the manifests without errors doesn't mean they do what you intended. You need to verify both directions — what's blocked and what's allowed.

Create a Test Pod

Spin up a busybox pod with no labels matching any policy:

kubectl run nettest \
  --image=busybox \
  --restart=Never \
  -n k8s-vm-app \
  -- sleep 3600

This pod represents anything that shouldn't have access — a compromised container, a misconfigured service, or an attacker who somehow got a shell inside the cluster.

Test 1 — Postgres BLOCKED from random pod ❌

kubectl exec -n k8s-vm-app nettest \
  -- nc -zv postgres 5432 -w 3

Expected result:

nc: postgres (10.x.x.x:5432): Connection timed out
command terminated with exit code 1

The postgres NetworkPolicy denies all ingress except from app=django-backend. The nettest pod has no such label — blocked.

Test 2 — Postgres REACHABLE from backend pod ✅

kubectl exec -n k8s-vm-app \
  $(kubectl get pod -n k8s-vm-app -l app=django-backend \
    -o jsonpath='{.items[0].metadata.name}') \
  -- nc -zv postgres 5432 -w 3

Expected result:

postgres (10.x.x.x:5432) open

The backend pod has label app=django-backend which matches the postgres policy's allow rule.

Test 3 — Backend BLOCKED from random pod ❌

kubectl exec -n k8s-vm-app nettest \
  -- nc -zv django-backend 8000 -w 3

Expected result:

nc: django-backend (10.x.x.x:8000): Connection timed out
command terminated with exit code 1

Test 4 — Backend REACHABLE from frontend pod ✅

kubectl exec -n k8s-vm-app \
  $(kubectl get pod -n k8s-vm-app -l app=nextjs-frontend \
    -o jsonpath='{.items[0].metadata.name}') \
  -- nc -zv django-backend 8000 -w 3

Expected result:

django-backend (10.x.x.x:8000) open

The frontend pod has label app=nextjs-frontend which matches the backend policy's allow rule.

Test 5 — End-to-end through Ingress ✅

curl http://api.oty-k8s.local/health/

Expected:

{"status": "ok"}

curl http://api.oty-k8s.local/api/tasks/

Expected:

[]

Or open http://app.oty-k8s.local in your browser — full task manager UI loading through the Ingress controller.

Clean Up

kubectl delete pod nettest -n k8s-vm-app

Test Results Summary

Test	From	To	Port	Expected	What it proves
1	random pod	postgres	5432	❌ timed out	DB unreachable from untrusted sources
2	django-backend	postgres	5432	✅ open	App can reach its DB
3	random pod	django-backend	8000	❌ timed out	API unreachable from untrusted sources
4	nextjs-frontend	django-backend	8000	✅ open	Frontend can call the API
5	laptop browser	app.oty-k8s.local	80	✅ 200 OK	Full stack works end to end

All five passing means your NetworkPolicy enforces exactly what you intended. The cluster is now network-isolated at the pod level.

Understanding the Full Traffic Flow

With everything in place, here's what happens when you open http://app.oty-k8s.local:

Browser (your laptop)
    │
    │ DNS resolves app.oty-k8s.local → 192.168.1.200
    │ HTTP GET / on port 80
    ↓
192.168.1.200 — MetalLB
(assigned to ingress-nginx LoadBalancer service,
 announced via ARP to your local network)
    │
    │ Host header: app.oty-k8s.local
    ↓
Nginx Ingress Controller Pod (ingress-nginx namespace)
    │
    │ Matches rule: app.oty-k8s.local → nextjs-frontend:3000
    │ NetworkPolicy allows ingress-nginx → nextjs-frontend
    ↓
Next.js Pod (k8s-vm-app namespace)
    │
    │ API call to django-backend:8000
    │ NetworkPolicy allows nextjs-frontend → django-backend
    ↓
Django Backend Pod
    │
    │ Query to postgres:5432
    │ NetworkPolicy allows django-backend → postgres
    ↓
PostgreSQL Pod (StatefulSet, PersistentVolume on node disk)

Every hop is intentional. Every connection is explicitly allowed. Anything not on this list is blocked at the network level.

Common Issues and Fixes

no matches for kind "Ingress" in version "networking.k8.io/v1"
Typo — networking.k8.io should be networking.k8s.io. Fix:

sed -i 's/networking.k8.io/networking.k8s.io/g' ingress.yaml

MetalLB IP stays <pending>
Check MetalLB pods are running and the IPAddressPool is configured. Also verify no other service already claimed the IP range.

kubectl get pods -n metallb-system
kubectl get ipaddresspool -n metallb-system

Ingress returns 404 for all paths
The ingressClassName: nginx doesn't match the installed controller class, or the controller isn't ready yet.

kubectl get ingressclass
# Should show: nginx

NetworkPolicy blocking allowed connections
Check that pod labels match exactly what the policy expects:

kubectl get pods -n k8s-vm-app --show-labels

Then review the AND vs OR indentation in your NetworkPolicy YAML.

503 Service Temporarily Unavailable from Ingress
The Ingress controller can reach the service but no pods are passing their readiness probe.

kubectl get endpoints -n k8s-vm-app
# All services should show pod IPs, not <none>

What's Next

You now have a production-style Kubernetes networking setup. Both services are accessible via clean hostnames through a single Ingress entry point, and NetworkPolicy enforces traffic isolation at the network level with verified tests.

The remaining phases of this homelab roadmap:

Phase 3 — Storage and Stateful Systems
PostgreSQL HA with streaming replication as a StatefulSet, backup strategies, and Longhorn for distributed storage across nodes.

Phase 4 — Observability and Security
Full kube-prometheus-stack deployment, custom Grafana dashboards for application metrics, RBAC, ServiceAccounts, PodSecurityAdmission, and encrypting Secrets at rest.

Phase 5 — GitOps with ArgoCD
Helm charts for the application, ArgoCD for continuous deployment with Git as the single source of truth, and Horizontal Pod Autoscaler for automatic scaling under load.

Key Takeaways

NodePort is for learning, not production. It exposes every node's IP on random high ports with no hostname routing. The production pattern is LoadBalancer → Ingress → ClusterIP.

MetalLB is essential for bare metal. Without it, LoadBalancer services pend forever. With it, you get the same experience as cloud Kubernetes — services get real IPs automatically from a pool you control.

NetworkPolicy is deny-by-default once applied. As soon as you add a NetworkPolicy to a pod, all traffic not explicitly allowed is blocked. This is exactly the right security posture — allowlist, not blocklist.

Always test your NetworkPolicy — don't assume it works. The manifest applying without errors doesn't mean it does what you intended. The AND vs OR YAML structure is subtle and easy to get wrong silently. Test both blocked and allowed paths every time.

The Ingress controller is just Nginx. Demystify it: it's a regular nginx reverse proxy that watches the Kubernetes API and updates its config automatically. When routing breaks, you can kubectl exec into the controller pod and inspect the nginx config directly.

Source code: github.com/otie16/k8s-homelab-vm-project

← Part 1: Cluster Setup, Workloads, and a Full-Stack App

Oty is a Lead DevOps/Cloud Engineer and DevOps mentor. Follow for more hands-on infrastructure content.

Tags: Kubernetes DevOps Networking MetalLB Nginx Ingress NetworkPolicy Platform Engineering Homelab Cloud Native

Building a Production-Grade Kubernetes Cluster from Scratch — Part 1: Cluster Setup, Workloads, and a Real App

Otobong Edoho — Wed, 13 May 2026 10:45:57 +0000

Part 1 of 2 — From bare VMs to a fully running 3-service application on a self-managed Kubernetes cluster. No managed services. No shortcuts. Just raw kubeadm.

Series navigation:

Part 1 (you are here): Cluster setup, foundational workloads, deploying a full-stack app with ConfigMaps, Secrets, StatefulSets, and CI pipelines

Part 2: Networking deep dive — MetalLB, Nginx Ingress, clean hostnames, and NetworkPolicy enforcement

Full source code: All application code, Kubernetes manifests, and CI pipelines are available at
github.com/otie16/k8s-homelab-vm-project

There are two kinds of Kubernetes engineers.

The first kind provisions an EKS cluster, deploys a workload, and moves on. They know Kubernetes from the outside — the API, the manifests, the kubectl commands.

The second kind wants to know what's happening underneath. How does the scheduler actually decide where to place a pod? What does kubeadm actually do when you run kubeadm init? Why does Calico need kernel modules? What breaks when your pod CIDR overlaps with your host network?

This series is for the second kind.

I built a two-node Kubernetes cluster from scratch on two Ubuntu VMs in my homelab, deployed a production-style full-stack application on top of it, built CI pipelines with SAST and vulnerability scanning, debugged every error the cluster threw at me, and documented every step. This is that documentation — written so you can follow along, break things, fix them, and walk away understanding why Kubernetes works the way it does.

By the end of Part 1, you'll have:

A fully functional two-node kubeadm cluster
A 3-service application running on it (Next.js + Django REST API + PostgreSQL)
Proper use of ConfigMaps, Secrets, StatefulSets, Jobs, probes, and resource limits
CI pipelines with SAST, dependency scanning, and Docker image vulnerability scanning
A deep understanding of every concept you implemented

The Architecture

Your Laptop
    │
    ├── k8s-master  (192.168.1.100) — Control Plane
    │       kube-apiserver, etcd, scheduler,
    │       controller-manager, CoreDNS, Calico
    │
    └── k8s-worker-node (192.168.1.101) — Worker
            kubelet, kube-proxy, Calico
            Your actual workloads run here

Node specs:

Node	Role	IP	OS	Specs
k8s-master	Control Plane	192.168.1.100	Ubuntu 24.04 LTS	2 vCPU, 4GB RAM
k8s-worker-node	Worker	192.168.1.101	Ubuntu 24.04 LTS	2 vCPU, 4GB RAM

Both VMs run on VMware. You can use VirtualBox, Hyper-V, or any hypervisor — the Kubernetes setup is identical.

Part 1 — Bootstrapping the Cluster

Why kubeadm Instead of a Managed Service?

Managed Kubernetes (EKS, GKE, AKS) hides the control plane from you. You never see the API server. You never touch etcd. You never configure a CNI plugin from scratch. That's great for production but terrible for learning.

kubeadm is the official Kubernetes cluster bootstrapping tool. It handles the hard parts — generating certificates, writing control plane manifests, configuring etcd — while still giving you full access to everything. Running kubeadm once teaches you more about how Kubernetes actually works than months of using managed services.

Step 1 — Set Hostnames

On the control plane VM:

sudo hostnamectl set-hostname k8s-master

On the worker VM:

sudo hostnamectl set-hostname k8s-worker-node

On both VMs, add entries to /etc/hosts so nodes can resolve each other by name:

sudo nano /etc/hosts

Add at the bottom:

192.168.1.100  k8s-master
192.168.1.101  k8s-worker-node

Step 2 — Disable Swap (Both VMs)

Kubernetes requires swap to be off. The kubelet enforces this because swap causes unpredictable memory behaviour that breaks scheduling guarantees — if a container exceeds its memory limit, it should be OOMKilled immediately, not start swapping to disk and silently degrading.

# Disable immediately
sudo swapoff -a

# Disable permanently across reboots
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

Verify:

free -h
# Swap row should show 0B

Step 3 — Load Kernel Modules (Both VMs)

Kubernetes networking needs two kernel modules:

overlay — handles the layered filesystem that containers use
br_netfilter — allows iptables to see traffic crossing network bridges (required for pod-to-pod networking)

sudo modprobe overlay
sudo modprobe br_netfilter

# Make them persist across reboots
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

Step 4 — Set Kernel Networking Parameters (Both VMs)

These sysctl settings tell the kernel to let iptables process bridged traffic and to forward IPv4 packets — both required for Kubernetes networking:

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

# Apply without rebooting
sudo sysctl --system

Step 5 — Install containerd (Both VMs)

Kubernetes needs a container runtime that implements the CRI (Container Runtime Interface). containerd is the standard choice — it's what Docker uses under the hood.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Add Docker's GPG key (containerd ships in Docker's repo)
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y containerd.io

Critical — configure containerd to use the systemd cgroup driver:

Both containerd and kubelet must agree on the cgroup driver. On modern Ubuntu that's systemd. Mismatching them causes kubelet crashes that look completely unrelated to cgroups.

sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# Set SystemdCgroup = true
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' \
  /etc/containerd/config.toml

sudo systemctl restart containerd
sudo systemctl enable containerd
sudo systemctl status containerd

Step 6 — Install kubeadm, kubelet, kubectl (Both VMs)

sudo apt-get install -y apt-transport-https ca-certificates curl gpg

# Add Kubernetes apt repo — write as a single line, not multi-line
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /" | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list

sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl

# Pin versions — prevents accidental upgrades that break version skew rules
sudo apt-mark hold kubelet kubeadm kubectl
sudo systemctl enable kubelet

Important: Write the Kubernetes apt repo entry as a single unbroken line. Multi-line echo commands with backslashes cause malformed entries in the .list file that break apt-get update with E: Malformed entry 1.

Part 2 — Initialising the Control Plane

Step 7 — kubeadm init (Master Only)

sudo kubeadm init \
  --pod-network-cidr=10.244.0.0/16 \
  --apiserver-advertise-address=192.168.1.100

Why 10.244.0.0/16 and not 192.168.0.0/16?

This is a mistake I made the first time. My VMs are on 192.168.1.x. If I used 192.168.0.0/16 as the pod CIDR, it would overlap with the host network. Calico would get confused about which interface belongs to the pod network and which belongs to the host, and every pod would fail to start with stat /var/lib/calico/nodename: no such file or directory. Always choose a pod CIDR that doesn't overlap with your host network.

What kubeadm init does behind the scenes:

Generates all TLS certificates for cluster components
Writes static pod manifests for the API server, etcd, scheduler, and controller manager
Starts the control plane components
Installs CoreDNS
Outputs a kubeadm join command — copy this immediately

Step 8 — Configure kubectl

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Test it:

kubectl get nodes
# k8s-master should show NotReady — normal, CNI isn't installed yet

Step 9 — Install Calico CNI

Without a CNI plugin, pods can't communicate. The NotReady status is because of this.

# Download the manifest so we can edit it
curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml

# Set the correct pod CIDR to match what we used in kubeadm init
sed -i 's|# - name: CALICO_IPV4POOL_CIDR|- name: CALICO_IPV4POOL_CIDR|' calico.yaml
sed -i 's|#   value: "192.168.0.0/16"|  value: "10.244.0.0/16"|' calico.yaml

# Verify the change
grep -A1 "CALICO_IPV4POOL_CIDR" calico.yaml

kubectl apply -f calico.yaml

Watch Calico come up:

watch kubectl get pods -n kube-system

The calico-node pod goes through Init:0/3 → Init:1/3 → Init:2/3 → Running. The init containers pull ~250MB of images so this takes a few minutes. Once calico-node hits Running, the master goes Ready within 60 seconds.

Step 10 — Join the Worker Node

Generate a fresh join command on the master:

kubeadm token create --print-join-command

Run the output on the worker node with sudo:

sudo kubeadm join 192.168.1.100:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

Watch the worker appear:

watch kubectl get nodes

Expected output:

NAME              STATUS   ROLES           AGE   VERSION
k8s-master        Ready    control-plane   10m   v1.28.15
k8s-worker-node   Ready    <none>          2m    v1.29.15

Step 11 — Install the Storage Provisioner

On bare metal, there's no cloud provider to fulfill PersistentVolumeClaim requests automatically. Without a storage provisioner, any pod that requests a PVC will be stuck with FailedScheduling: pod has unbound immediate PersistentVolumeClaims.

Install Rancher's local-path provisioner:

kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.26/deploy/local-path-storage.yaml

# Set it as the default StorageClass
kubectl patch storageclass local-path \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

# Verify
kubectl get storageclass

Expected:

NAME                   PROVISIONER             AGE
local-path (default)   rancher.io/local-path   1m

From this point every PVC in the cluster gets fulfilled automatically. No manual PV creation ever again.

Part 3 — The Application

We're deploying a real 3-service task manager:

Next.js frontend — React UI for creating, completing, and deleting tasks
Django REST API — CRUD endpoints backed by PostgreSQL
PostgreSQL — StatefulSet with persistent storage

All application source code is on GitHub:
github.com/otie16/k8s-homelab-vm-project

The repo contains:

backend/ — Django REST API (models, serializers, views, urls, wsgi, settings)

frontend/ — Next.js task manager UI with App Router

k8s/ — All Kubernetes manifests

.github/workflows/ — CI pipelines for both services

Project Structure

k8s-homelab-vm-project/
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── manage.py
│   ├── core/
│   │   ├── settings.py       # DB config from env, INSTALLED_APPS, TEMPLATES
│   │   ├── urls.py           # health/, ready/, api/ endpoints
│   │   └── wsgi.py           # get_wsgi_application() with django.setup()
│   └── tasks/
│       ├── apps.py           # TasksConfig AppConfig
│       ├── models.py         # Task model
│       ├── serializers.py
│       ├── views.py          # ModelViewSet
│       └── migrations/
│           └── 0001_initial.py
├── frontend/
│   ├── Dockerfile            # Multi-stage with Next.js standalone output
│   ├── next.config.js        # output: 'standalone'
│   └── app/
│       ├── layout.js         # Required root layout for App Router
│       └── page.js           # Task manager UI
├── k8s/
│   ├── namespace.yaml
│   ├── configmap.yaml
│   ├── secret.yaml
│   ├── postgres-statefulset.yaml
│   ├── postgres-service.yaml
│   ├── migrate-job.yaml
│   ├── backend-deployment.yaml
│   ├── backend-service.yaml
│   ├── frontend-deployment.yaml
│   ├── frontend-service.yaml
│   └── deploy.sh
└── .github/
    └── workflows/
        ├── backend-ci.yml
        └── frontend-ci.yml

Key Implementation Decisions Worth Understanding

wsgi.py — the bug that cost me the most time

The single most frustrating error in this entire project was AppRegistryNotReady: Apps aren't loaded yet. The cause: Django's WSGI handler instantiated at module import time before django.setup() runs.

# Wrong — WSGIHandler() called at import time, app registry not ready
from django.core.handlers.wsgi import WSGIHandler
application = WSGIHandler()

# Correct — handles initialisation order properly
import django
from django.core.wsgi import get_wsgi_application
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'core.settings')
django.setup()
application = get_wsgi_application()

This looks like a trivial difference but it determines whether Django's app registry is populated before URL patterns are loaded. The get_wsgi_application() function is the correct public API for exactly this reason. Without it, every request returns 500 and the pod enters CrashLoopBackOff.

Next.js standalone output — why it matters for image size

Without standalone mode, copying node_modules into the final Docker image produces ~800MB. With standalone mode enabled in next.config.js, Next.js traces exactly which files the production server needs. The final image runs node server.js directly — no npm, no Next.js CLI, no node_modules at runtime. Result: ~160MB instead of ~800MB.

The init container pattern — dependency ordering without hacks

Both the migration job and the backend deployment use an init container to wait for PostgreSQL:

initContainers:
- name: wait-for-postgres
  image: busybox
  command: ['sh', '-c',
    'until nc -z postgres 5432; do echo waiting; sleep 2; done']

This blocks the main container from starting until port 5432 responds. No sleep hacks, no retry logic in application code, no race conditions. The main container never starts until the dependency is ready.

Liveness vs Readiness probes — they're not the same thing

Both probes hit different endpoints for a reason:

/health/ → liveness: "Is this container alive?" Failure triggers a container restart.
/ready/ → readiness: "Is this container ready for traffic?" Failure removes the pod from the Service endpoint list without restarting it.

Your Django app might be alive but still warming up. Readiness handles that gracefully — the pod stays up but doesn't receive traffic until it signals it's ready.

Part 4 — Kubernetes Manifests Deep Dive

The full manifests are in k8s/ in the GitHub repo. Here's what each one does and the important decisions behind them.

Namespace

Everything lives in k8s-vm-app. Namespaces isolate resources, apply RBAC boundaries, and scope NetworkPolicy.

ConfigMap and Secret — The Right Separation

This is one of the most important patterns to get right in Kubernetes.

ConfigMap — anything you'd commit to a public git repo. Hostnames, ports, feature flags, non-sensitive config. In our case: DB_HOST, DB_PORT, DB_NAME, DEBUG, ALLOWED_HOSTS, NEXT_PUBLIC_API_URL.

Secret — anything you'd never commit. Passwords, API keys, tokens. In our case: DB_USER, DB_PASSWORD, POSTGRES_PASSWORD, DJANGO_SECRET_KEY.

Both are consumed via envFrom in the pod spec — containers get all keys as environment variables automatically without any hardcoded credentials touching the manifest files.

See → k8s/configmap.yaml | k8s/secret.yaml

PostgreSQL — Why StatefulSet and Not Deployment

This is the most important architectural decision for databases on Kubernetes.

A Deployment treats pods as interchangeable. Any pod can replace any other. No stable identity, no guaranteed ordering.

A StatefulSet gives pods:

Stable identity — pods are named postgres-0, postgres-1, not random hashes. postgres-0.postgres.k8s-vm-app.svc.cluster.local is always that specific pod.
Ordered startup/shutdown — pods start in order and terminate in reverse. Critical for primary/replica database setups.
Per-pod PVCs via volumeClaimTemplates — each replica gets its own PersistentVolumeClaim that follows it even if rescheduled to a different node.

The headless service (clusterIP: None) is required for StatefulSets — it allows DNS to resolve directly to individual pod IPs rather than a virtual cluster IP.

See → k8s/postgres-statefulset.yaml

The Migration Job

Database migrations run once, must complete before the application starts, and should retry on failure. A Kubernetes Job is the exact right primitive for this.

The manifest uses an init container that blocks until postgres:5432 responds, then runs python manage.py migrate --noinput. backoffLimit: 3 means Kubernetes retries up to 3 times on failure.

See → k8s/migrate-job.yaml

Backend and Frontend Deployments

Both deployments use:

RollingUpdate with maxUnavailable: 0 — zero downtime deploys, new pods must be ready before old ones are removed
imagePullPolicy: Always — ensures every rollout pulls the latest image from Docker Hub even if the tag hasn't changed
envFrom consuming both ConfigMap and Secret
Liveness and readiness probes
Resource requests and limits to prevent any single pod from starving others on the node

See → k8s/backend-deployment.yaml | k8s/frontend-deployment.yaml

The Deploy Script

Never apply manifests one by one manually. The deploy script handles ordering and waiting automatically:

chmod +x /home/oty-k8s/k8s/deploy.sh
/home/oty-k8s/k8s/deploy.sh

It applies resources in the correct dependency order, waits for PostgreSQL readiness before migrations, waits for the migration job to complete before the application starts, and stops immediately on any failure (set -e).

See → k8s/deploy.sh

Part 5 — CI Pipelines with Real Security Gates

Every image passes through a security pipeline before reaching Docker Hub. The pipeline architecture:

Push to main
    ↓
Lint + unit tests (flake8 / eslint)
    ↓
SAST: Bandit + pip-audit + Trivy filesystem scan
    ↓
Docker build + Trivy image scan (CRITICAL = fail hard)
    ↓
Push to Docker Hub (only on main, only if all gates pass)

GitHub Secrets Required

Go to your repo → Settings → Secrets and variables → Actions:

DOCKERHUB_USERNAME    your Docker Hub username
DOCKERHUB_TOKEN       Docker Hub access token (not your password)

What Each Security Tool Does

Bandit scans Python source code for security anti-patterns — hardcoded passwords, subprocess with shell=True, SQL string formatting, weak cryptography. Reads your code the way a security reviewer would, without executing it.

pip-audit cross-references every package in requirements.txt against the Python Packaging Advisory Database for known CVEs. If your Django version has a known vulnerability, it fails before the image is built.

Trivy filesystem scan runs against the source directory before the Docker build. Catches secrets accidentally committed, misconfigured files, and dependency vulnerabilities through a different database than pip-audit — the overlap is intentional.

Trivy image scan runs against the final built image layers. This is the deepest scan — it catches OS-level vulnerabilities that no source-level tool would see. A vulnerable libssl in the Alpine base image, for example. CRITICAL severity fails the pipeline hard. HIGH severity generates a report but doesn't block.

The key gate: nothing reaches Docker Hub unless lint, SAST, and image scanning all pass, and only on pushes to main.

See the full pipeline files:

Part 6 — Deploying to the Cluster

Clone the repo:

git clone https://github.com/otie16/k8s-homelab-vm-project.git
cd k8s-homelab-vm-project

Update the image names in the deployment manifests to your Docker Hub username, then build and push both images:

# Backend
cd backend
docker build -t YOUR_USERNAME/k8s-vm-app-backend:latest .
docker push YOUR_USERNAME/k8s-vm-app-backend:latest

# Frontend
cd ../frontend
docker build -t YOUR_USERNAME/k8s-vm-app-frontend:latest .
docker push YOUR_USERNAME/k8s-vm-app-frontend:latest

Copy manifests to the master node:

scp -r k8s/ oty-k8s@192.168.1.100:/home/oty-k8s/

SSH to the master and run the deploy script:

ssh oty-k8s@192.168.1.100
chmod +x /home/oty-k8s/k8s/deploy.sh
/home/oty-k8s/k8s/deploy.sh

Watch everything come up:

kubectl get all -n k8s-vm-app

Expected final state:

NAME                                  READY   STATUS
pod/django-backend-xxx                1/1     Running
pod/django-backend-yyy                1/1     Running
pod/nextjs-frontend-xxx               1/1     Running
pod/nextjs-frontend-yyy               1/1     Running
pod/postgres-0                        1/1     Running
pod/django-migrate-job-xxx            0/1     Completed

NAME                      TYPE        PORT(S)
service/django-backend    NodePort    8000:30000/TCP
service/nextjs-frontend   NodePort    3000:30001/TCP
service/postgres          ClusterIP   None

Access the app:

Frontend:    http://192.168.1.100:30001
Backend API: http://192.168.1.100:30000/api/tasks/
Health:      http://192.168.1.100:30000/health/

The Errors That Cost Me The Most Time

No honest Kubernetes writeup skips the debugging. Here are the ones worth knowing about:

stat /var/lib/calico/nodename: no such file or directory
Pod CIDR overlapping with the host network. Calico can't figure out which interface is for pods vs the host. Fix: use a CIDR that doesn't overlap — 10.244.0.0/16 when hosts are on 192.168.x.x.

AppRegistryNotReady: Apps aren't loaded yet
Django's WSGI handler instantiated at module import time before django.setup() runs. Fix: use get_wsgi_application() with explicit django.setup(). One line of difference, hours of debugging.

E: Malformed entry 1 in list file /etc/apt/sources.list.d/kubernetes.list
Multi-line echo commands with backslashes write literal newlines into the apt sources file. Fix: always write the deb entry as a single unbroken line.

pod has unbound immediate PersistentVolumeClaims
No storage provisioner on bare metal. Fix: install local-path-provisioner.

secret "app-secret" not found
Secret name mismatch — created as app-secrets (with an s) but manifests referenced app-secret. Fix: audit all references with grep -r "secretRef" k8s/.

Calico token expiry — Unauthorized on pod sandbox creation
Calico's CNI kubeconfig uses a projected ServiceAccount token with a 24-hour TTL. When it expires, new pod sandboxes fail. Workaround: delete the calico-node pod on the affected node — the daemonset recreates it with a fresh token.

# Refresh the Calico token on the worker
kubectl delete pod -n kube-system \
  $(kubectl get pods -n kube-system -o wide | grep calico-node | grep worker | awk '{print $1}')

What's Next

You now have a production-style cluster running a real application with proper security patterns. But two things aren't production-ready yet:

Services exposed on ugly NodePort high ports (30000, 30001)
No network-level isolation between pods

Part 2 fixes both — MetalLB for real LoadBalancer IPs, Nginx Ingress for clean hostname routing on port 80, and NetworkPolicy with real tests to verify traffic isolation works.

👉 Continue to Part 2: MetalLB, Nginx Ingress, and NetworkPolicy

Key Takeaways

kubeadm is the best learning tool for Kubernetes. Managed services hide the control plane. kubeadm forces you to understand certificates, etcd, CNI plugins, and component communication at a level that makes you significantly better at operating any Kubernetes cluster.

Bare metal is harder and more educational. No cloud LoadBalancer. No storage provisioner. No managed node groups. Every abstraction you take for granted in EKS has to be built manually — and every time you build it manually, you understand it better.

The debugging process is the education. Every error in this post was a lesson. The AppRegistryNotReady error taught me how Django's WSGI initialisation works at a depth I never would have reached following a happy-path tutorial.

Version skew matters. My master runs v1.28.15 and my worker joined at v1.29.15 — one minor version difference. Kubernetes tolerates this, but in production you manage it carefully.

Source code: github.com/otie16/k8s-homelab-vm-project

Follow for Part 2 — MetalLB, Nginx Ingress, and NetworkPolicy.

Tags: Kubernetes DevOps Platform Engineering kubeadm Homelab Cloud Native Docker Django NextJS

Using Dockerfile and Docker Compose For Local Development with Node.js, MongoDB and MongoExpress

Otobong Edoho — Tue, 15 Oct 2024 11:03:43 +0000

Introduction

In this post, I'll show you how to set up a local development environment using Docker with Node.js, MongoDB, and MongoExpress. Docker is a powerful tool that makes it easy to package applications and their dependencies, ensuring consistency across different environments.

The goal of this guide is to help you spin up a simple Node.js app connected to a MongoDB database. We'll also use MongoExpress as a lightweight web-based interface to manage the database, all running inside Docker containers. By the end of this post, you’ll have a fully functional environment that can be set up and torn down with just a few commands.

Prerequisites
Before we dive in, please make sure you have the following installed:

Docker: You can download and install Docker from here.
Basic understanding of Node.js and MongoDB.
An EC2 Cloud instance for Non-ubuntu users

If you’re new to Docker, there's no need to worry! This guide will walk you through the essential commands you need to know to get your environment up and running.

Setting up the Project

Setup for Docker
So we will start setting up the project, The first thing we need to do is pull the mongodb images and mongo express UI image from dockerhub.

Let's install docker but first we need to update the package lists

sudo apt update
sudo apt upgrade -y

Install Required Dependencies
Install packages that allow apt to use repositories over HTTPS:

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

Add Docker’s Official GPG Key

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Set Up the Docker Repository
Add the Docker repository to apt sources:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Now that docker is installed its time to pull the images
Let's pull the mongodb image first

The docker run command does two things, it pulls the image and runs the image which is what we call a container. A container is the running instance of an image.

Docker containers run in an isolated network meaning if we are running two different containers and we want them to be able to communicate we must put them in the same network.

Explanation of the Screenshot:

`docker run`:

This command starts a new container from a Docker image.

`-d`:

The -d flag tells Docker to run the container in "detached" mode (in the background), so it won't block the terminal.

`-p 27017:27017`:

This option maps port 27017 on the host machine to port 27017 in the container. MongoDB uses this port for communication.

The syntax is host_port:container_port, which means MongoDB will be accessible via localhost:27017 on the host machine.

`--network mongo-network`:

This option connects the container to a Docker network named mongo-network. The network allows multiple containers to communicate with each other.

If the network doesn't exist, create it with docker network create mongo-network.

`--name mongodb`:

This assigns a name (mongodb) to the running container. It allows you to refer to the container by name rather than by its container ID.

`-e MONGO_INITDB_ROOT_USERNAME=admin`:

The -e flag sets environment variables inside the container. In this case, it sets MONGO_INITDB_ROOT_USERNAME to admin, which specifies the MongoDB root user's username.

`-e MONGO_INITDB_ROOT_PASSWORD=changethis123`:

Similar to the previous option, this sets the environment variable MONGO_INITDB_ROOT_PASSWORD to changethis123, defining the password for the MongoDB root user.

`mongo`:

This is the name of the image to use. In this case, it is the official MongoDB image from Docker Hub.

Now that we have some knowledge about docker let's proceed to pull the mongodb express image and run it

To check the network available, we can run
docker network ls

It will output the name of the network that we just created, so they can talk to each other using just the container name.

So we can access the mongo express server from our browser using localhost:8081

Now there's a quicker and better setup, that is using dockerfile and docker compose rather than just running the commands in the terminal. Just to be clear a Docker Compose file uses YAML syntax, it defines how to configure and run multi-container applications on Docker while a Dockerfile is a text file that contains instructions for building a container image.

Setting up the Project

First, let's create a simple Node.js application. If you don't already have Node.js installed, you can download it here.

Start by creating a project folder:

   mkdir docker-node-mongo
   cd docker-node-mongo

Initialize a new Node.js project:

   npm init -y

Install the necessary dependencies. For this setup, we’ll need Express for our web server and Mongoose to interact with MongoDB:

   npm install express mongoose

Create an index.js file with a simple Express server and a MongoDB connection using Mongoose:

   const express = require('express');
   const mongoose = require('mongoose');

   const app = express();
   const port = 3000;

   // MongoDB connection
   mongoose.connect('mongodb://mongo:27017/testdb', {
     useNewUrlParser: true,
     useUnifiedTopology: true,
   }).then(() => {
     console.log('Connected to MongoDB');
   }).catch(err => {
     console.log('Failed to connect to MongoDB', err);
   });

   // Routes
   app.get('/', (req, res) => {
     res.send('Hello from Node.js and MongoDB');
   });

   app.listen(port, () => {
     console.log(`App running at http://localhost:${port}`);
   });

This sets up a basic Express server and connects it to a MongoDB instance running on mongodb://mongo:27017/testdb. Now let's Dockerize it.

Creating a Dockerfile for Node.js

Next, we need to create a Dockerfile that will define the environment for our Node.js app. A Dockerfile is essentially a blueprint for building the Docker image that will contain your application.

Create a file called Dockerfile in the root of your project directory and add the following:

# Use the official Node.js image from Docker Hub
FROM node:16

# Set the working directory inside the container
WORKDIR /app

# Copy package.json and install dependencies
COPY package*.json ./
RUN npm install

# Copy the rest of the app files
COPY . .

# Expose the port the app runs on
EXPOSE 3000

# Command to run the app
CMD ["node", "index.js"]

This Dockerfile will:

Use the official Node.js image.
Set the working directory to /app.
Copy the package.json and install the necessary dependencies.
Copy the rest of the files and set the entry point to run the Node.js app.

Setting up MongoDB and MongoExpress with Docker Compose

Instead of running all services separately, we'll use Docker Compose to define and manage our multi-container environment. Docker Compose allows us to define services, networks, and volumes in a docker-compose.yml file, making it easy to orchestrate our entire stack. One thing to remember is that when using docker compose we don't need to create a network it automatically creates a network for our multiple containers defined in the yaml file.

Create a docker-compose.yml file in the project root:

version: '3'
services:
  nodeapp:
    build: .
    ports:
      - '3000:3000'
    volumes:
      - .:/app
    depends_on:
      - mongo
  mongo:
    image: mongo
    ports:
      - '27017:27017'
  mongo-express:
    image: mongo-express
    ports:
      - '8081:8081'
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: root
      ME_CONFIG_MONGODB_ADMINPASSWORD: example
      ME_CONFIG_MONGODB_SERVER: mongo

This configuration defines three services:

nodeapp: Our Node.js application.
mongo: A MongoDB instance running on port 27017.
mongo-express: A web-based interface to manage MongoDB, accessible on port 8081.

Running the Application

With everything set up, let’s run the app using Docker Compose.

Run the following command in your terminal:

docker-compose up

To shut down the multiple containers currently using Docker Compose

docker-compose down

Docker Compose will pull the necessary images, build the Node.js app, and start all services. After the process completes, you should see logs from MongoDB, Node.js, and MongoExpress.

Visit http://localhost:3000 to see the Node.js app running.
Visit http://localhost:8081 to access MongoExpress and manage your database.

Connecting Node.js to MongoDB

Our Node.js app is already set up to connect to MongoDB with the following connection string inside index.js:

mongoose.connect('mongodb://mongo:27017/testdb', {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});

The mongo hostname refers to the MongoDB service defined in our docker-compose.yml. Docker Compose automatically creates a network for the services, allowing them to communicate by their service names.

Conclusion

In this post, we’ve successfully set up a local development environment using Docker for Node.js, MongoDB, and MongoExpress. Using Docker Compose, we orchestrated multiple containers to work together seamlessly, making it easier to spin up a fully functional stack for development.

With this setup, you can easily add more services, manage your databases with MongoExpress, and have an isolated environment without needing to install MongoDB or other dependencies locally.

Happy Reading!!! Please Like, save, share and follow!!!

How to Publish a Java Artifact Built with Gradle to a Nexus Repository part 1

Otobong Edoho — Wed, 28 Aug 2024 12:41:29 +0000

What is a Nexus repository?

Nexus repository is a publicly accessible repository manager from Sonatype that organizes, stores and helps in distribution of artifacts used in software development.

It has built in support many for artifact formats such as Docker, Java, Go, PHP, Python etc.

Artifacts simply put refers to outcome of software build and packaging process

Importance of Publishing Java Artifacts to a Central Repository

Publishing Java artifacts to a central repository, like Nexus, is an important practice in modern software development for several reasons:

Team Collaboration: In a team environment, a central repository allows developers to share libraries, frameworks, or any reusable code easily.
Integration with CI/CD Pipelines: Publishing to a central repository is often a key step in CI/CD pipelines. Artifacts can be automatically deployed to a repository after a successful build, making them immediately available for testing or production deployment.
Version Control: Central repositories allow developers to manage multiple versions of an artifact. This enables the use of specific versions, ensuring compatibility and stability across different project development.

Prerequisites

Java Development Kit 17 installed.
Gradle installed and configured.
Access to a Nexus Repository (public or private).
Basic understanding of Gradle build scripts (build.gradle).
An EC2 Instance or any other Cloud Service

Install Nexus

So before we install nexus we will setup an EC2 instance where we can install and run nexus.

To install Java on the instance

apt install openjdk-17-jre-headless

When that is done you can install nexus using this command



cd /opt
wget https://download.sonatype.com/nexus/3/nexus-3.71.0-06-unix.tar.gz
ls

It comes as a tar ball so we need to extract it

tar -xvzf nexus-3.71.0-06-unix.tar.gz

Run ls and you should see this

Run ls -l to see the files and the owners, the root has ownership to the files so we need to give ownership to a nexus user which we will create. It is best practice to always create a user for any service we want to run.

Let's create a nexus user and add the user to nexus group



adduser nexus
usermod -aG nexus nexus

while still in the /opt directory run this command



chown -R nexus:nexus nexus-3.71.0-06
chown -R nexus:nexus sonatype-work

Set nexus config so it will run as a nexus user
vim nexus-3.71.0-06/bin/nexus.rc

This should open up the file in vim edit the run_as_user="nexus" like this

Now switch to the nexus user and run the nexus service



su - nexus
/opt/nexus-3.71.0-06/bin/nexus start

Use the command below to check the service and on which port running.

We can see that nexus is running in port 8081, if the port is blocked on your EC2 instance you need to configure the security groups to allow inbound traffic on that port.

Next Use the public IP address of your instance and the nexus port number like this
18.232.173.21:8081
to be able to access the nexus interface from our browser

To get the default password for the admin interface navigate to the following directory



/opt/sonatype-work/nexus-3.71.0-06/
cat admin.password

Use that to login, the username is admin

After logging in the admin interface should look like this

maven-releases repository is where we store artifacts that have been tested and are ready to be deployed to production.
maven-snapshots repository is where we store artifacts that are still in the development and test phase.

Let's say a developer in our company want to publish an artifact to nexus we can't let them use the admin account, we must create an account for that user

Navigate to the Users tab and create local user

Go to User roles and create a role for the created user

Best Practice: We don't want our user having too many privileges so we will only assign a role in which the user needs to carry out a task

We are building with gradle in this case but the role still works the same as maven so we will set the following role

Now we Assign that role that we created to the user

Configure Gradle with Nexus
Apply the following configurations and plugin to the build.gradle file



group = 'com.example'
version = '1.0.0-SNAPSHOT'
sourceCompatibility = '17'
targetCompatibility = '17'

apply plugin: 'maven-publish'

This code block publishes the artifact that we have built



publishing {
//  The Artifacts we are going to upload
    publications {
        maven(MavenPublication) {
            artifact("build/libs/java-react-example-${version}.jar") {
                extension 'jar'
            }
        }
    }

This code block defines the address that we are going to publish to.
The allowInsecureProtocol = true
Allows the publishing to work regardless of the fact that we are not using https
The credentials declares the user account that we created on our Nexus repository, so it will give access for our user to publish to the repository



// The Nexus repo that we will upload the Jar file to
    repositories {
        maven {
            name 'nexus'
            url "http://[Your Public IP]:8081/repository/maven-snapshots/"
//        So that it will all HTTP
            allowInsecureProtocol = true
            credentials {
                username project.repoUser
                password project.repoPassword
            }
        }
    }
}

Let's create a gradle.properties in our project file to store our user secret



repoUser = oty
repoPassword = xxxxxxxxxxx

Create a settings.gradle file if it doesn't exist and add the project name



rootProject.name ='java-react-example'

If you haven't already built the project run then publish it



gradle build
gradle publish

Now we can go to our nexus repository and view our publish artifact

Happy Reading!!!
Please Like and Follow if You liked the Article.
Thank You.

Git Commit Hacks Every Developer Should Know

Otobong Edoho — Tue, 20 Aug 2024 11:23:52 +0000

1. Mastering Git Commit: The Foundation of Version Control

The git commit command is the bedrock of Git. Each commit represents a snapshot of your project at a particular point in time. Here’s how to make the most of it:

Atomic Commits
Atomic commits are all about keeping each commit focused and self-contained. When you make small, focused commits, it becomes easier to track down the source of bugs and understand the evolution of the project. Each commit should ideally address one specific issue or feature.

git commit

2. Undoing Mistakes: Git Revert vs. Git Reset
Mistakes happen. When they do, Git provides powerful tools to help you undo them.

Safe Reversal with git revert
If you need to undo a commit without altering the commit history, git revert is your best friend. Unlike git reset, which changes your history, git revert creates a new commit that undoes the changes introduced by a previous commit.

git revert <id>

This is especially useful in shared repositories where altering history can cause issues for others.

Hard Reset with git reset --hard <id>
On the other hand, git reset --hard is a more drastic measure. It resets your current branch to the specified commit, discarding all changes in the working directory and the index

git reset --hard <id>

3. Navigating History: Leveraging Git Checkout
git checkout <id> is a versatile command that allows you to switch between branches or revisit specific commits.

git checkout <id>

Exploring Old Versions with git checkout <id>
Sometimes, you need to look at an older version of your code to understand how a feature was implemented or to test an earlier state of the project. You can temporarily switch to an older commit using.

4. Understanding Git Log: Navigating Your Project’s History
The git log command is an essential tool for any developer working with Git. It allows you to view the history of commits in a repository, providing a detailed log of all the changes made over time. Here's how you can make the most out of git log.

git log

By understanding these commands and when to use them, you can wield Git more effectively and maintain a clean, understandable project history.

Happy Reading!!!!!!!

Setting Up Postgresql Database for Servers

Otobong Edoho — Thu, 25 Jul 2024 21:23:53 +0000

Introduction

PostgreSQL is an advanced object relational database sytem that uses and also extends the SQL language. The good thing about postgreSQL that it is Open source.

Developers and Database administrators alike use postgreSQL because of it's high data consistencey and data integrity which proves to be more reliable than other SQL databases.

This is a stage 4 task that I worked on as HNG11 intern, It was a team based task, the team consisted of 6 members.

This post will cover

Installation of postgreSQL
Creation of the Database and user
Configuring PostgreSQL

Prerequisites

List of required tools and software (e.g., PostgreSQL, SSH client)
Basic knowledge required (e.g., familiarity with terminal commands, server access)

Install PostgreSQL along with its additional features

sudo apt install postgresql postgresql-contrib

Switch to the PostgreSQL user to perform the needed administrative tasks

sudo -i -u postgres

# opening  the sql prompt
psql

Within the PostgreSQL prompt, create the required databases for the production, staging and development environments

CREATE DATABASE langlearnai_be_staging_db;
CREATE DATABASE langlearnai_be_main_db;
CREATE DATABASE langlearnai_be_dev_db;

Create Users and assign passwords for each enviroment

CREATE USER langlearnai_be_staging_user WITH ENCRYPTED PASSWORD 'staging_password';
CREATE USER langlearnai_be_main_user WITH ENCRYPTED PASSWORD 'main_password';
CREATE USER langlearnai_be_dev_user WITH ENCRYPTED PASSWORD 'dev_password';

Grant the necessary Privileges to Users

GRANT ALL PRIVILEGES ON DATABASE langlearnai_be_staging_db TO langlearnai_be_staging_user;
GRANT ALL PRIVILEGES ON DATABASE langlearnai_be_main_db TO langlearnai_be_main_user;
GRANT ALL PRIVILEGES ON DATABASE langlearnai_be_dev_db TO langlearnai_be_dev_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO langlearnai_be_staging_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO langlearnai_be_main_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO langlearnai_be_dev_user;

Exit the PostgreSQL prompt:

\q

Configure and modified the Postgres configuration files to allow PostgreSQL to Listen on External IP

sudo vim /etc/postgresql/13/main/postgresql.conf

Locate the listen_addresses line and change to:

listen_addresses = "*"

Open the pg_hba.conf file

sudo vim /etc/postgresql/13/main/pg_hba.conf

Add the following lines under IPV4 local connections to allow external access. i.e These lines configure PostgreSQL to accept connections from the specified IP address

# IPv4 local connections
host    all             all             0.0.0.0/0               md5
host    postgres        postgres        <server-ip-address>/32      md5
host    langlearnai_be_dev_db  langlearnai_be_dev_user  <server-ip-address>/32    md5
host    langlearnai_be_main_db  langlearnai_be_main_user  <server-ip-address>/32    md5
host    langlearnai_be_staging_db  langlearnai_be_staging_user  <server-ip-address>/32    md5

Restart to apply changes and enable the PostgreSQL service to start on system boot

sudo systemctl restart postgresql
sudo systemctl enable postgresql

Allow connections on port through firewall

sudo ufw allow 5432/tcp

Accessing the Database

To connect to the PostgreSQL database remotely, use the following command

psql -h your_server_ip -U your_database_username -d your_database_name

Happy Reading and Learning

Setting Up Postgresql Database for Servers

Otobong Edoho — Thu, 25 Jul 2024 21:23:53 +0000

Introduction

PostgreSQL is an advanced object relational database sytem that uses and also extends the SQL language. The good thing about postgreSQL that it is Open source.

Developers and Database administrators alike use postgreSQL because of it's high data consistencey and data integrity which proves to be more reliable than other SQL databases.

This is a stage 4 task that I worked on as HNG11 intern, It was a team based task, the team consisted of 6 members.

This post will cover

Installation of postgreSQL
Creation of the Database and user
Configuring PostgreSQL

Prerequisites

List of required tools and software (e.g., PostgreSQL, SSH client)
Basic knowledge required (e.g., familiarity with terminal commands, server access)

Install PostgreSQL along with its additional features

sudo apt install postgresql postgresql-contrib

Switch to the PostgreSQL user to perform the needed administrative tasks

sudo -i -u postgres

# opening  the sql prompt
psql

Within the PostgreSQL prompt, create the required databases for the production, staging and development environments

CREATE DATABASE langlearnai_be_staging_db;
CREATE DATABASE langlearnai_be_main_db;
CREATE DATABASE langlearnai_be_dev_db;

Create Users and assign passwords for each enviroment

CREATE USER langlearnai_be_staging_user WITH ENCRYPTED PASSWORD 'staging_password';
CREATE USER langlearnai_be_main_user WITH ENCRYPTED PASSWORD 'main_password';
CREATE USER langlearnai_be_dev_user WITH ENCRYPTED PASSWORD 'dev_password';

Grant the necessary Privileges to Users

GRANT ALL PRIVILEGES ON DATABASE langlearnai_be_staging_db TO langlearnai_be_staging_user;
GRANT ALL PRIVILEGES ON DATABASE langlearnai_be_main_db TO langlearnai_be_main_user;
GRANT ALL PRIVILEGES ON DATABASE langlearnai_be_dev_db TO langlearnai_be_dev_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO langlearnai_be_staging_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO langlearnai_be_main_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO langlearnai_be_dev_user;

Exit the PostgreSQL prompt:

\q

Configure and modified the Postgres configuration files to allow PostgreSQL to Listen on External IP

sudo vim /etc/postgresql/13/main/postgresql.conf

Locate the listen_addresses line and change to:

listen_addresses = "*"

Open the pg_hba.conf file

sudo vim /etc/postgresql/13/main/pg_hba.conf

Add the following lines under IPV4 local connections to allow external access. i.e These lines configure PostgreSQL to accept connections from the specified IP address

# IPv4 local connections
host    all             all             0.0.0.0/0               md5
host    postgres        postgres        <server-ip-address>/32      md5
host    langlearnai_be_dev_db  langlearnai_be_dev_user  <server-ip-address>/32    md5
host    langlearnai_be_main_db  langlearnai_be_main_user  <server-ip-address>/32    md5
host    langlearnai_be_staging_db  langlearnai_be_staging_user  <server-ip-address>/32    md5

Restart to apply changes and enable the PostgreSQL service to start on system boot

sudo systemctl restart postgresql
sudo systemctl enable postgresql

Allow connections on port through firewall

sudo ufw allow 5432/tcp

Accessing the Database

To connect to the PostgreSQL database remotely, use the following command

psql -h your_server_ip -U your_database_username -d your_database_name

Happy Reading and Learning

Forem: Otobong Edoho

Kubernetes Networking Deep Dive — Part 2: MetalLB, Nginx Ingress, and NetworkPolicy

Why NodePort Is Not Enough

The Problem with LoadBalancer on Bare Metal

Step 1 — Install MetalLB

Configure the IP Address Pool

Step 2 — Install Nginx Ingress Controller

Step 3 — Update Services to ClusterIP

Step 4 — Create the Ingress Resource

Step 5 — Configure Local DNS

Step 6 — NetworkPolicy

The Rules We Want

Critical YAML Detail — AND vs OR Logic

Step 7 — Testing That NetworkPolicy Actually Works

Create a Test Pod

Test 1 — Postgres BLOCKED from random pod ❌

Test 2 — Postgres REACHABLE from backend pod ✅

Test 3 — Backend BLOCKED from random pod ❌

Test 4 — Backend REACHABLE from frontend pod ✅

Test 5 — End-to-end through Ingress ✅

Clean Up

Test Results Summary

Understanding the Full Traffic Flow

Common Issues and Fixes

What's Next

Key Takeaways

Building a Production-Grade Kubernetes Cluster from Scratch — Part 1: Cluster Setup, Workloads, and a Real App

The Architecture

Part 1 — Bootstrapping the Cluster

Why kubeadm Instead of a Managed Service?

Step 1 — Set Hostnames

Step 2 — Disable Swap (Both VMs)

Step 3 — Load Kernel Modules (Both VMs)

Step 4 — Set Kernel Networking Parameters (Both VMs)

Step 5 — Install containerd (Both VMs)

Step 6 — Install kubeadm, kubelet, kubectl (Both VMs)

Part 2 — Initialising the Control Plane

Step 7 — kubeadm init (Master Only)

Step 8 — Configure kubectl

Step 9 — Install Calico CNI

Step 10 — Join the Worker Node

Step 11 — Install the Storage Provisioner

Part 3 — The Application

Project Structure

Key Implementation Decisions Worth Understanding

Part 4 — Kubernetes Manifests Deep Dive

Namespace

ConfigMap and Secret — The Right Separation

PostgreSQL — Why StatefulSet and Not Deployment

The Migration Job

Backend and Frontend Deployments

The Deploy Script

Part 5 — CI Pipelines with Real Security Gates

GitHub Secrets Required

What Each Security Tool Does

Part 6 — Deploying to the Cluster

The Errors That Cost Me The Most Time

What's Next

Key Takeaways

Using Dockerfile and Docker Compose For Local Development with Node.js, MongoDB and MongoExpress

Introduction

Setting up the Project

Explanation of the Screenshot:

docker run:

-d:

-p 27017:27017:

--network mongo-network:

--name mongodb:

-e MONGO_INITDB_ROOT_USERNAME=admin:

-e MONGO_INITDB_ROOT_PASSWORD=changethis123:

mongo:

Setting up the Project

Creating a Dockerfile for Node.js

Setting up MongoDB and MongoExpress with Docker Compose

Running the Application

Connecting Node.js to MongoDB

Conclusion

How to Publish a Java Artifact Built with Gradle to a Nexus Repository part 1

Git Commit Hacks Every Developer Should Know

Setting Up Postgresql Database for Servers

`docker run`:

`-d`:

`-p 27017:27017`:

`--network mongo-network`:

`--name mongodb`:

`-e MONGO_INITDB_ROOT_USERNAME=admin`:

`-e MONGO_INITDB_ROOT_PASSWORD=changethis123`:

`mongo`: