Install kubefirst From the CLI

Using the CLI to create your cluster directly without using the UI is a perfect alternative for automation. The end result will be the same, a new production-ready management Kubernetes cluster, but you won't have access to the useful additional features available within the UI.

Prerequisites

kubefirst

macOS & Linux (Homebrew)

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

Linux (manually)

You can download the latest build for your architecture from the releases page. Once done, extract it, and ensure it's executable. You may need to use sudo for the tar or `chmod`` command.

tar --overwrite -xvf kubefirst_<VERSION>_linux_<ARCH>.tar.gz -C /usr/local/bin/ kubefirst && \
chmod +x /usr/local/bin/kubefirst

Now you can run kubefirst.

kubefirst version

Windows

We currently do not support Windows directly, but you can easily use kubefirst using WSL (tested with Ubuntu). To install the latest WSL version, please follow the Microsoft documentation on how to install Linux on Windows.

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

AWS Prerequisites

1. Create an AWS account with billing enabled.
2. Establish a public hosted zone with DNS routing established (docs). The account you will use to create your new cluster need to be the same as the one managing the domain DNS.
3. Connect with an Administrator Access IAM credentials to your AWS account (docs). It needs to be a set of temporary security credentials created with AssumeRole. More information on why, and future changes about it.
4. Our Homebrew package will automatically install the AWS IAM Authenticator dependency. If you use another installation method, you will need to install this utility.

tip

If you are not sure how to generate the role that will be assume, you can use this Terraform plan. Please read the comments before proceeding.

If you want to easily assume the role from your terminal, you can use this bash script.

GitHub

GitHub Prerequisites

• A GitHub organisation.
• A GitHub personal access token for your kbot account.

Create your new kubefirst cluster

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

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxx

kubefirst aws create \
  --alerts-email [email protected] \
  --domain-name your-company.io \
  --cluster-name kubefirst-mgmt \
  --github-org your-github-organization-name

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.

tip

By default kubefirst use the Git provider you selected as container registry. With AWS, you have the option to use EKS instead. To do so, add the flag --ecr with the value true to your cluster creation command.

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 ~ 10 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 Aws 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

GitLab

GitLab

• Create or use an existing GitLab account.
• Create a GitLab group developer permissions.
• A GitLab personal access token for your kbot account.

note

GitLab SaaS offering has limitations that require us to use groups contrary to GitHub which can be use without an organization.

info

If you want to use GitLab self-managed, you can update your GitOps repository and Kubernetes cluster once the creation is done following this tutorial.

Create your new kubefirst cluster

Adjust the following command with your GitLab token in addition to the appropriate values for your new platform.

export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxx

kubefirst aws create \
  --alerts-email [email protected] \
  --git-provider gitlab \
  --gitlab-group your-gitlab-group \
  --domain-name your-domain.io \
  --cluster-name kubefirst

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.

tip

By default kubefirst use the Git provider you selected as container registry. With AWS, you have the option to use EKS instead. To do so, add the flag --ecr with the value true to your cluster creation command.

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 ~ 10 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 Aws 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

Root credentials

To obtain your 3 initial passwords, run

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

To connect to your new Kubernetes cluster, run

export KUBECONFIG=~/.k1/kubeconfig

To view all cluster pods, run

kubectl get pods -A