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
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. Check out details on how to do it at Civo Academy. 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 your Civo Kubernetes cluster
If this is your first time working with Civo, check out the guide on how you can set up a Civo Kubernetes cluster.
Once your cluster is ready, 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://22.214.171.124:6443 CoreDNS is running at https://126.96.36.199: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:
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
apiVersion: v1 kind: Service metadata: name: hello-world labels: app: hello-world spec: ports: - name: "hello-world" port: 5000 selector: app: hello-world
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.
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.