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.

Before we get into the guide, we also have a video walkthrough demonstrating launching a cluster both of the Civo CLI and from the dashboard.

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. Civo CLI is built with Go and distributed as binary files, available for multiple operating systems. You can find the latest release in the GitHub repository, or if you use Homebrew on Mac OS, you can also install it as follows:

brew tap civo/tools
brew install civo

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 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 tool, simply run civo update or brew upgrade civo.

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 g3.k3s.medium respectively). For more visibility and control, we can provide these options and a few switches: $ civo kubernetes create kube_demo --size=g3.k3s.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, Civo CLI can merge the new information to the existing file, creating a new context:

$ civo kubernetes config kube_demo --save --merge
Merged with main kubernetes config: ~/.kube/config

Access your cluster with:
kubectl config use-context kube_demo
kubectl get node

This then allows you to context-switch to manage different clusters 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]. You can even use a partial name or unique section of the ID to have it show, like in the following example - as long as the part of the name you input matches only one cluster, you'll get the cluster information returned: ``` $ civo kubernetes show kube ID : 1718b50e-4e87-4488-9e28-43c9e71f3432 Name : kube_demo # Nodes : 2 Size : g3.k3s.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 kubernetes 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 kubernetes 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 stateful, you will be need to provide your chosen storage-size plan or be prompted for it: civo kubernetes 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 kubedemo ID : 1718b50e-4e87-4488-9e28-43c9e71f3432 Name : kubedemo # Nodes : 2 Size : g3.k3s.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 kubedemo ID : 1718b50e-4e87-4488-9e28-43c9e71f3432 Name : kubedemo # Nodes : 3 Size : g3.k3s.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.

Recycling Nodes

If you need to rebuild nodes for whatever reason, such as a node you can use the recycle method. This takes as arguments your cluster and the specific node you wish to recycle. Recycling a node will delete it entirely, rebuild a new node to match it, and attach that to your cluster.

$ civo kubernetes recycle kube_demo --node kube-node-2f5d
The node (kube-node-2f5d) was recycled

If you were to take a look at your cluster, you would see something like the following, showing the new node being built (excerpted from civo kubernetes show kube_demo):

Nodes:
+------------------+----+--------+-----------+-----------+------+----------+
| Name             | IP | Status | Size      | Cpu Cores | Ram  | SSD disk |
+------------------+----+--------+-----------+-----------+------+----------+
| kube-master-7868 |    | ACTIVE | g2.medium |         2 | 4096 |       50 |
| kube-node-7a70 |    | ACTIVE | g2.medium |         2 | 4096 |       50 |
| kube-node-dd79   |    | BUILD  | g2.medium |         2 | 4096 |       50 |
+------------------+----+--------+-----------+-----------+------+----------+

Note: When a node is recycled, it is fully deleted. The recycle command does not drain a node, it simply deletes it before building a new node and attaching it to a cluster. It is intended for scenarios where the node itself develops an issue and must be replaced with a new one.

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 kubedemo Removing Kubernetes cluster kubedemo

$ civo kubernetes show kubedemo No Kubernetes clusters found for 'kubedemo'. 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.