Introduction

For scripting and automation, having a command-line interface to cloud services is invaluable. Civo customers can use our CLI tool to manage their account, instances, and for those lucky enough to be on our managed #KUBE100 Beta programme, their Kubernetes clusters! This guide will run through the functionality of the Civo CLI tool from the perspective of cluster management, starting from set-up for your account, and finishing at deleting your clusters.

Pre-Requisites and Set-Up

For the purposes of this guide, you will need to have a Civo account and, for the time being, be in our #KUBE100 beta programme. You can apply for access to the beta here.

Once you have your account activated to use the managed Kubernetes features, you will need to download the Civo CLI tool. This is distributed as a Ruby gem, so first you would need to have Ruby installed. You can do this for your operating system at:

To download the CLI tool, simply download the gem: gem install civo_cli You may need to use sudo if you get an error about You don't have write permissions when installing the gem. The syntax is sudo gem install civo_cli.

After installation, you should be able to run civo from your terminal, and get the following:

$ civo
Commands:
  civo apikey          # manage API keys stored in the client
  civo applications    # list and add marketplace applications to Kubernetes clusters
  civo blueprint       # manage blueprints
  civo domain          # manage DNS domains
  civo domainrecord    # manage domain name DNS records for a domain
  civo firewall        # manage firewalls
  civo help [COMMAND]  # Describe available commands or one specific command
  civo instance        # manage instances
  civo kubernetes      # manage Kubernetes
  civo loadbalancer    # manage load balancers
  civo network         # manage networks
  civo quota           # view the quota for the active account
  civo region          # manage regions
  civo size            # manage sizes
  civo snapshot        # manage snapshots
  civo sshkey          # manage uploaded SSH keys
  civo template        # manage templates
  civo version         # show the version of Civo CLI used
  civo volume          # manage volumes

Civo CLI is in active development, so it's worth periodically checking you are running the current version. If you need to upgrade the gem, simply run civo update or gem install civo_cli:

$ civo version
You are running v0.3.6 of Civo CLI, but are out of date because v0.4.0 is available
$ sudo gem install civo_cli
Fetching civo_cli-0.4.0.gem
Successfully installed civo_cli-0.4.0
Parsing documentation for civo_cli-0.4.0
Installing ri documentation for civo_cli-0.4.0
Done installing documentation for civo_cli after 0 seconds
1 gem installed
$ civo version
You are running the current v0.4.0 of Civo CLI

Setting Up Your Civo CLI

The first step is to get your API key to make sure you can access your account using the CLI. Your Civo account will have one created for you already - you can see it here as long as you are logged in to your account. You can also regenerate a code at that page.

We'll have to add key to the CLI config:

$ civo apikey add Demo_Test_Key DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r
Saved the API Key DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r as Demo_Test_Key

Set the current key to be the key we just added:

$ civo apikey current Demo_Test_Key
The current API Key is now Demo_Test_Key

Now we're ready to deploy our cluster!

Creating a Cluster

The simplest way for you to create a cluster is to simply run:

civo kubernetes create

This will generate a name for your cluster and use default values for the number of nodes and the specifications for those nodes (three, and g2.medium respectively). For more visibility and control, we can provide these options and a few switches:

$ civo kubernetes create kube_demo --size=g2.medium --nodes=2 --wait
Building new Kubernetes cluster kube_demo:
Building new Kubernetes cluster kube_demo: Done
Created Kubernetes cluster kube_demo in 01 min 18 sec

You can get the full list of command options for cluster creation by running civo kubernetes help create.

Downloading the Cluster's Configuration

When you have created a cluster, you can download or display the configuration file to administer it using the CLI as well:

civo kubernetes config kube_demo --save
Saved config to ~/.kube/config

For the above operation to work, you must already have kubectl installed. If you already have a ~/.kube/config file, this command will merge the new information to the existing file, allowing you to context-switch using kubectl, kubectx or another tool of your choice such as Octant.

If you wish to merely view the cluster's configuration on screen, run civo kubernetes config [cluster_name] without any switches.

You can combine creating a cluster and saving your configuration all in one step by calling --wait --save on civo kubernetes create. This will wait for the creation of the cluster to complete and download the configuration.

Viewing Cluster Information

We now have a running cluster with our specifications. We can get a nicely-formatted information screen by running civo kubernetes show [cluster_name]:

 $ civo kubernetes show kube
                ID : 1718b50e-4e87-4488-9e28-43c9e71f3432
              Name : kube_demo
           # Nodes : 2
              Size : g2.medium
            Status : ACTIVE
           Version : 0.8.1
      API Endpoint : https://91.211.152.88:6443

Nodes:
+------------------+---------------+--------+
| Name             | IP            | Status |
+------------------+---------------+--------+
| kube-master-7868 | 91.211.152.88 | ACTIVE |
| kube-node-7a70   | 91.211.152.97 | ACTIVE |
+------------------+---------------+--------+

Installed marketplace applications:
+---------+-----------+-----------+--------------+
| Name    | Version   | Installed | Category     |
+---------+-----------+-----------+--------------+
| Traefik | (default) | Yes       | architecture |
+---------+-----------+-----------+--------------+

We can see that the two nodes we requested are running, they are the size we wanted them to be, and we have the default installed application, Traefik up as well. Any changes, such as scaling your cluster up/down, will be immediately reflected on this status screen.

Adding Applications

Great, you're running your cluster, and have its configuration to administer it. You can also install applications to the cluster directly from the command line. You can see the available applications by running civo applications list - As I type this the list is the following, but we are adding more by community demand so if you have a suggestion for an app you'd like to see, let us know by raising it as an issue on our open repository for the Kubernetes marketplace!

