This guide will walk you through going from code to building a Docker container to running that container in a Kubernetes cluster.
- a Kubernetes cluster
- Docker and a basic knowledge of running and building containers
- A Docker Hub account (sign up if you don't have one)
We'll need an ingress controller for your cluster to get traffic from the internet to your app. We'll use Ambassador's Edge Stack for this.
We recommend installing using Helm but there are other options below to choose from.
If needed, see the list of other installation options.
Now that your cluster is ready to go, let's check out the app we're going to use.
We're going to use a sample web app provided by Docker: a bulletin board written using Node.js. The repo contains the app's code and a Dockerfile for building a container.
Start by cloning the repo and switching into the directory containing the Dockerfile.
Open and inspect the Dockerfile. It follows these basic steps:
- use the latest Node.js slim base image
- install dependencies using npm
- expose port 8080 on the container
- start the Node.js server using npm
Next, we'll build the container and start running it locally, to make sure everything works and see what the app looks like. Make sure Docker is running, then run these commands to build and run the container (substituting in your Docker Hub username):
Let's look at the flags on the
docker run command:
-druns in detached mode, runs in the background after starting
-psets a localhost port to map to a container port, in this case http://localhost (implying port 80) will map to 8080 on the container
--namesets the name of the running container
<your Docker Hub username>/nodebb:1.0is the built image that the container will run
Go to http://localhost to see the web app in action.
Let's stop and remove the container before moving on:
To deploy the app to your cluster, Kubernetes must be able to pull the image from a repository. In this case, we are using Docker Hub. First, you must log in to Docker Hub on the Docker CLI to authorize it to push to your account:
Login to your account as prompted.
Next, push the
nodebb image to Docker Hub:
docker push <your Docker Hub username>/nodebb:1.0
When it finishes go to Docker Hub and you should see your image as a public repository
Save this file as
nodebb.yaml, replacing the value for your Docker Hub username.
This manifest file first creates a Deployment, which defines and runs the Pod. Pods in Kubernetes are usually made up of a single container, in this case, the
nodebb container you pushed to Docker Hub.
Next, it creates a Service, which handles getting the traffic on the specified port to the Pod.
Finally, it creates a Mapping, which is used by Edge Stack to expose a Service to the internet at a specific URL prefix,
/ in this case (as in the root of your hostname or IP address, like
Compare the Deployment and Service to our previous
docker run command. You should see things that look familiar, like the image repository, name, and tag, and the port on the container being mapped to a port on the host.
Also, notice how certain values match across the different resources? For example, the Deployment's
spec.template.metadata.labels value and the Service's
spec.selector value match. This is essential to connect these different cluster resources together so that the Services knows what Deployment to send the traffic to.
Deploy the YAML file with
kubectl apply -f nodebb.yaml.
Get IP address of Edge Stack (the ingress controller that you installed at the beginning of this guide):
Finally, go to
http://<load balancer IP>/ and you should see your app.
If you have a registered domain name then you can take this one step further by setting up a Host resource to provision an SSL certificate.
You'll first need to create an A record at your DNS provider. We suggest a subdomain like
test.yourdomain.com. For the A record's IP address use the load balancer IP from the previous step.
Once the record is created and you give it a few minutes to propagate across the internet, save the following as
host.yaml, filling in your domain name and email address.
This tells Edge Stack to use your domain name to generate and install an SSL certificate via Let's Encrypt. Apply the file with
kubectl apply -f host.yaml then wait a moment for the certificate to generate.
You can check the certificate's status with
kubectl describe host nodebb-host. When complete you should see an event saying
Host with ACME-provisioned TLS certificate marked Ready.
Finally, go to your domain in the browser and you should see the app with a valid SSL certificate installed.
YAML files used to deploy Kubernetes resources are generally kept under version control. You can automate deploying and updating resources as changes are committed to your code repositories using a CI/CD system like Argo! Check out our guide on getting started with Argo.
Debugging services running on Kubernetes can be a frustrating process, make it easier and faster using Telepresence!