Hi Devs and Divas.
Today I am going to show you a simple way to install run and test your API locally with docker caontainer and orchestrating with Kubernetes.
If you ever heard that Kubernetes is super difficult, don't worry, it's not that bad.
In this article you will learn how to deploys a simple API to kubernetes with a local environment:
- Preparing the API
- Publishing API in Docker Hub
- Installing Kind for Kubernetes
- Preparing the API for Kubernetes
- Pushing and Managing API to Kubernetes
Pre-requirements
You should have the basic concept knowledge of:
- Kubernetes
- Docker/Containers
- Kind for Kubernetes
- .net API
Preparing the API
We will create a basic Weatherforecast API that dotnet gives us.
Vs Code
- Open VS CODE, open a new terminal, navigate to the folder you wish to create your project for example (cd source/repos).
- Now type
dotnet new webapi -o "weather"
to create a sample webapi project. - Now open this project folder in the vscode.
To auto-create the Docker support that is available upon project creation in Visual Studio follow the next steps:
Install the
Docker
extension.Press
Ctrl + Shift + P
Type
Add Docker Files to Workspace
Select
.NET: ASP.NET Core
Select
Linux
Type the port you wish to expose
Select
No
for docker compose. At this first moment we won't need it.
Then you notice it generated a new Dockerfile
in your workspace.
Visual Studio
- Open visual studio and create a
ASPNET Core Web API
and make sure you enableDocker Support
.
Swagger Support
- After the project is created you go to Program.cs (.net 6 above) or to Startup.cs (.net 6 below) and remove the
IF condition
from the swagger setup From this:
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
Should look like this:
app.UseSwagger();
app.UseSwaggerUI();
We do this for testing purpose only, because when you push it to kubernetes you need to set which environment you wish to build your application. You can add ASPNETCORE_ENVIRONMENT=Development
in your docker profile, it will work as well.
Publishing API in Docker Hub
You must have Docker
installed and have a Docker hub Account
to complete this step.
In your IDE, open terminal and build the API:
docker build -t weather .
As a prevention measure, test your container before orchestrating with kubernetes. So lets run the image. (You can use whatever port you wish)
docker container run -d -p 8070:80 --name containername weather
Now you should be able to see swagger
page if you type localhost:8070/swagger
- Pushing to Docker Hub
Before pushing you can add tags to your image.
docker tag weather dockerHubUserName/weather
Now you can push it
docker push dockerHubUserName/weather
If you open your docker hub on your browser you should be able to see your image.
Installing Kind
To install kind
refer to original documentation https://kind.sigs.k8s.io/docs/user/quick-start/
But let me show you what I did.
- Download the file from https://kind.sigs.k8s.io/dl/v0.14.0/kind-windows-amd64
- Rename the file to
kind.exe
- Move it to a folder named
k8s
. So should look like thisC:\k8s\kind.exe
- On windows, go to environment variables and add new PATH
C:\k8s
- Now if you have
docker
running, you should be able to create a cluster.
kind create cluster
Wait till it creates the cluster.
You should see a new container running on your docker. To check if the container is running type docker ps
in your terminal and you should see a container named kind-control-plane
from the image kindest
.
To check if there are any clusters type on your terminal:
kind get clusters
And you should get a response like this:
kind
Preparing the API for Kubernetes
To access your application you need at least 2 kubernetes objects:
deploy.yml
- A Deployment provides declarative updates for Pods and ReplicaSets.
service.yml
- An abstract way to expose an application running on a set of Pods as a network service. To access your pod you need a service to expose it.
You don't need to know how to write it by hear, you can get a template and edit.
I recommend you use VsCode
with YAML extension
to edit your yml files, because it indentation is very delicate, and Visual Studio has no support for this extension.
This is a simplified version, for testing purpose, there are many options and features to be added according to your project
- Create a file in your project
weather-deploy.yml
Template:
apiVersion: apps/v1
kind: Deployment
metadata:
name: Application Name
spec:
replicas: How many Replicas?
template:
metadata:
labels:
app: Application Name
spec:
containers:
- name: Application Name
image: dockerHubUser/applicationName
selector:
matchLabels:
app: Application Name
Our project:
apiVersion: apps/v1
kind: Deployment
metadata:
name: weather
spec:
replicas: 2
template:
metadata:
labels:
app: weather
spec:
containers:
- name: weather
image: dockerHubUser/weather
selector:
matchLabels:
app: weather
Don't forget to add you docker hub User
- Create a file in your project
weather-service.yml
Template:
apiVersion: v1
kind: Service
metadata:
name: Project Name
spec:
selector:
app: Project Name
ports:
- port: port?
targetPort: 80 is the standart port
Our project:
apiVersion: v1
kind: Service
metadata:
name: weather
spec:
selector:
app: weather
ports:
- port: 8070
targetPort: 80
Pushing API to Kubernetes
To orchestrate the API to kubernetes pod we will only push this 2 files as the project will come from the docker image.
Terminal:
kubectl apply -f weather-deploy.yml
kubectl apply -f weather-service.yml
Terminal response should be:
deployment.apps/weather created
service/weather created
- Wait a minute and check if your pod and service are running:
Terminal:
kubectl get pods
Terminal:
kubectl get svc
Terminal response:
kubectl get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP xxxxx <none> 443/TCP 23h
weather ClusterIP xxxxx <none> 8070/TCP 3m53s
Accessing your Pod
To access your pod you need to forward a port to the service.
kubectl port-forward service/weather 8070:8070
Now you should be able to see the Swagger
page in your browser typing localhost:8070/swagger
Basically you are telling the kubernetes that when you access port 8070 locally, you will access 8070 on kubernetes service, which is our pod's service.
Top comments (1)
Great article! I think it will help people who are new to K8s and want to know more about it by following the walkthrough you described.