Skip to main content

Civo Marketplace Prerequisites

Summary​

This document walks through the prerequisites for installing Kubefirst using Civo Marketplace and the Kubefirst UI.

Why Use Civo Marketplace to Install?​

We recommend using Civo Marketplace to install Kubefirst for users who:

  • Don’t want to host Kubefirst on their local machine
  • Don’t have a local machine with sufficient resources to support an installation
  • May have connectivity issues that would interfere with installation

Install Assumptions​

Before getting started make sure you are aware of the following:

  • We assume that you already have a Civo Cloud account and credentials.
  • We assume you have a Git organization (in either GitLab or GitHub) that is free to use for this installation.
  • We are assuming you have never installed Kubefirst or Kubefirst Pro before.
    • If you have previously installed Kubefirst or Kubefirst Pro you will need to remove the ~/.k1 folder, the ~/.kubefirst file, and anything related to k3d in Docker for the steps, as they’re outlined here, to be successful.
  • We’re going to use your personal account for GitHub or GitLab as an admin and associate it with the bot that we use to build automation. This is faster but it also means that if you want to continue beyond just “testing it out” there are additional steps required to establish an independent bot account for the system to use. The bot is yours to run, configure, or remove and we do not store information on our servers.

Prerequisites​

Before getting started with this installation there are several things you will need to have set up to successfully complete the installation.

info

These instructions assume you don’t already have a cluster that you want to use to install Kubefirst.

Homebrew​

The commands we provide here assume you are using Homebrew.

Civo Components​

Civo Account​

A Civo account with administrative access (with permissions to create SSH Keys, S3 Buckets, Kubernetes Clusters, and a Network).

Civo CLI​

Run the following command to install the Civo CLI.

brew install civo/tools/civo

Learn more about the Civo CLI.

Civo API Key​

Your saved Civo API Key.

Kubectl​

The instructions below also use kubectl. Run the following brew command to install

brew install kubernetes-cli

Git Provider (GitHub or GitLab)​

After provisioning your installer cluster you will need to have domain details for your preferred Git provider for your management cluster. We support GitHub and GitLab.

  • Organization name/Group name
  • Personal Access token
  • Username

Check out our instructions for details (including scopes/permissions) on creating your git token.

DNS​

Kubefirst assumes that you will use your cloud provider for DNS. We also support Cloudflare, refer to the details below.

For information on Civo check out their documentation on adding DNS.

Cloudflare (Optional for DNS)​

If you prefer to use Cloudflare as your DNS provider:

  • Create a dedicated Cloudflare user account
  • Create a user token with read and write access to your registered zone. This token will be required during installation.

Refer to the Cloudflare documentation for user token creation for additional details.

mkcert Certificate Authority​

tip

This is not an optional step: the cluster creation will fail if you don't install the mkcert CA in your trusted store.

We use mkcert to generate local certificates and serve https with the Traefik Ingress Controller. During the installation, Kubefirst generates these certificates and pushes them to Kubernetes as secrets to attach to Ingress resources.

To allow the applications running in your Kubefirst platform, in addition to your browser, to trust the certificates generated by your Kubefirst install, you need to install the CA (Certificate Authority) of mkcert in your trusted store.

Run the following command to install mkcert.

brew install mkcert
mkcert -install

For Firefox, you will also need to install Network Security Services (NSS):

brew install nss

Known Limitations​

Installation of Kubefirst using Civo marketplace has the following known limitations

Let's Encrypt Certificate Rate Limit​

Kubefirst uses Let's encrypt to automatically create certificates for your domains. Let's encrypt limits creation to 50 weekly certificates with an additional limitation of 5 per subdomain. In some scenarios you may reach that limit if you often create and destroy Kubefirst clusters using the same domain during a short period. You can use the Let's Debug Toolkit to check those.

Cloudflare DNS with origin certificates is an alternative method that allows unlimited certificate creation if this limit impacts you.

Civo Specific​ DNS​

Subdomains are not supported. Using subdomains with Civo DNS won't create a virtual cluster successfully. We recommend using Cloudflare as a DNS provider or using a root domain with Civo.

Getting Support​

If you’re not sure this is the best method of installation for you, or you started the install and ran into issues, or if you have a question about the process and don’t see it mentioned here, we've got you covered. Join our Slack Community for support and get the answers you need!