From .NET Core API to Containerised APIs with Docker & Kubernetes

mdbhowmik
Sep 3
2 min read

So, you’ve built a shiny new .NET Core API. It runs fine on your machine, but then the dreaded question pops up:

“But… will it work on the server?”

We’ve all been there. Different environments, missing dependencies, and the classic “it works on my machine”headache. That’s where containerisation comes in. With Docker, you can package your API into a neat, portable container that runs anywhere. And when you’re ready to scale? Kubernetes has your back.

In this post, we’ll walk through taking a .NET Core Web API, containerising it with Docker, testing it locally, and even touching Kubernetes for deployment.

Step 1: Prep Your .NET Core API

Before we containerise, make sure your API runs locally with:

dotnet run

Also, follow these good practices:

Use environment variables (instead of hardcoded configs).
Add a simple health endpoint like /health for monitoring.
Ensure logging goes to stdout/stderr (Docker will capture it).

Step 2: Write a Dockerfile

Inside your API project folder, create a file called Dockerfile:

# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src

COPY *.csproj ./
RUN dotnet restore

COPY . .
RUN dotnet publish -c Release -o /app

# Stage 2: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime
WORKDIR /app

COPY --from=build /app .
ENTRYPOINT ["dotnet", "YourApi.dll"]

What’s happening here?

First stage (sdk): Builds and publishes your app.
Second stage (aspnet): Runs your app in a lightweight runtime image.

This makes your container smaller and faster.

Step 3: Build & Run the Container

Build your image:

docker build -t my-dotnet-api .

Run it:

docker run -d -p 8080:80 --name myapi my-dotnet-api

Check http://localhost:8080 and your API is running inside Docker.

Step 4: Use Docker Compose for Multi-Service Apps

Most real apps need more than just an API — think databases, queues, or caches. That’s where Docker Compose saves the day.

Create a docker-compose.yml:

version: '3.9'
services:
  api:
    build: .
    ports:
      - "8080:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Server=db;Database=mydb;User=sa;Password=Pass@123;
    depends_on:
      - db

  db:
    image: mcr.microsoft.com/mssql/server:2019-latest
    environment:
      SA_PASSWORD: "Pass@123"
      ACCEPT_EULA: "Y"
    ports:
      - "1433:1433"

Run everything with:

docker-compose up --build

Now you’ve got an API and a database running together.

Step 5: Deploy with Kubernetes

When you’re ready to scale beyond your laptop, Kubernetes (K8s) is the way to go.

A simple deployment (deployment.yaml):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dotnet-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: dotnet-api
  template:
    metadata:
      labels:
        app: dotnet-api
    spec:
      containers:
        - name: dotnet-api
          image: my-dotnet-api:latest
          ports:
            - containerPort: 80

Apply it:

kubectl apply -f deployment.yaml

Now your API is replicated, load-balanced, and resilient.

Best Practices

Use multi-stage builds → keeps images lean.
Stick to environment variables for configs.
Add /health and /ready endpoints for monitoring.
Centralise logs → stdout/stderr (K8s/Docker pick them up).
Automate builds with GitHub Actions, Azure DevOps, or GitLab CI.

Wrap Up

Yes, you just turned a plain .NET Core API into a containerised, production-ready service.

Docker gives you consistency.
Compose lets you orchestrate local dev environments.
Kubernetes lets you scale to the cloud.

The best part? Once you’ve written that Dockerfile, your API will run anywhere: your laptop, a VM, Azure Kubernetes Service (AKS), AWS EKS, or even on-prem servers.