Skip to main content
Version: 2.4

FAQ

General​

I ran into an issue, what should I do?​

If an error occurs, try to run the command again if you are using the CLI. Note that it is not advised to retry by changing some of the flags you used as they may not be taken into consideration, or can cause potential issues. If you want to do so, deprovision what was created, and start with a new canvas. If you are using the UI, there is a "Retry" button you can use. In both cases, the execution state is kept, and the process will start again where it ended. If it doesn't work, check the logs provided in the ~/.k1/logs folder for the CLI, and in the UI interface, in the "Verbose" tab.

If you are not sure about the steps to take to fix the problem you encounter, join our Slack community, and ask for help in the #helping-hands channel. We'll gladly work through it with you. If you think there is a bug, you can also open an issue describing the problems you are having.

I'm experiencing timeouts when kubefirst deploys Argo CD or HashiCorp Vault through the Helm installations​

You may need a more stable connection / higher download speed. Check with your internet provider or use an online speed test to confirm you have at least 100mbps download speed, or else you may experience timeouts.

I'm stuck with artifacts after a failed local installation and can't continue​

If you still cannot complete the installation due to remaining artifacts after completing a kubefirst k3d destroy, you may have to do a manual teardown. Firstly, you need to delete the k3d cluster with the following command:

~/.k1/<your-cluster-name>/tools/k3d cluster delete kubefirst
kubefirst reset

Once it's done, you can delete the GitHub assets we created by logging into your account and removing the gitops, and metaphor repositories. You can also use the GitHub CLI to do that1:

gh repo delete <GITHUB_USERNAME>/metaphor --confirm
gh repo delete <GITHUB_USERNAME>/gitops --confirm

What is the wait.yaml file in each application components folder?​

We've had issues with Argo CD and its sync waves not orchestrating correctly (it's a known bug, here's one example), so we've added the wait.yml file as a secondary measure to help with the reliability of the platform provisioning. We may revisit how this is functioning, and remove those files on our platform orchestration evolution.

Can I install kubefirst on an existing cluster?​

It is not possible for now to install kubefirst (as in, the management cluster) on an existing cluster. Since our tool install multiple applications to give you that production-grade management cluster, it would be quite risky to do so in a cluster with existing installations that could overlap or interfere with our, or your platform. In addition to that, since a kubefirst cluster is based on the GitOps principles, the systems in place could be removed from the cluster if they are not defined in the source of truth, the gitops repository.

One way of using an existing cluster is to go through the process of creating a new management one with kubefirst, and manually creating the proper YAML files in the gitops repository to recreate the same application architecture you already had. It's a manual process that could be tedious depending on the size, and complexity of the system you already have in place. Let us know if you need help or have any questions about it.

info

You can use Helm to install the console application on an existing cluster, which we agree, can be confusing. This will give you access to the console application, which will let you create a new cluster using the UI installation process, but it won't install any other tools inside the cluster you used with Helm.

Does kubefirst add any cloud resources overhead?​

kubefirst adds virtually no overhead when it comes to cloud resources compared to creating a Kubernetes cluster manually and adding all the tools we install, and configure for you. You can find exactly the resources needed for public clouds by kubefirst from the Terraform files in the gitops-template repository in the /<cloud>-<git-provider>/terraform/<cloud>/ folder.

Can I give the gitops repository another name?​

It is not possible right now to have kubefirst create the GitOps repository under another name, nor to easily rename it after the creation. Unfortunately, a lot of parts of our code using the repository's name are hardcoded. We may add this option in the future.

How can I unseal HashiCorp Vault?​

If you are using k3d, for security reasons, HashiCorp Vault may seal itself when you quit Docker, or manually stop the k3d cluster. You can kubefirst k3d unseal-vault to unseal it. In rare cases (when it lose quorum), it may seal itself also with public clouds. To retrieve the root-unseal-key, which you'll have to enter manually, use the following commands:

kubectl -n vault get secrets/vault-unseal-secret --template='{{index .data "root-unseal-key-1"}}' | base64 -d
kubectl -n vault get secrets/vault-unseal-secret --template='{{index .data "root-unseal-key-2"}}' | base64 -d
kubectl -n vault get secrets/vault-unseal-secret --template='{{index .data "root-unseal-key-3"}}' | base64 -d

Terraform is returning a quota limit exceeded error​

If Terraform returns a quota limit exceeded error, please check that your public cloud resources quota limit settings are set above what kubefirst needs to work, and that you still have available resources. More information on resources used. On Civo you can check your quota usage with the kubefirst civo quota, same with AWS on the command line with kubefirst aws quota. This command is not available yet on DigitalOcean, Google Cloud or Vultr.

Do you plan to support technology X?​

kubefirst is an opinionated platform: we install, and configure the tools we think you need to have a production-ready Kubernetes cluster. We also try to keep the initial tooling at a minimum. Everything else that could be useful for your endeavor can either be installed using the GitOps Catalog, or manually added by you using your new gitops repository. If the applications you want isn't in the Catalog, let us know by creating an issue (or in our Slack community), and we'll add it.

With that said, here's a list of requests we got from our users, with some details on the plans to add the technology, or not. Even if the status of the application you would like in kubefirst is not planned, kindly let us know. We are always listening to our community, so if a technology request is popular, we will review our plans to decide if we change our plans.

k0s​

Since we support k3d, we have no plan to support k0s since, as far as we know, the capabilities, especially for our usage, are the same.

Any plans to move away from HashiCorp Vault & Terraform following the license changes & IBM acquisition?​

kubefirst is a commercial but free platform and is not subject to the new commercial restrictions related to the license change to BSL (Business Source License). The restriction is then flowing down to our users so you may be subject to the commercial element of it. As much as we would like to help, we are no legal experts, so we cannot advise you on the topic, but so far, we have seen no issues about this within our community.

As for the IBM acquisition, we are closely keeping track of the situation. So far there is no indication that it will cause any problems for kubefirst. We are fans of HashiCorp Vault, and Terraform, especially with its Atlantis integration, so for now, we have no plans to replace Terraform with OpenTofu or Vault with OpenBao, nor to offer alternatives as options. kubefirst being open source, there is always a way for you to replace those yourself, but we will not be able to provide any help on that matter as it's outside of the normal usage scope.

As with everything we do, we are listening to our users, so if for any reasons, the usage of HashiCorp technologies within our platform is a blocker for you, please let us know. We will keep track of the interest and issues related to this topic, and plan accordingly.

DigitalOcean​

I got an AWS error, but I'm creating a cluster on DigitalOcean. What is this?​

The error can be misleading, but it makes sense as smaller cloud providers, including DigitalOcean, built their storage offering to be S3 compatible, which means that the Terraform provider used for them is also the AWS one. As for the error itself, there's a chance it's because your DO_SPACES_KEY and/or DO_SPACES_SECRET environment variable were not set, or you key isn't valid anymore.