DEV Community

Cover image for Build Once, Deploy Everywhere: Deploying a .NET 8 API with Docker, AKS & GitHub Actions
Ibrahim Bio Abubakar
Ibrahim Bio Abubakar

Posted on

Build Once, Deploy Everywhere: Deploying a .NET 8 API with Docker, AKS & GitHub Actions

#docker #kubernetes #azure #githubactions

Cloud-native development can feel overwhelming at first—containers, Kubernetes, CI/CD pipelines, cloud providers, etc. This tutorial walks you step by step from writing a simple .NET 8 Web API to deploying it on Azure Kubernetes Service (AKS) with a fully automated GitHub Actions CI/CD pipeline.

We’ll go beyond just writing code. You’ll also learn how and why each tool fits into the bigger cloud-native picture.

Learning Objective

By completing this tutorial, you will master:

  • Building production-ready .NET 8 Web APIs

  • Containerizing applications with Docker

  • Deploying to Azure Kubernetes Service (AKS)

  • Setting up CI/CD pipelines with GitHub Actions

  • Applying cloud-native development best practices

Project Overview

We’ll build a Weather Forecast API and deploy it to the cloud.

  • Backend → .NET 8 Web API

  • Containerization → Docker

  • Cloud Platform → Azure Kubernetes Service (AKS)

  • Automation → GitHub Actions for CI/CD

Prerequisites

Required Software

Install these tools (in order):

Visual Studio Code

.NET 8 SDK

Git

Docker Desktop

⚠️ Remember: Start Docker Desktop after installation

Azure CLI

kubectl

GitHub CLI (optional)

Required Accounts

GitHub(free)

Azure (free tier with $200 credits)

Verify Installation

Run the following commands in your terminal:

dotnet --version # Shows installed .NET SDK version (should be 8.x.x) git --version # Confirms Git is installed docker --version # Confirms Docker CLI works az --version # Shows Azure CLI version kubectl version --client # Verifies kubectl client
Enter fullscreen mode Exit fullscreen mode

Note: If any fail → reinstall that tool.

Image 1

💻 Step 1: Create the .NET Application

1.1 Set Up Project Structure

mkdir weather-app-demo # Create root project folder cd weather-app-demo mkdir WeatherApp # Create app folder cd WeatherApp
Enter fullscreen mode Exit fullscreen mode

Why? → Organizing code and infra configs in separate folders makes CI/CD pipelines easier to manage.

Image 2

1.2 Initialize .NET Project

dotnet new webapi -minimal
Enter fullscreen mode Exit fullscreen mode

dotnet new → Creates a new project

webapi → Template for REST APIs

-minimal → Uses the simplified .NET 8 minimal API syntax (less boilerplate)

Image 3

1.3 Add Dependencies

dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks
Enter fullscreen mode Exit fullscreen mode

HealthChecks → Adds endpoints for monitoring app health (Kubernetes probes rely on this).

Image 4

dotnet add package Swashbuckle.AspNetCore
Enter fullscreen mode Exit fullscreen mode

Swashbuckle.AspNetCore → Generates Swagger/OpenAPI docs automatically.

Image 5

1.4 Application Code

Replace the content Program.cs with:

