Introduction

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 Kubnernetes 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:

New Kubernetes Cluster

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:

Cluster 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:

$ 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/v1beta1
kind: Ingress
metadata:
  name: hello-world-ingress
  annotations:
    kubernetes.io/ingress.class: "traefik"
  labels:
    app: hello-world
spec:
  rules:
    - host:
      http:
        paths:
          - path: /
            backend:
              serviceName: hello-world
              servicePort: 5000

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:

Hello, world deployed

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!

If you have any questions or have any trouble with this guide, please let us know in the Civo Community Slack.