In this guide, we'll be going through how you can interact with your Civo Kubernetes cluster. Check out our guide if you want to learn more about how to launch a Civo Kubernetes cluster.

Once you have your cluster up and running, you should be seeing a dash board like this:

Interacting with your cluster via the dashboard

At the dashboard shown above, you can view information about your cluster at one place. You can view information such as the number of nodes, external IP, API endpoints, DNS name, firewall, and more. You can also download the Kubeconfig from the dashboard and also manage the NodePools as explained in this guide.

You can also view information about the installed applications, and add more applications if needed.

CLI Setup

Using the Civo CLI

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
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
  snapshot     Details of Civo snapshots
  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

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 can use the CLI to interact with our clusters!

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

You can also scale the NodePool of your cluster via the CLI. The complete guide for how you can do that can be found here.

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.