XenonStack

DevOps

XenonStack Blog Deploy ASP.NET Core on Kubernetes: A Practical Guide

and | Published | Updated

Key takeaway

  • Step-by-step guide to deploy ASP.NET Core on Kubernetes: multi-stage Dockerfile, registry push, Deployment and Service files, checks and troubleshooting.

To deploy an ASP.NET Core application on Kubernetes, you package it as a container image with a multi-stage Dockerfile, push the image to a registry, describe it in a Deployment and a Service manifest, and apply both with kubectl. The same steps work on a local cluster such as Minikube and on a managed service such as Azure Kubernetes Service.

This guide uses the current Microsoft Dockerfile pattern, shows what a production-minded Deployment needs, and ends with the checks an engineering lead should ask for before a release. For the wider delivery process, read our guides to DevOps processes and the continuous delivery pipeline.

What do you need before you start?

You need five things in place. None of them is exotic, but each one is a common source of failed first deployments.

RequirementWhat it is forNotes
A Kubernetes clusterRuns the containersMinikube for a laptop test, a managed cluster for shared environments. See the Kubernetes Deployment documentation.
kubectlApplies manifests and inspects the clusterkubectl reference
A supported .NET versionReceives security and bug fixesCheck the .NET support policy before you pick a base image.
Docker or another image builderBuilds the container imageThe Dockerfile below follows Microsoft Learn.
A container registryStores the image so the cluster can pull itDocker Hub, Azure Container Registry or Amazon ECR all work.

Which .NET version should you target?

Target a version that is still supported. According to the Microsoft .NET support policy page (read on 13 November 2026), it lists .NET 10 as a long-term support release with end of support on 14 November 2028, and .NET 11 as a standard-term support release, released on 10 November 2026, also with end of support on 14 November 2028. The page lists no other versions as supported, so if your application still targets an older .NET release, plan the upgrade before you containerise it. Confirm the current dates on the official page, because they can change.

How do you write a Dockerfile for ASP.NET Core?

