Skip to main content
Version: 2.6

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.

k3d​

Cannot connect to the Docker daemon​

Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

If Docker is running, and working properly (run docker run hello-world in your terminal to test it), but you get the error above while trying to create a cluster with k3d, it may be related to this Docker issue. It was fixed a while ago, but it seems like the problem is back. Since it's a Docker issue, and that the Unix sockets default path should be /var/run/docker.sock, you can specify the path using the DOCKER_HOST variable:

export DOCKER_HOST="unix://$HOME/.docker/run/docker.sock"

Using Rancher Desktop Instead of Docker Desktop​

Firstly, you need to disable Traefik in your Rancher Desktop because our installation uses Traefik and port forwarding. Between the conflicts and the double routing, it's just easier to disable Traefik on Rancher Desktop.

macOS (Apple Silicon)​

This is experimental. It works, but all of the features it uses are considered beta or experimental by Rancher Desktop.

For Apple Silicon macOS, you need to enable a few features in Rancher Desktop before this works. Run the following command in your terminal:

rdctl set --container-engine.name docker \
    --kubernetes.options.traefik=false \
    --experimental.virtual-machine.type vz \
    --experimental.virtual-machine.use-rosetta=true \
    --experimental.virtual-machine.mount.type virtiofs \
    --experimental.virtual-machine.socket-vmnet=true

If you have any issues, reach out to us on our Slack community.

macOS (Intel)​

Not yet tested.

Windows Subsystem for Linux (WSL) on Windows​

Rancher Desktop is not yet supported but Docker Desktop is with WSL on Windows. There are limitations within Rancher Desktop and how it manages volumes which prevent us from supporting it at this moment.

Using nerdctl Instead of Docker​

Creation via nerdctl isn't supported yet. k3d doesn't fully support it probably because it doesn't have an API that is publicly exposed like the Docker daemon. We need k3d to support nerdctl and containerd on WSL before we can add support in kubefirst.

Using Lima Instead of Docker Desktop​

We didn't try kubefirst k3d cluster creation with Lima yet. If you are using it, let us know how it's working, and if you think it's something we can support with the existing codebase.