var builder = WebApplication.CreateBuilder(args); // Register services builder.Services.AddHealthChecks(); // Adds /health endpoint builder.Services.AddEndpointsApiExplorer(); // Enables endpoint discovery for Swagger builder.Services.AddSwaggerGen(); // Generates Swagger UI // Configure Kestrel to listen on port 8080 (important for containers) builder.WebHost.ConfigureKestrel(options => { options.ListenAnyIP(8080); // Allows traffic from any network interface }); var app = builder.Build(); // Enable Swagger UI in Dev & Prod if (app.Environment.IsDevelopment() || app.Environment.IsProduction()) { app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "Weather API v1"); c.RoutePrefix = "swagger"; // URL: /swagger }); } // Welcome endpoint app.MapGet("/", () => new { Message = "Welcome to the Weather App!", Version = "1.0.0", Environment = app.Environment.EnvironmentName, Timestamp = DateTime.UtcNow }) .WithName("GetWelcome") .WithTags("General"); // Weather forecast endpoint app.MapGet("/weather", () => { var summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; var forecast = Enumerable.Range(1, 5).Select(index => new { Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), // Next 5 days TemperatureC = Random.Shared.Next(-20, 55), // Random °C TemperatureF = 0, // Placeholder Summary = summaries[Random.Shared.Next(summaries.Length)] }) .Select(temp => new { temp.Date, temp.TemperatureC, TemperatureF = 32 + (int)(temp.TemperatureC / 0.5556), // Formula °C → °F temp.Summary }); return forecast; }) .WithName("GetWeatherForecast") .WithTags("Weather"); // Health check endpoint (important for Kubernetes probes) app.MapHealthChecks("/health") .WithTags("Health"); app.Run(); // Starts the web server
Enter fullscreen mode Exit fullscreen mode

Concepts Explained:

  • Minimal APIs → Introduced in .NET 6, let you build APIs with fewer lines.

  • Swagger → Auto-generates interactive API docs.

  • Probes → Kubernetes uses health endpoints to restart/retry containers when needed.

1.5 Test Locally

dotnet run
Enter fullscreen mode Exit fullscreen mode

Image 5

Test endpoints in browser or with curl in the terminal:

http://localhost:8080/ → Welcome message

http://localhost:8080/weather → Forecast data

http://localhost:8080/swagger → Swagger docs

http://localhost:8080/health → Health check

Below is the Weather App on a browser:

Image z

Stop the app with Ctrl + C.

🐳 Step 2: Containerize Your Application with Docker

We’ll package the .NET app into a Docker container so it can run consistently anywhere.

2.1 Create Dockerfile

Create a file named Dockerfile inside WeatherApp/ directory:

touch Dockerfile
Enter fullscreen mode Exit fullscreen mode

Image 6

Add the content below to the Dockerfilecreated:

# Multi-stage build for optimized image size # Runtime stage FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base WORKDIR /app EXPOSE 8080 ENV ASPNETCORE_URLS=http://+:8080 ENV ASPNETCORE_ENVIRONMENT=Production # Build stage FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build ARG BUILD_CONFIGURATION=Release WORKDIR /src # Copy project file and restore dependencies COPY ["WeatherApp/WeatherApp.csproj", "."] RUN dotnet restore "WeatherApp.csproj" # Copy source code and build COPY . . WORKDIR /src COPY WeatherApp/ ./WeatherApp/ WORKDIR /src/WeatherApp RUN dotnet restore "WeatherApp.csproj" RUN dotnet build "WeatherApp.csproj" -c $BUILD_CONFIGURATION -o /app/build # Publish stage FROM build AS publish ARG BUILD_CONFIGURATION=Release RUN dotnet publish "WeatherApp.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false # Final stage FROM base AS final WORKDIR /app COPY --from=publish /app/publish . ENTRYPOINT ["dotnet", "WeatherApp.dll"]
Enter fullscreen mode Exit fullscreen mode

Concept: Multi-stage builds → build and runtime environments are separate. This keeps the final image small and secure.

2.2 Create .dockerignore

Prevent unnecessary files from bloating your image:

touch .dockerignore
Enter fullscreen mode Exit fullscreen mode

Image 7

Add the content below to the Dockerfilecreated:

 # Build outputs bin/ obj/ out/ # IDE files .vs/ .vscode/ *.user *.suo # OS files .DS_Store Thumbs.db # Git .git/ .gitignore # Docs README.md *.md # Docker Dockerfile* .dockerignore # Logs *.log logs/
Enter fullscreen mode Exit fullscreen mode

2.3 Build & Test Container

# Build image docker build -t weather-app:local . # Ensure your Docker Desktop is running before you run this command
Enter fullscreen mode Exit fullscreen mode

Image 8

Below is the built WeatherApp image in Docker Desktop app:

Image 9

Now let's run the container:

