Skip to main content
Version: 2.4

Install kubefirst from the CLI

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.

GitHub​

Create or use an actual GitHub personal account

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

Additional steps for Windows with WSL​

The certificate installed on your WSL distribution won't be propagated to the local system (Windows). If you want to access your k3d installation from your main OS without certification warning, you will need to add the certificate to your Windows Trusted Root Certification Authorities store. To do so, find the location of the store by running the following command in WLS:

mkcert -CAROOT

Now cd into that directory and run:

explorer.exe .

It will open Explorer in the current directory. Copy the full path, which should look like \\wsl.localhost\Ubuntu\root\.local\share\mkcert. Open PowerShell as an administrator, cd to the copied path, and run the following command:

certutil –addstore -enterprise –f "Root" .\rootCA.pem

Restart your browser, and you should be good to go.

Local Atlantis Executions (optional)​

To install the k3d kubefirst platform with Atlantis wired up for automated Terraform executions, you'll need to create an account with ngrok, and expose an ngrok auth token environment variable in your shell. This allows the GitHub/GitLab servers to invoke the Atlantis webhook running in your cluster.

You can sign up for an ngrok account for free.

Once you've logged in, you can retrieve your ngrok auth token.

Make this available by running the following in your shell before you execute your kubefirst k3d create command, replacing the xxxxxxxxxxxxxxxxxxxxx with your actual authtoken.

export NGROK_AUTHTOKEN=xxxxxxxxxxxxxxxxxxxxx

If you skip this step the platform will still operate just fine, you just won't have automated Terraform plans and applies in your pull requests.

Working without SSH​

If you need your kubefirst installation to avoid using SSH whenever possible, you can bypass SSH and kubefirst will configure itself, GitHub Actions, Argo CD, and your entire GitOps workflow to utilize HTTPS instead of SSH at all times.

Provide the flag --git-protocol https when building your k3d cluster and kubefirst will take care of the rest.

If you ever need to change this, you will need to rebuild the cluster or manually update the templates in your gitops repository.

Create your new local cluster​

To create a new kubefirst cluster locally, run

kubefirst k3d create

Details about your execution will be logged to your ~/.k1/logs directory. More information on kubefirst k3d, including optional flags, can be discovered by running kubefirst k3d help.

We are able to create an ephemeral GitHub token that expires after 8 hours using a process that will prompt your browser to request access to your account. If you need a quick environment, this is a frictionless approach. However, if you need this environment for longer than 8 hours, which is probably the case, please follow our GitHub Token Guide and export a more permanent token to your terminal by using the following command:

export GITHUB_TOKEN=ghp_xxxxxxxx

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

Installed Applications​

To see what is installed by kubefirst, check the overview page.

Console UI Screen​

kubefirst console screen

Root credentials​

To obtain your 3 initial passwords, run

kubefirst k3d root-credentials

root credentials

If you created your cluster using the UI, or reset your kubefirst environment, you can still retrieve the root credentials (except the kbot user password, which you will have to find manually in Vault) using kubectl:

# Argo CD admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# Vault root token
kubectl -n vault get secret vault-unseal-secret -o jsonpath="{.data.root-token}" | base64 -d

Connecting to Kubernetes​

You will be automatically connected to your new Kubernetes cluster. To view all cluster pods, run

kubectl get pods -A