Use a multi-stage build. The first stage uses the SDK image to restore and publish the app. The final stage uses the smaller ASP.NET runtime image and copies in only the published output. This is the pattern Microsoft Learn shows for .NET 10 (the project and folder names are Microsoft's sample names, so replace them with yours).

Two-column diagram. Stages Build, Publish, Declare and Apply on the left, each paired on the right with its artefact and check, ending in a versioned, rollback-ready release.
# https://hub.docker.com/_/microsoft-dotnet
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /source

# copy csproj and restore as distinct layers
COPY *.sln .
COPY aspnetapp/*.csproj ./aspnetapp/
RUN dotnet restore

# copy everything else and build app
COPY aspnetapp/. ./aspnetapp/
WORKDIR /source/aspnetapp
RUN dotnet publish -c release -o /app --no-restore

# final stage/image
FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app ./
ENTRYPOINT ["dotnet", "aspnetapp.dll"]

What port does the container listen on?

The current Microsoft sample runs the container with -p <port>:8080, which maps a local port to port 8080 in the container. The sample for older .NET versions on the same page maps to port 80 instead. Check which port your image uses before you write the Service, because a wrong targetPort is the most common reason a healthy Pod returns nothing.

How do you build and test the image locally?

docker build -t aspnetapp .
docker run -it --rm -p 8080:8080 --name aspnetcore_sample aspnetapp

Open http://localhost:8080 in a browser. If it responds, the image is ready to publish.

How do you publish the image to a container registry?

Tag the image with the registry host name and a version tag, then push it. Use a fixed version tag rather than latest, so that every Deployment points to a known build and a rollback means something. The example uses Azure Container Registry, and the registry name is a placeholder.

docker tag aspnetapp myregistry.azurecr.io/aspnetapp:1.0.0
docker push myregistry.azurecr.io/aspnetapp:1.0.0

Pushing to Docker Hub or Amazon ECR follows the same tag-and-push pattern with a different host name and login step. The cluster also needs permission to pull from a private registry, which you configure with an image pull secret or the managed cluster's registry integration. Follow your registry's own documentation for that step.

How do you create the Kubernetes Deployment and Service files?

A Deployment keeps the desired number of Pods running and handles rolling updates. A Service gives those Pods one stable address. Save the two manifests below as aspnetapp.deployment.yml and aspnetapp.service.yml. They are illustrative: replace the image, names, port and probe path with your own.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aspnetapp
  template:
    metadata:
      labels:
        app: aspnetapp
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:1.0.0
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            memory: 256Mi
apiVersion: v1
kind: Service
metadata:
  name: aspnetapp
spec:
  type: NodePort
  selector:
    app: aspnetapp
  ports:
  - port: 80
    targetPort: 8080

The readiness probe assumes your application exposes a health endpoint at /healthz. Add one before you rely on the probe, or change the path to an endpoint that exists. Resource requests and limits are starting values, not recommendations, so measure your own workload.

How do you run the application on Kubernetes?

Apply both files, then wait for the rollout to finish. You can also use the Kubernetes Dashboard, but the command line is easier to repeat in a pipeline.

kubectl apply -f aspnetapp.deployment.yml
kubectl apply -f aspnetapp.service.yml
kubectl rollout status deployment/aspnetapp

How do you verify the deployment?

kubectl get pods -l app=aspnetapp
kubectl get service aspnetapp

The Pods should show a Running status and be ready. The Service output shows the port the cluster assigned to the NodePort.

How do you test the application?

The quickest check works on any cluster: forward a local port to the Service.

kubectl port-forward service/aspnetapp 8080:80

Then open http://localhost:8080. On Minikube you can also use the node address and the NodePort shown by kubectl get service. The NodePort range is a cluster setting, so confirm it on the Kubernetes Service documentation rather than assuming a number. On a managed cloud cluster, a Service of type LoadBalancer or an ingress controller is the usual way to reach the app from outside.

How do you troubleshoot a failing deployment?

SymptomLikely causeFirst command
Pod stuck in ImagePullBackOffWrong image name or tag, or no pull permission on the registrykubectl describe pod <pod>
Pod restarts repeatedlyThe application crashes on start, often a missing settingkubectl logs <pod> --previous
Pod is Running but not ReadyThe readiness probe path or port is wrongkubectl describe pod <pod>
Service returns no responseSelector does not match the Pod labels, or targetPort is wrongkubectl get endpoints aspnetapp

What should leaders check before this goes to production?

A working demo is not a production release. Ask your platform and engineering teams to confirm the points below.

AreaWhat to confirm
VersioningImages use fixed tags, and the team can roll back with kubectl rollout undo.
Supported runtimeThe base image uses a .NET version that is still in support.
Configuration and secretsSettings come from ConfigMaps and Secrets, not from the image.
DeliveryBuilds and applies run from a pipeline, for example Jenkins on Kubernetes or Azure DevOps, not from a laptop.
PackagingTeams that manage many manifests consider Helm.
Cluster basicsThe team understands the Kubernetes architecture components it runs on.

When is this not the right approach?

A single small internal app with light traffic may not justify running a cluster. A managed platform that runs containers for you can be simpler, and the Deployment steps above still apply if you move later. Kubernetes earns its cost when you run many services, need rolling updates and self-healing, or want one deployment model across teams.

How does this fit agentic AI and governed delivery?

Teams that add AI agents to .NET services need the same discipline: versioned images, declared configuration and an audit trail for changes. ElixirClaw is an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control. For agile and DevOps delivery work, AgentScrum is one of the ElixirClaw sites. ElixirData keeps governed context, versioned policy and decision traces in one decision layer above AI agents.

To map one release decision your agents should make, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop.

Frequently asked questions

Can I run ASP.NET Core on Kubernetes?

Yes. You build the app into a container image, push it to a registry and describe it in Deployment and Service manifests. Kubernetes then runs and manages the Pods.

Which .NET version should I use?

One that is supported. The Microsoft .NET support policy page lists .NET 10 (long-term support) and .NET 11 (standard-term support) as supported, both with end of support on 14 November 2028. Confirm on the official page before you choose.

Which port should the container expose?

The current Microsoft Learn sample maps to port 8080 in the container, while the samples for older .NET versions map to port 80. Match the Service targetPort to the port your image actually uses.

How do I roll back a bad release?

Use fixed image tags and run kubectl rollout undo deployment/aspnetapp, which returns the Deployment to its previous revision.

Do I need a registry?

Yes, for any cluster that cannot read your local Docker images. Docker Hub, Azure Container Registry and Amazon ECR are common choices, and the cluster needs permission to pull from a private one.

Follow XenonStack on LinkedIn: XenonStack on LinkedIn for new guides on agentic AI, data and platform engineering.

Table of Contents

navdeep-singh-gill

Navdeep Singh Gill

Global CEO and Founder of XenonStack

LinkedIn profile

Navdeep Singh Gill is serving as Chief Executive Officer and Product Architect at XenonStack. He holds expertise in building SaaS Platform for Decentralised Big Data management and Governance, AI Marketplace for Operationalising and Scaling. His incredible experience in AI Technologies and Big Data Engineering thrills him to write about different use cases and its approach to solutions.

Get the latest articles in your inbox

Subscribe Now

Interested in Solving your Challenges with XenonStack Team
Get Started

Get Started with your requirements and primary focus, that will help us to make your solution

Please Select your Industry
Banking
Fintech
Payment Providers
Wealth Management
Discrete Manufacturing
Semiconductor
Machinery Manufacturing / Automation
Appliances / Electrical / Electronics
Elevator Manufacturing
Defense & Space Manufacturing
Computers & Electronics / Industrial Machinery
Motor Vehicle Manufacturing
Food and Beverages
Distillery & Wines
Beverages
Shipping
Logistics
Mobility (EV / Public Transport)
Energy & Utilities
Hospitality
Digital Gaming Platforms
SportsTech with AI
Public Safety - Explosives
Public Safety - Firefighting
Public Safety - Surveillance
Public Safety - Others
Media Platforms
City Operations
Airlines & Aviation
Defense Warfare & Drones
Robotics Engineering
Drones Manufacturing
AI Labs for Colleges
AI MSP / Quantum / AGI Institutes
Retail Apparel and Fashion

Proceed Next