# Run container docker run -d -p 8080:8080 --name weather-test weather-app:local
Enter fullscreen mode Exit fullscreen mode

Image 10

Test the running app using curl in the terminal:

# Test endpoints curl http://localhost:8080/ curl http://localhost:8080/weather
Enter fullscreen mode Exit fullscreen mode

Image 11

# Clean up docker stop weather-test docker rm weather-test
Enter fullscreen mode Exit fullscreen mode

Image 12

Concept: Containers make your app portable — works the same on your laptop and in the cloud.

Step 3: Set Up Azure Infrastructure

We’ll use Azure CLI to provision resources.

3.1 Login to Azure

az login #Opens browser for Azure sign-in.
Enter fullscreen mode Exit fullscreen mode

3.2 Select Subscription

az account list --output table # See subscriptions az account set --subscription "Your-Subscription-Name"
Enter fullscreen mode Exit fullscreen mode

3.3 Create Resource Group

az group create --name student-demo --location eastus
Enter fullscreen mode Exit fullscreen mode

Image 14

Concept: A resource group is a logical container for all your Azure resources.

3.4 Create Container Registry (ACR)

az acr create --resource-group student-demo --name studentdemo2042acr --sku Basic
Enter fullscreen mode Exit fullscreen mode

Image 15

Concept: ACR = private Docker Hub inside Azure.

3.5 Build & Push Image

az acr build --registry studentdemo2042acr --image weather-app:latest .
Enter fullscreen mode Exit fullscreen mode

Image 16

Why ACR build? → Azure builds inside the cloud, avoiding OS/CPU compatibility issues.

3.6 Create AKS Cluster

az aks create \ --resource-group student-demo \ --name student-aks-cluster \ --node-count 1 \ --node-vm-size Standard_B2s \ --attach-acr studentdemo2042acr \ --enable-managed-identity \ --generate-ssh-keys
Enter fullscreen mode Exit fullscreen mode

Image 17

📌 Concept:

  • AKS = Azure-managed Kubernetes cluster

  • attach-acr → avoids ImagePullBackOff errors by linking AKS to ACR automatically

3.7 Connect to Cluster

az aks get-credentials \ --resource-group student-demo \ --name student-aks-cluster
Enter fullscreen mode Exit fullscreen mode

Image 18

kubectl get nodes # Verify cluster connection
Enter fullscreen mode Exit fullscreen mode

Image 19

☸️ Step 4: Deploy with Kubernetes

Kubernetes uses YAML manifests to declare your app’s state.

cd .. # Back to weather-app-demo folder mkdir k8s cd k8s touch deployment.yaml
Enter fullscreen mode Exit fullscreen mode

Image 20

4.1 Create Deployment

Copy and paste the content below in k8s/deployment.yaml

 apiVersion: apps/v1 kind: Deployment metadata: name: weather-app labels: app: weather-app version: v1 spec: replicas: 2 # Run 2 pods for high availability selector: matchLabels: app: weather-app template: metadata: labels: app: weather-app version: v1 spec: containers: - name: weather-app image: studentdemo2024acr.azurecr.io/weather-app:latest imagePullPolicy: Always ports: - containerPort: 8080 env: - name: ASPNETCORE_ENVIRONMENT value: "Production" resources: # Resource requests & limits requests: memory: "128Mi" cpu: "100m" limits: memory: "512Mi" cpu: "500m" # Probes for self-healing livenessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 30 readinessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 10
Enter fullscreen mode Exit fullscreen mode

📌 Concepts:

  • Deployment → ensures the desired # of pods run.

  • Probes → tell Kubernetes when a pod is healthy or ready.

4.2 Create Service

Create k8s/service.yaml file

touch service.yaml
Enter fullscreen mode Exit fullscreen mode

Image 22

Copy and paste the content below in k8s/service.yaml

apiVersion: v1 kind: Service metadata: name: weather-app-service spec: type: LoadBalancer # Exposes app to internet selector: app: weather-app ports: - port: 80 # External port targetPort: 8080 # Maps to container
Enter fullscreen mode Exit fullscreen mode

