How to Debug NestJS Micro‑services Locally Inside Kubernetes with VS Code & Skaffold

Ever spend minutes rebuilding, pushing, and redeploying just to verify a single NestJS breakpoint? Local debugging against a Kubernetes cluster can feel that way — until you streamline it. In this walkthrough, you’ll install and configure VS Code (with the Google Cloud Code extension), Skaffold, and Docker Desktop’s Kubernetes. By the end, you’ll set a breakpoint in under 10 seconds and hit it live in a NestJS pod.

Table of Contents

• What is Local Kubernetes Debugging?

• How It Works: VS Code, Skaffold & Docker Desktop

• Install Prerequisites

• Generate Demo Services

• Containerize with Dockerfiles

• Write Kubernetes Manifests

• Bootstrap Skaffold & Attach the VS Code Debugger

• Exercise Breakpoints

What is Local Kubernetes Debugging?

Local Kubernetes debugging means running your application inside a Kubernetes cluster on your own machine — rather than relying on a remote test or production cluster — and connecting your IDE’s debugger directly into those live pods. Instead of editing code, rebuilding Docker images, pushing them to a registry, and waiting for redeployments, you…

- Build locally: Skaffold (or a similar tool) watches your source files and incrementally rebuilds and deploys updated images to your local cluster.

- Run in-cluster: Docker Desktop (or Minikube, Kind, etc.) hosts a full Kubernetes control plane right on your laptop.

- Attach live debugger: VS Code (with Cloud Code) or another IDE forwards your breakpoints into the running container via the Node inspector protocol.

This approach gives you the best of both worlds:

- Fidelity: You’re debugging against actual Kubernetes manifests (services, ConfigMaps, Secrets, and Ingresses) rather than a simplified local process.

- Speed: You cut out manual Docker pushes and Kubernetes rollouts, so you can set and hit breakpoints in seconds.

- Confidence: By exercising the same pod startup and networking logic that you’ll use in production, you eliminate “it works on my machine” surprises.

In the next section, we’ll look under the hood at how VS Code, Skaffold, and Docker Desktop collaborate to make this magic happen.

How It Works: VS Code, Skaffold & Docker Desktop

Under the hood, local Kubernetes debugging stitches together three core tools in a continuous edit→build→deploy→debug loop:

- VS Code + Google Cloud Code

• When you click “Start Debugging,” Cloud Code runs your NestJS app in debug mode (under the hood it does something like node — inspect=0.0.0.0:9229 -r ts-node/register src/main.ts), which you can also invoke directly via:

nest start — debug — watch

This opens port 9229 inside the container and restarts on file changes.

• VS Code then establishes a port-forward from your local machine to that debug port, letting you set and hit breakpoints as if the code were running natively.

- Skaffold

• By enabling ”watch”: true in your VS Code launch.json, Skaffold watches your source directory for file changes.

• On save, it rebuilds only the layers that changed (leveraging Docker’s cache), tags the new image, and updates the running Deployment in your local cluster.

• Because it reuses the same container name and labels, Cloud Code’s port-forward stays intact — no need to re-attach your debugger.

- Docker Desktop’s Kubernetes

• Provides a complete, single-node Kubernetes control plane on your laptop (no remote clusters required).

• Applies your Deployment, Service, and other manifests just as they would run in production — same scheduler, same pod networking, same volume mounts.

• Keeps everything local and lightweight, so you incur minimal latency and bandwidth usage.

Install Prerequisites

Before you start, install and verify the following tools. Click each link for detailed setup instructions:

• Docker Desktop (with Kubernetes)

Download and install Docker Desktop, then enable the built-in Kubernetes cluster in Settings → Kubernetes.

Docker Desktop Docs

- Visual Studio Code + Google Cloud Code

Install VS Code and add the Cloud Code extension for Kubernetes & Skaffold integration.

VS Code • Cloud Code Extension

- Skaffold CLI

Install Skaffold to watch, build, and deploy on file changes.

Skaffold Installation Guide

- kubectl

Install the Kubernetes CLI to apply manifests and inspect your local cluster.

kubectl Installation Guide

- Node.js & Nest CLI

Install Node.js (v20+) and the Nest CLI for scaffolding and running your services.

Node.js Downloads • Nest CLI Docs

- (Optional) Asciinema or VS Code Screencast

For recording your breakpoint demo as a GIF, install Asciinema or use VS Code’s built-in screencast recorder (⌘⇧P → “Record Screencast”).

Generate Demo Services

Next, scaffold and verify two minimal NestJS services so you can demo multi-service debugging:

- Scaffold each service

nest new nest-one

nest new nest-two

- Install, build

cd nest-one

npm install

npm run build

cd ../nest-two

npm install

npm run build

- Verify each service runs

cd nest-one

nest start — debug — watch

• Confirms the compiled code is served on port 3000 with the inspector on 9229.

• Visit http://localhost:3000 to see the default NestJS welcome.

• Press Ctrl+C to stop.

• nest-two in the same way.

