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 even 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.
Prerequisites and Set-Up
For the purposes of this guide, you will need to have an active Civo account. If you have not yet created your account, you can sign up and then return to the guide.
Downloading Civo CLI
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
If you prefer, you can run this in your terminal:
curl -sL https://civo.com/get | sh
There are more instructions for different operating systems such as Windows, that you can find in the repository's read-me.
After installation, you should be able to run civo from your terminal, and get the following:
$ civo
civo is a CLI library for managing cloud resources such
as instances and Kubernetes clusters at Civo.com.
Usage:
civo [flags]
civo [command]
Available Commands:
apikey Manage API keys used to access your Civo account
completion Generates bash completion scripts
diskimage Details of Civo disk images
domain Details of Civo domains
firewall Details of Civo firewalls
help Help about any command
instance Details of Civo instances
kubernetes Details of Civo Kubernetes clusters
loadbalancer Details of Civo Load Balancer
network Details of Civo networks
quota Show quota
region Details of Civo regions
size Details of Civo instance sizes
sshkey Details of Civo SSH keys
update Update the cli to the last version
version Version will output the current build information
volume Details of Civo volumes
Flags:
--config string config file (default is $HOME/.civo.json)
-f, --fields string output fields for custom format output (use -h to determine fields)
-h, --help help for civo
-o, --output string output format (json/human/custom) (default "human")
--pretty Print pretty the json output
--region string Choose the region to connect to, if you use this option it will use it over the default region
-y, --yes Automatic yes to prompts; assume "yes" as answer to all prompts and run non-interactively
Use "civo [command] --help" for more information about a command.
Error: a valid subcommand is required
Usage:
civo [flags]
civo [command]
Available Commands:
apikey Manage API keys used to access your Civo account
completion Generates bash completion scripts
diskimage Details of Civo disk images
domain Details of Civo domains
firewall Details of Civo firewalls
help Help about any command
instance Details of Civo instances
kubernetes Details of Civo Kubernetes clusters
loadbalancer Details of Civo Load Balancer
network Details of Civo networks
quota Show quota
region Details of Civo regions
size Details of Civo instance sizes
sshkey Details of Civo SSH keys
update Update the cli to the last version
version Version will output the current build information
volume Details of Civo volumes
Flags:
--config string config file (default is $HOME/.civo.json)
-f, --fields string output fields for custom format output (use -h to determine fields)
-h, --help help for civo
-o, --output string output format (json/human/custom) (default "human")
--pretty Print pretty the json output
--region string Choose the region to connect to, if you use this option it will use it over the default region
-y, --yes Automatic yes to prompts; assume "yes" as answer to all prompts and run non-interactively
Use "civo [command] --help" for more information about a command.
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 With your API Key
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 region, number of nodes and the specifications for those nodes (depending on your account, 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.
Note that you will need to have set the correct civo region for where the cluster was created, or specify it in the command to be able to download the cluster's configuration file.
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.
Note that you will need to have set the correct civo region for where the cluster was created, or specify it in the command to be able to view the cluster information.
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 kube_demo
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 |
+----------------+-----------+-----------+--------------+
| 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. This can be done on a node pool basis. It's easy to do so from the command line in a single command. It takes the name of the cluster (or the ID), the pool ID, and --nodes which is the new number of nodes in the pool:
$ civo kubernetes node-pool scale kube_demo 5ef83b --nodes 5
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 : 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!
Deleting a cluster:
$ 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 Civo Community Slack or on the GitHub repository.
