You're ready to deploy your first application to Kubernetes through the command line. This post will walk you through how to do exactly that, the tools you'll need and a bit of the theory behind what is going on.
Tools you will need
Kubectl
Kubernetes clusters are administered through a tool called kubectl. There are numerous tools that visualize your clusters, help out with monitoring and updating what's running on them, but fundamentally many of them utilize the functionality of kubectl under the hood. If you want to take a detour and read more, here is a guide to getting to grips with Kubernetes clusters on the command line.
You can install kubectl for your operating system from [the official Kubernetes site here. Make sure you do that now and test that it runs in your terminal. You should get something like the following:
$ kubectl
kubectl controls the Kubernetes cluster manager.
Find more information at: https://kubernetes.io/docs/reference/kubectl/overview/
Basic Commands (Beginner):
create Create a resource from a file or from stdin.
expose Take a replication controller, service, deployment or pod and expose it as a new Kubernetes Service
run Run a particular image on the cluster
set Set specific features on objects
(continues...)
In order to use kubectl, we are going to have to let it know which cluster you want it to manage. That's what the next section, on your cluster's kubeconfig, is for.
Your cluster kubeconfig
Each cluster has a configuration file that allows kubectl to control it. We need to tell our kubectl installation about our Civo cluster. If you already have a running Kubernetes cluster, great! You can skip ahead to the next section, Downloading your kubeconfig. If you do not have a running Civo Kubernetes cluster, keep reading.
Starting a Civo Kubernetes cluster
Go ahead and open up the Kubernetes dashboard in your account. Next, click on "Create cluster". You will get a screen giving you options about the cluster's name, node size and number, and other options:
Go ahead and give your cluster a name, keep the nodes to 3 and select size Medium. We are not deploying anything extra through the marketplace in this instance, so you can just leave it as is and scroll down to "Create" and press the button.
Wait a few minutes for the cluster to be ready, and you should see its details:
You can now proceed to the next section, Downloading your kubeconfig.
Downloading your kubeconfig
We can download our kubeconfig in two ways, through the web UI on the cluster page, or using Civo CLI. The CLI option is simpler, but requires you to have it installed.
Getting your kubeconfig file from the webpage
When you download the Kubeconfig file from the dashboard, it will be saved on your computer. The easiest way to persist that configuration for kubectl is to copy it to a location it will know to look in: in a sub-directory of your home directory called .kube, in a file called config. When you installed kubectl and tested it, it should have created this directory, so all that we need to do is move our downloaded configuration file to it:
$ cp <path-to-downloaded-config> ~/.kube/config
To test that kubectl can connect to your cluster, let's run a command, kubectl cluster-info to find out about it:
$ kubectl cluster-info
Kubernetes master is running at https://91.211.154.112:6443
CoreDNS is running at https://91.211.154.112:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
The reported Kubernetes master IP address should match the one on our cluster info page. You're ready to skip to the next section, The definition files!
Getting the Kubeconfig file using Civo CLI
As long as you have the CLI tool set up and your API Key associated with it, you will be able to download your cluster configuration and have it automatically save to the correct location on your operating system that was created when you set up Kubectl earlier:
$ civo kubernetes config hello-world --save
Warning: Are you sure you want to overwrite the kubernetes config (y/N) ? y
Access your cluster with:
kubectl get node
You will now be able to continue to the last part of preparation, the app definition files.
The definition files (YAML)
Kubernetes deployments and other resources are described as YAML files. They detail the types of services you want your cluster to run, the namespaces they should run in, and the containers the services should be running.
For the purposes of this application, we're going to need to define a Deployment, a Service and an Ingress. In short, they are:
- Deployment: which container image to use, the replicas to run, and the like.
- Service: Kubernetes' way to define how your deployments are to be accessed within the cluster, given the individual pods running your applications are ephemeral.
- Ingress: The way access from outside your cluster to your app is handled.
Our application will return "Hello, world!" when accessed. The three resource definitions are available copied below. Copy each one and save them as the filenames specified:
deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-world
spec:
replicas: 2
selector:
matchLabels:
app: hello-world
template:
metadata:
labels:
app: hello-world
spec:
containers:
- image: civo/docker-hello-world:latest
name: hello-world
service.yaml
apiVersion: v1
kind: Service
metadata:
name: hello-world
labels:
app: hello-world
spec:
ports:
- name: "hello-world"
port: 5000
selector:
app: hello-world
ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: traefik
labels:
app: hello-world
name: hello-world-ingress
spec:
rules:
- host: hello-world.<your_cluster_id>.k8s.civo.com
http:
paths:
-
backend:
service:
name: hello-world
port:
number: 5000
path: /
pathType: "Prefix"
When you save the above ingress.yaml file make sure to copy in the DNS entry from the cluster information page so that the full line looks something like - host: hello-world.a08e204b-d027-45af-8f5f-8861fa23f3d7.k8s.civo.com. This is what defines access to your application.
Deploying your application
We're now ready to deploy our Hello World application to our cluster. We're going to use kubectl to apply our configuration YAML files to our cluster, which Kubernetes will use to download the required container image and manage access to it.
The command we're going to need is kubectl apply -f <filename>. What this means is we are ordering our cluster to parse the specified file and set up resources according to it:
$ kubectl apply -f deployment.yaml
deployment.apps/hello-world created
$ kubectl apply -f service.yaml
service/hello-world created
$ kubectl apply -f ingress.yaml
ingress.networking.k8s.io/hello-world-ingress created
If you see output like above after each command, you have successfully deployed the application. Give it a few moments to start up while you give yourself a pat on the back!
Now, it's time to test it all works.
Testing your application
Each Civo Kubernetes cluster gets a DNS entry in the form of cluster-id.k8s.civo.com. Our application is set to run on a subdomain called hello-world. If you point your browser at http://hello-world.your-cluster-id.k8s.civo.com, you should see the application respond with a greeting:
This means the ingress is succesfully receiving your request at the correct sub-domain, routing it to the service, which then responds from one of the running containers back to you.
Conclusion
By following this guide, you have successfully deployed a simple application to Kubernetes by declaring the configuration you have specified in the deployment, service and ingress files. This application runs on a Civo Kubernetes cluster, and is accessible via the web on its own subdomain.
If you followed this guide to complete the "Deploy your application from the command line" step of KubeQuest, you can proceed to complete the step. Congratulations!