📌 Concept: A Service gives your pods a stable IP address + load balancing.

4.3 Deploy

# Apply Kubernetes manifests kubectl apply -f deployment.yaml kubectl apply -f service.yaml
Enter fullscreen mode Exit fullscreen mode

Image 23

# Check deployment status kubectl get deployments kubectl get pods
Enter fullscreen mode Exit fullscreen mode

Image 24

# Check deployment status kubectl get services
Enter fullscreen mode Exit fullscreen mode

Image 25

🔄 Step 5: GitHub Actions CI/CD

We’ll automate build → push → deploy.

5.1 Init Git

cd .. # Back to weather-app-demo folder # Initialize Git repository git init git add . git commit -m "Initial commit: Weather App"
Enter fullscreen mode Exit fullscreen mode

Image 26

5.2 Create Service Principal

# Get your subscription ID SUBSCRIPTION_ID=$(az account show --query id --output tsv) echo "Subscription ID: $SUBSCRIPTION_ID" # Create service principal with contributor role az ad sp create-for-rbac \ --name "weather-app-github-sp" \ --role contributor \ --scopes /subscriptions/$SUBSCRIPTION_ID/resourceGroups/student-demo \ --sdk-auth
Enter fullscreen mode Exit fullscreen mode

Image 27

Save JSON output → add as GitHub Secret AZURE_CREDENTIALS.

5.3 Create GitHub Repo

gh auth login # Follow the prompts
Enter fullscreen mode Exit fullscreen mode

Image 28

Image 29

# Create GitHub repository (using GitHub CLI) and Push to Repo gh repo create weather-app-demo --public --source=. --push
Enter fullscreen mode Exit fullscreen mode

Alternative: Create the repository manually on GitHub.com and push your code.

Image 30

Image 31

5.4 Configure GitHub Secrets

Use JSON output from step 5.2

gh secret set AZURE_CREDENTIALS -b'PASTE_JSON_HERE'
Enter fullscreen mode Exit fullscreen mode

Image 32

gh secret set ACR_NAME -b"studentdemo2042acr"
Enter fullscreen mode Exit fullscreen mode

Image 33

gh secret set RESOURCE_GROUP -b"student-demo"
Enter fullscreen mode Exit fullscreen mode

Image 34

gh secret set CLUSTER_NAME -b"student-aks-cluster"
Enter fullscreen mode Exit fullscreen mode

Image 35

5.5 Create a GitHub Workflow

Create the workflow directory and file:

 mkdir -p .github/workflows touch .github/workflows/deploy.yml
Enter fullscreen mode Exit fullscreen mode

Copy and paste the content below in .github/workflows/deploy.yml file.

name: Build and Deploy to AKS on: push: branches: [ main ] pull_request: branches: [ main ] env: IMAGE_NAME: weather-app jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup .NET uses: actions/setup-dotnet@v3 with: dotnet-version: '9.0.x' - name: Restore dependencies run: dotnet restore WeatherApp/WeatherAPP.csproj - name: Build application run: dotnet build WeatherApp/WeatherAPP.csproj --configuration Release --no-restore - name: Run tests run: dotnet test WeatherApp/WeatherAPP.csproj --no-build --verbosity normal || true - name: Azure Login uses: azure/login@v1 with: creds: ${{ secrets.AZURE_CREDENTIALS }} - name: Setup Azure CLI uses: azure/cli@v2 with: inlineScript: echo "Azure CLI setup complete" - name: Build and push Docker image to ACR run: | IMAGE_TAG=${{ secrets.ACR_NAME }}.azurecr.io/${{ env.IMAGE_NAME }}:${{ github.sha }} az acr build \ --registry ${{ secrets.ACR_NAME }} \ --image ${{ env.IMAGE_NAME }}:${{ github.sha }} \ --file WeatherApp/Dockerfile \ . echo "IMAGE_TAG=$IMAGE_TAG" >> $GITHUB_ENV - name: Deploy to AKS if: github.ref == 'refs/heads/main' run: | echo "Checking if AKS cluster exists..." if ! az aks show --resource-group "${{ secrets.RESOURCE_GROUP }}" --name "${{ secrets.CLUSTER_NAME }}" --output table; then echo "ERROR: AKS cluster '${{ secrets.CLUSTER_NAME }}' not found in resource group '${{ secrets.RESOURCE_GROUP }}'" exit 1 fi echo "Getting AKS credentials..." az aks get-credentials \ --resource-group ${{ secrets.RESOURCE_GROUP }} \ --name ${{ secrets.CLUSTER_NAME }} \ --overwrite-existing echo "Testing kubectl connection..." kubectl cluster-info echo "Updating deployment with image: ${{ env.IMAGE_TAG }}" kubectl set image deployment/weather-app \ weather-app=${{ env.IMAGE_TAG }} echo "Waiting for rollout to complete..." kubectl rollout status deployment/weather-app --timeout=600s echo "Deployment status:" kubectl get pods -l app=weather-app kubectl get service weather-app-service
Enter fullscreen mode Exit fullscreen mode