With both services scaffolded, built, tested, and verified, you’re ready to containerize them and define your Kubernetes manifests.

Containerize with Dockerfiles

To run your services in Kubernetes, we’ll use a multi-stage Dockerfile that optimizes for both development (debug) and production builds. Here’s an example you can drop into each service’s root directory:

# ─── base ───────
FROM node:22-alpine AS base
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# ─── debug ───────
FROM base AS debug
ENV NODE_ENV=development
EXPOSE 3000 9229
RUN npm install -g @nestjs/cli
CMD ["npm", "run", "start:debug"]
# ─── builder ───────
FROM base AS builder
RUN npm run build
# RUN npm test
# ─── production ───
FROM node:22-alpine AS production
RUN addgroup - system appgroup && adduser - system - ingroup appgroup appuser
WORKDIR /app
COPY - from=builder /app/package*.json ./
RUN npm ci - omit=dev
COPY - from=builder /app/dist ./dist
EXPOSE 3000
USER appuser
CMD ["node", "dist/main.js"]

Write Kubernetes Manifests

In the k8s/ folder of the repo you’ll find example manifests you can copy and adapt:

• nest-one-deployment.yaml & nest-one-service.yaml

• nest-two-deployment.yaml & nest-two-service.yaml

Deployment

Each Deployment manifest defines how to run your service in Kubernetes, including the container image, environment variables, and resource limits. Here’s the deployment mainifest for nest-one:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nest-one
spec:
  replicas: 1
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      app: nest-one
  template:
    metadata:
      labels:
        app: nest-one
    spec:
      containers:
        - name: nest-one
          image: nest-one
          ports:
            - containerPort: 3000
          resources:
            limits:
              memory: 512Mi
              cpu: "1"
            requests:
              memory: 256Mi
              cpu: "0.5"

Service

Each Service manifest exposes your Deployment internally within the cluster, allowing other services to communicate with it. Here’s the service manifest for nest-one:

apiVersion: v1
kind: Service
metadata:
  name: nestone-srv
spec:
  selector:
    app: nest-one
  ports:
    - targetPort: 3000
      name: http
      port: 8000

Ingress

If you want to expose your services externally (e.g., via HTTP), you can define an Ingress resource:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
  name: myingress
spec:
  ingressClassName: nginx
  rules:
  - host: localhost
    http:
      paths:
      - backend:
          service:
            name: nestone-srv
            port:
              number: 8000
        path: /nestone
        pathType: Prefix
      - backend:
          service:
            name: nesttwo-srv
            port:
              number: 8000
        path: /nesttwo
        pathType: Prefix
  defaultBackend:
    service:
      name: nestone-srv
      port:
        number: 8000

• Make sure you’ve deployed an NGINX Ingress Controller before applying your Ingress resource.

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

helm repo update

helm install nginx-ingress ingress-nginx/ingress-nginx

Proceed to bootstrapping Skaffold and attach the VS Code debugger in the next section.

Bootstrap Skaffold & Attach the VS Code Debugger

The Google Cloud Code extension for VS Code leverages Skaffold under the hood — when you start a Kubernetes debug session, it builds your images, deploys them, and sets up port-forwards automatically.

Configure Skaffold

apiVersion: skaffold/v4beta11
kind: Config
metadata:
  name: nestjs-k8s-debugging
build:
  artifacts:
    - image: nest-one
      context: nest-one
      docker:
        dockerfile: Dockerfile
        target: debug
    - image: nest-two
      context: nest-two
      docker:
        dockerfile: Dockerfile
        target: debug
manifests:
  rawYaml:
    - k8s/ingress.yaml
    - k8s/nest-one-deployment.yaml
    - k8s/nest-one-service.yaml
    - k8s/nest-two-deployment.yaml
    - k8s/nest-two-service.yaml

Debug with Google Cloud Code in VS Code

• Install the Cloud Code extension.

• Open Command Palette with Ctrl+Shift+P and select “Cloud Code: Debug on Kubernetes”

• Cloud Code will:

• Build your Docker images using Skaffold.

• Deploy the Kubernetes manifests to your local cluster.

• Set up port-forwarding for the debug ports (9229).

• Attach the VS Code debugger to the running pods.

You’ll see logs like:

Port forwarding service/nestone-srv in namespace default, remote port 8000 -> http://127.0.0.1:8001

Port forwarding service/nesttwo-srv in namespace default, remote port 8000 -> http://127.0.0.1:8000

Port forwarding pod/nest-one-bc985d76b-h9rk7 in namespace default, remote port 9229 -> http://127.0.0.1:9229

Port forwarding pod/nest-two-c6b76cfb5-fwvtx in namespace default, remote port 9229 -> http://127.0.0.1:9230

Exercise Breakpoints

• Place breakpoints in the services.

• In your browser, make requests to the following URLs to trigger the breakpoints:

• http://localhost/nestone

• http://localhost/nesttwo

• The execution will pause at the breakpoints, allowing you to inspect the state of the application.

For more information, visit the repository: https://github.com/pkhafizov/nestjs-k8s-debugging