$ civo applications list
+----------------+------------+--------------+-----------------+--------------+
| Name           | Version    | Category     | Plans           | Dependencies |
+----------------+------------+--------------+-----------------+--------------+
| cert-manager   | v0.10.0    | architecture | Not applicable  | Helm         |
| Helm           | 2.14.3     | management   | Not applicable  |              |
| Linkerd        | 2.5.0      | architecture | Not applicable  |              |
| Longhorn       | 0.5.0      | storage      | Not applicable  |              |
| Maesh          | Latest     | architecture | Not applicable  | Helm         |
| MariaDB        | 10.4.7     | database     | 5GB, 10GB, 20GB | Longhorn     |
| metrics-server | Latest     | architecture | Not applicable  | Helm         |
| MinIO          | 2019-08-29 | storage      | 5GB, 10GB, 20GB | Longhorn     |
| OpenFaaS       | 0.17.0     | architecture | Not applicable  | Helm         |
| PostgreSQL     | 11.5       | database     | 5GB, 10GB, 20GB | Longhorn     |
| Redis          | 3.2        | database     | Not applicable  |              |
| Traefik        | (default)  | architecture | Not applicable  |              |
+----------------+------------+--------------+-----------------+--------------+

You can see some of the apps have dependencies, which will be installed automatically alongside the main application.

If your chosen application is statefull, you will be need to provide your chosen storage-size plan or be prompted for it:

civo applications add PostgreSQL --cluster=kube_demo
You requested to add PostgreSQL but didn't select a plan. Please choose one... (5GB, 10GB, 20GB) [5GB]: 5GB
Thank you, next time you could use "PostgreSQL:5GB" to choose automatically
Added PostgreSQL 11.5 to Kubernetes cluster kube_demo

Now, our cluster will immediately show that it has PostgreSQL and its dependency Longhorn installed:

$ civo k8s show kube_demo
                ID : 1718b50e-4e87-4488-9e28-43c9e71f3432
              Name : kube_demo
           # Nodes : 2
              Size : g2.medium
            Status : ACTIVE
           Version : 0.8.1
      API Endpoint : https://91.211.152.88:6443

Nodes:
+------------------+---------------+--------+
| Name             | IP            | Status |
+------------------+---------------+--------+
| kube-master-7868 | 91.211.152.88 | ACTIVE |
| kube-node-7a70   | 91.211.152.97 | ACTIVE |
+------------------+---------------+--------+

Installed marketplace applications:
+----------------+-----------+-----------+--------------+
| Name           | Version   | Installed | Category     |
+----------------+-----------+-----------+--------------+
| Longhorn       | 0.5.0     | Yes       | storage      |
| Traefik        | (default) | Yes       | architecture |
| PostgreSQL 5GB | 11.5      | Yes       | database     |
+----------------+-----------+-----------+--------------+

Scaling Your Cluster

Let's say you want to scale your cluster, whether as part of a script to add mode nodes based on demand, or to quickly bring the node count down. It's easy to do so from the command line in a single command:

$ civo kubernetes scale kube_demo --nodes=3
Kubernetes cluster kube_demo will now have 3 nodes

By looking into the cluster status, we can see this change immediately starts building a new node, as we increased the count:

$ civo kubernetes show kube_demo
                ID : 1718b50e-4e87-4488-9e28-43c9e71f3432
              Name : kube_demo
           # Nodes : 3
              Size : g2.medium
            Status : INSTANCE-CREATE
           Version : 0.8.1
      API Endpoint : https://91.211.152.88:6443

Nodes:
+------------------+---------------+---------------+
| Name             | IP            | Status        |
+------------------+---------------+---------------+
| kube-master-7868 | 91.211.152.88 | ACTIVE        |
| kube-node-7a70   | 91.211.152.97 | ACTIVE        |
| kube-node-bc2c   |               | BUILD_PENDING |
+------------------+---------------+---------------+

Installed marketplace applications:
+----------------+-----------+-----------+--------------+
| Name           | Version   | Installed | Category     |
+----------------+-----------+-----------+--------------+
| Longhorn       | 0.5.0     | Yes       | storage      |
| Traefik        | (default) | Yes       | architecture |
| PostgreSQL 5GB | 11.5      | Yes       | database     |
+----------------+-----------+-----------+--------------+

Within seconds, your new node will also be active.

If you want to scale your cluster down, that's easy too: simply specify the number of nodes you want to scale down to, and the CLI will take care of the hard work.

Teardown: Deleting Your Cluster

Clusters are not pets, and accordingly can be removed with one command. However, be aware that this change is immediate, and will immediately bring down all nodes of the cluster, so use it with caution!

$ civo kubernetes remove kube_demo
Removing Kubernetes cluster kube_demo

$ civo kubernetes show kube_demo
No Kubernetes clusters found for 'kube_demo'. Please check your query.

Conclusion

This guide has run through the main capabilities of Civo CLI to administer Kubernetes clusters. You have seen how to create, scale and tear down your clusters, get information about them and install applications from the Civo Marketplace.

Many of the above commands can be combined into a single step, such as creating a cluster and saving your configuration all in one step. You can use the CLI to automate cluster builds and removals, allowing you to build the managed Kubernetes functionality into your workflow.

Remember, there is contextual help for all commands that you can access by running civo kubernetes help [COMMAND] at any time.

If you have any suggestions for features you would like to see Civo CLI have, or have any other questions or even bug reports, you can let us know on the #KUBE100 Community Slack or on the GitHub repository.