Scope: We'll be learning the basics of Kubernetes by locally hosting a toy Go server.
Start by cloning this repo
git clone https://github.com/dangbert/k8s-tutorial.git && cd k8s-tutorialNotice that ./backend/server.go implements a few API endpoints. To start, go ahead and run it locally like so:
cd backend/
go run server.go
# in another terminal hit the API endpoint
curl http://localhost:8000/fruitOr visit http://localhost:8000/fruit in your browser.
1. Setup Minikube
Minikube provides a pre-configured host ready to run kubernetes.
# start a kubernetes single node "cluster" (inside Docker)
minikube start --driver docker
# now ensure kubectl is pointed to minikube
kubectl config get-contexts
# you should see the following:
# CURRENT NAME CLUSTER AUTHINFO NAMESPACE
# * minikube minikube minikube defaultdocker build ./backend -t backend:latest
# now make the image available inside minikube
minikube image load backend:latest
# optionally you can test running the image locally
docker run -p 8000:8000 -t backendOur goal is to run server.go inside a pod, which is a thin abstraction around a container in Kubernetes.
Using the Kubernetes docs as a reference, we can describe our pod (in yaml) like so:
apiVersion: v1
kind: Pod
metadata:
name: backend
spec:
containers:
- name: backend
image: backend:latest
imagePullPolicy: Never # this is a local image
ports:
# indicate this pod shall expose port 8000
- containerPort: 8000Copy that into ./backend.yaml (in the root of this repository) then run:
# load our pod's definition into kubernetes
kubectl apply -f backend.yaml
# now you can check the status of the pod
kubetl get pods # repeat until status show "Running"
# and stream the pod's logs
kubectl logs -f pods/backendThe pod is currently only accessible inside the minikube host...
# so we can port forward to expose on localhost:8000
kubectl port-forward pods/backend 8000:8000
# OR alternatively get the IP of your pod (within minikube)
kubectl get pods/backend -o wide
# and curl the IP directly
minikube ssh curl http://10.XX.XX.XX9:8000/fruit
# for example
minikube ssh curl http://10.244.0.9:8000/fruitNote if you're having any trouble, you can see the solution for this step here.
So you've managed to run the application inside Kubernetes! But what if we wanted to have a DNS record making it easier to communicate with your pod?
For this we'll define a new Kubernetes resource called a service. A service groups one or more pods under a single static IP address (with a DNS name), which is also helpful for load balancing traffic.
- You can optionally see the docs here for more info.
Now update backend.yaml, appending to the bottom:
# (yaml from step 3 remains here)
---
apiVersion: v1
kind: Service
metadata:
name: backend-service
labels:
app: backend # we'll use this later
spec:
selector:
# find all pods with the label app=backend, and group under this service
app: backend
ports:
ports:
- protocol: TCP
port: 80 # port for the service itself to expose on its IP
targetPort: 8000 # must match the pod's `containerPort`# and now apply the changes
kubectl apply -f backend.yaml
# now check what IPs have been added to the service
# (the IP listed should match your pod from earlier)
kubectl get endpoints backend-service
#NAME ENDPOINTS AGE
#backend-service 10.244.0.9:8000 12mAnd now let's try to hit the service under the DNS name "backend-service". To do this we'll launch a temporary pod named "debug", containing tools like the curl command.
kubectl run debug --image=nicolaka/netshoot -it --rm --restart=Never -- sh
# ^this may take a while to pull the image, but you can always monitor the status in a new terminal:
watch -n 1 kubectl describe pods debug
# once the "debug" pod is launched run inside:
curl http://backend-service/fruit
# then use <ctrl>d to kill the pod
Note if you're having any trouble, you can see the solution for this step here.
Now what if you wanted to scale to 3 instances of the backend pod? For this we'll use the deployment resource. A deployment handles spawning pods (from a template), ensuring the desired "replica" count (e.g. 3) is always met.
- See the deployment docs for more info.
Modify backend.yaml again, this time DELETE the entire kind: pod section, then add this in its place:
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
labels:
app: backend
spec:
# indicate we'd prefer 3 instances of the pod
replicas: 3
selector:
matchLabels:
app: backend
# here we describe how our pods should be created
template:
# this part is identical to the pod we defined in step 3:
metadata:
name: backend
labels:
app: backend
spec:
containers:
- name: backend
image: backend:latest
imagePullPolicy: Never # this is a local image
ports:
# indicate this pod shall expose port 8000
- containerPort: 8000
# (definition of our service from step 4 continues below)
---
# ...# let's check on our existing pod
kubectl get pod
# and delete it
kubectl delete pod backend
# now apply, creating the "deployment" resource
kubectl apply -f backend.yamlOur deployment should immediately create three backend pods. Let's check:
kubectl get pods
# NAME READY STATUS RESTARTS AGE
# backend-5b664f9c6-284bv 1/1 Running 0 26s
# backend-5b664f9c6-fh856 1/1 Running 0 26s
# backend-5b664f9c6-xc7bk 1/1 Running 0 26s
# and we can stream the logs from all our backend pods at once
# (note that we can filter by the label app=backend here)
kubectl logs -l app=backend --prefix=true -f
# now in another terminal try to hit the backend-service
kubectl run debug --image=nicolaka/netshoot -it --rm --restart=Never -- curl http://backend-service/fruitObserve the logs as you hit the backend, and try hitting it a few times. You'll notice that a different pod may respond to the request each time.
Note if you're having any trouble, you can see the solution for this step here.
Consider the yaml configs (a.k.a. "manifests") we created in Part 1. How would we distribute them to the world if we wanted to let anyone run our backend in the same way? While we could just pass around the backend.yaml file, if our system was more complex with many microservices across many yaml files this could become less portable. Also what if we want to deploy our manifests slightly differently in our staging cluster vs production?
Enter Helm. Helm is a package manager for Kubernetes manifests, allowing pre-packaged resources called Charts (i.e. a set of deployments, services, etc) to be shared and quickly installed in any kubernetes cluster. It also let's you use templating to dynamically define your manifests, giving you levers to customize the behavior in different environents.
In this section we'll learn the basics of Helm by refactoring our work above into a simple helm chart.
- Explore the Helm docs for more information.
helm create demoNow you'll have the demo folder:
demo/
├── Chart.yaml
├── charts
├── templates
│ ├── NOTES.txt
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── hpa.yaml
│ ├── httproute.yaml
│ ├── ingress.yaml
│ ├── service.yaml
│ ├── serviceaccount.yaml
│ └── tests
│ └── test-connection.yamlBut let's refactor:
rm -rf demo/templates/*
# and move our backend.yaml into templates
mv backend.yaml demo/templates/Now you're folder structure will look like this
$ tree demo/
demo/
├── Chart.yaml
├── charts
├── templates
│ └── backend.yaml
└── values.yamlNow let's install our Helm "chart" inside Kubernetes.
# start by deleting your existing resources
kubectl delete deployment/backend service/backend-service
# and verifying they're gone
kubectl get all
# you should only see:
#NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
#service/kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 8m59s
# and let's install your helm chart
helm install demo ./demo/
# and verify your deployment and service were recreated:
kubectl get allYou've successfully refactored your Kubernetes manifests into a Helm chart!
Now we'll do a small refactor to try to take advantage of Helm templating. In this case we'll make the port exposed by the backend configurable via a boolean in ./demo/values.yaml file.
- Open the default ./demo/values.yaml file and replace it's entire contents with:
backend:
port: 4242Now this value is available to dynamically inject into your backend.yaml. Edit ./demo/templates/backend.yaml:
- modyfing the
deploymentresource like so: ports: # indicate this pod shall expose port 8000
-
- containerPort: 8000
-
- containerPort: {{ .Values.backend.port }} -
env: -
- name: PORT -
value: {{ .Values.backend.port | quote }}
* and modify the `service` like so:
````txt
- protocol: TCP
port: 80 # port for the service itself to expose on its IP
- targetPort: 8000 # must match the pod's `containerPort`
+ targetPort: {{ .Values.backend.port }}
Now assuming you've installed the Helm diff plugin, we can preview this change:
helm diff upgrade demo ./demoNow let's apply the change in Kubernetes:
helm upgrade demo ./demo/
# wait 30 sec and let's verify the backend is using the new port
kubectl logs -l app=backend --prefix=true -f
# kuberentes should restart your pods, which will now print:
#[pod/backend-54755577b7-nm5zg/backend] running on port 4242
#[pod/backend-54755577b7-k2q5j/backend] running on port 4242
#[pod/backend-54755577b7-zsxxg/backend] running on port 4242NOTE: If you trouble with this section at all, you can see the solution at:
Feel free to review the Kubernetes docs I linked to through this tutorial, and check the Helm docs for more info on the templating tricks available in Helm.
For example, you could try:
-
making the replicaCount for the backend deployment modifiable via values.yaml
-
conditionally creating a resource e.g. with:
{- if eq .Values.envName "test" }}
# yaml defining your resource here...
{{- end }}