Skip to content

Platform Installation with the Kubefirst CLI

Kubefirst is the name of our command line tool that installs the Kubefirst platform and provides some platform conveniences.

It installs a fully automated platform of open source cloud native tools with a simple init and create command.


AWS Prerequisites

  1. Create an AWS account with billing enabled.

  2. Establish a public hosted zone with dns routing established(docs).

  3. Connect with AdministratorAccess IAM credentials to your AWS account (docs).

Step 1 - Download

Download the latest Kubefirst CLI.

Installation Using Homebrew

brew install kubefirst/tools/kubefirst

Installation Using Other Methods

There are a number of other ways to install Kubefirst for different operating systems, architectures, and containerized environments. Please see our installation readme for details.

Step 2 - Create your kubefirst bot user and a personal access token

The kubefirst cli will automatically create one admin user for you. We refer to this initial user as the kubefirst bot. After the installation, you will temporarily use that kubefirst bot to onboard yourself and the rest your team to the platform. From that point forward, the kubefirst bot should only be used for automated activities, and you can use your own personal account.

This kubefirst bot user needs to be associated with a GitHub user account. Log out of GitHub and create a new GitHub account to represent this new kubefirst bot account. Because this account will be used for automation, it's a good to choose a username that generically represents your company or project name - something like yourcompany-bot is a good idea. You can also have fun with it and give your bot a fun name - the point is that this is not an account for your long term personal use, it's for the kubefirst system to use.

Your new bot account will need to be associated with a GitHub organization.

  • If you don't already have one that you want to use, while logged into GitHub with your new bot account, establish a new GitHub organization.
  • If you do already have a GitHub org that you want to add Kubefirst to, you'll need to add your new kubefirst bot to the existing organization now.

While logged in with your GitHub bot account, go to your Personal Access Tokens and generate a new token with the following permissions:

GitHub token

Expose the new token to your local environment so the kubefirst cli can leverage it:

export KUBEFIRST_GITHUB_AUTH_TOKEN=your-new-token

Step 3 - kubefirst init

With your new KUBEFIRST_GITHUB_AUTH_TOKEN exported, let's init your local setup providing values for the following flags:

Flag Description Example
--admin-email an email address that can be used for certificate renewal alerts and the gitlab root account
--cloud we only support aws, gcp coming soon aws
--hosted-zone-name name of the platform's hosted zone domain - this will drive the URLs of your tools (,, etc)
--cluster-name the name of your cluster your_cluster_name
--region name of the aws region in which to place your region specific resources us-east-1
--profile name of the aws profile the cli should leverage default
--s3-suffix unique identifier for s3 buckets you-s3-bucket-name
--github-user name of your github user your_username
--github-org name of your github organization name your_organization
--aws-nodes-graviton Graviton nodes (ARM) on AWS EKS compute nodes true
--aws-nodes-spot nodes spot on AWS EKS compute nodes true
export KUBEFIRST_GITHUB_AUTH_TOKEN=your-new-token

kubefirst init \
--admin-email \
--cloud aws \
--hosted-zone-name \
--region us-east-1 \
--profile default \
--cluster-name your-cluster-name \
--github-user your-bot-users-github-username \
--github-owner your-github-organization-name

The init process produces a directory of utilities, a state file, and some staged platform content that can now be found at ~/.kubefirst

Step 3 - kubefirst cluster create

Now it's time to create the platform, to do so, simply run

kubefirst cluster create