📌 Concept:

  • GitHub Actions → automates the whole pipeline.

  • Every push to main → build → push image → deploy to AKS.

5.6 Deploy Your Application

git add . git commit -m "Add GitHub Actions CI/CD pipeline" git push origin main
Enter fullscreen mode Exit fullscreen mode

Image 35

Monitor the deployment:

  • Go to your GitHub repository
  • Click the Actions tab
  • Watch your workflow run in real-time

Image 36

🌐 Step 6: Access Your Deployed App

6.1 Get External IP Address

# Check service status kubectl get service weather-app-service
Enter fullscreen mode Exit fullscreen mode

Image 38

# Wait for EXTERNAL-IP (may take 2-5 minutes) kubectl get service weather-app-service --watch
Enter fullscreen mode Exit fullscreen mode

Wait until EXTERNAL-IP is assigned. Then test:

# Test the endpoints curl http://YOUR-EXTERNAL-IP/ curl http://YOUR-EXTERNAL-IP/weather curl http://YOUR-EXTERNAL-IP/health
Enter fullscreen mode Exit fullscreen mode

Image 40////

# Or open in browser open http://YOUR-EXTERNAL-IP/swagger # macOS start http://YOUR-EXTERNAL-IP/swagger # Windows
Enter fullscreen mode Exit fullscreen mode

Image 41

🔄 Step 7: Test Continuous Deployment

  1. Edit Program.cs welcome message. 
app.MapGet("/", () => new { Message = "Welcome to the Updated Weather App! 🌤️", Version = "1.1.0", Environment = app.Environment.EnvironmentName, Timestamp = DateTime.UtcNow, DeployedBy = "GitHub Actions" })
Enter fullscreen mode Exit fullscreen mode
  1. Commit & push: 
git add . git commit -m "Update welcome message" git push origin main
Enter fullscreen mode Exit fullscreen mode
  1. GitHub Actions will rebuild & redeploy automatically.

Image 42

  1. Test again → you should see your new message. 
curl http://YOUR-EXTERNAL-IP/
Enter fullscreen mode Exit fullscreen mode

Image 43

Conclusion

You’ve just taken a local .NET 8 Web API and transformed it into a cloud-native application running on Azure Kubernetes Service, packaged with Docker, and automated with a GitHub Actions CI/CD pipeline. That’s the full lifecycle of modern cloud development — from writing code → to shipping containers → to running resilient workloads in production.

The best part? You now have a repeatable blueprint you can apply to almost any project:

Swap the Weather API with your own service

Reuse the Docker + Kubernetes setup

Extend your GitHub workflow for tests, security scans, or staging environments

This isn’t just about building an app — it’s about learning how to ship production-ready software at scale.

Keep experimenting: add monitoring, autoscaling, or connect a database. The cloud-native journey is iterative, but now you’ve got the foundations locked in.

Top comments (0)