Skip to main content
Version: 2.7

Prerequisites​

Kubefirst​

If you are on macOS or Linux, and have Homebrew installed, you can run:

brew install konstructio/taps/kubefirst

To upgrade an existing Kubefirst CLI to the latest version run:

brew update
brew upgrade kubefirst

Docker Desktop​

Install Docker Desktop.

info

If you are a Windows user, you need to be sure to enable Docker support in WSL2 distributions. More information in the Docker documentation.

Docker Resources Allocation​

The more resources you give Docker, the faster your cluster creation will go, but here are the minimum requirements:

  • CPU: 5 Cores
  • Memory (RAM): 5 GB
  • Swap: 1 GB
  • Virtual Disk limit (for Docker images & containers): 10 GB

If you pull multiple images from Docker Hub, you may reach the rate limit: to help this issue not happening, we suggest you log in to your account (you can create a free one) in Docker Desktop. At the time of writing this docs, the limit is doubled when signed in.

Azure Prerequisites​

For kubefirst to be able to provision your Azure cloud resources:

Environment variables​

Azure authentication requires the following environment variables to be set:

VariableDescription
ARM_CLIENT_IDThe unique ID for your service principal
ARM_CLIENT_SECRETThe secret for your service principal
ARM_SUBSCRIPTION_IDThe unique ID for your Azure subscription
ARM_TENANT_IDThe unique ID for your Microsoft Entra tenant

GitHub Prerequisites​

Install the CA (Certificate Authority) of mkcert 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 local install, you need to install the CA (Certificate Authority) of mkcert in your trusted store. To do so, follow these simple steps:

brew install mkcert
mkcert -install

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

If you are using Firefox, you have one more step: you need to install the Network Security Services (NSS):

brew install nss

Create your new kubefirst cluster​

Adjust the following command with your GitHub and Azure tokens in addition to the appropriate values for your new platform.

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx
export ARM_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export ARM_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export ARM_SUBSCRIPTION_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export ARM_TENANT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

kubefirst beta azure create \
  --alerts-email [email protected] \
  --github-org your-github-org \
  --domain-name your-domain.io \
  --cluster-name kubefirst \
  --dns-azure-resource-group <dns-resource-group>

The dns-azure-resource-group flag is only used if Azure is your DNS provider. This is the name of the resource group where the DNS Zone resource is provisioned. This flag is not required, but may be useful if you have multiple DNS Zones with the same URL configured. If the resource group is not provided, the first DNS Zone that matches the given URL in your subscription will be used.

tip

By default Kubefirst use the cloud providers to manage DNS. You also have the option to use Cloudflare.

To do so, add the dnsProvider flag with the value cloudflare to your create command --dns-provider cloudflare.

You also need to set the CF_API_TOKEN environment variable with a Cloudflare token (export CF_API_TOKEN=xxxxxxxxx) having the Zone.Zone, and Zone.DNS edit permission. More information on Cloudflare token creation in their documentation.

The Kubefirst CLI will produce a directory of utilities, a state file, and some staged platform content that can now be found in the ~/.kubefirst and ~/.k1 folders on your local machine.

After the ~ 20 minute installation, your browser will launch a new tab to the Kubefirst Console, which will help you navigate your new suite of tools running in your new Azure cluster.

If your deployment is not successful, errors and troubleshooting information will be stored in a local log file specified during the installation run.

Example of terminal output following cluster creation​

Handoff Screen