Skip to content

Quick Start

This quick start (15-30min) walks you through kubara's local test setup for evaluation purposes.

It is intended for local testing only, not for production use.

This guide supports Linux, macOS and WSL on Windows.

Prerequisites

Install kubara first via the installation guide, then make sure these tools are available on your host:

1. Create a GitOps repository

Create a new GitHub or GitLab repository with your own account. This repository will act as your GitOps repo and stores the desired state of your platform. If you want more background, see What is GitOps?.

We recommend making the repository public for the local evaluation flow. Otherwise you also need to create a Personal Access Token (PAT) for Argo CD:

Run the remaining steps from inside that repository.

2. Generate the .env file

kubara init --prep --local

This creates the local evaluation .env template.

2026-06-11 12:37:42 INF ✓ copied prep file file=/Users/<user>/kubara-local/.gitignore
2026-06-11 12:37:42 INF Generated local-evaluation dotenv in path: /Users/<user>/kubara-local/.env

3. Update the Argo CD settings

Open the generated .env file and change:

  • ARGOCD_WIZARD_ACCOUNT_PASSWORD to magic
  • the Argo CD repository URL to your GitOps repository URL
  • if your repository is private, also add your PAT

4. Generate config.yaml

kubara init --local

This creates config.yaml. For this local flow you do not need to change it yet, but it is worth looking through once: it defines your cluster profile and the services Argo CD will manage for that cluster.

2026-06-11 12:39:00 INF ✓ copied prep file file=/Users/<user>/kubara-local/.gitignore
2026-06-11 12:39:00 INF Skipping dotenv creation. File exist: /Users/<user>/kubara-local/.env
2026-06-11 12:39:00 INF Generated local-evaluation config in path: /Users/<user>/kubara-local/config.yaml

5. Bootstrap the local cluster

Run the bootstrap command. It will do the following:

  • creates a local kind cluster named test-cluster
  • installs the required CRDs and namespaces
  • installs and configures Argo CD
  • installs OpenBao as the local secret engine (we highly recommend to use a managed service for this in a production environment)
  • applies less strict defaults for local testing and generates local deployment values
  • creates the placeholder Traefik LoadBalancer service
  • waits for you to start cloud-provider-kind manually so the local LoadBalancer IP can be assigned

After that, Argo CD takes over the ongoing deployments. kubara is a bootstrap and generation tool, not a runtime controller.

Run the bootstrapping: 

kubara bootstrap --local test-cluster

Wait until you see this on the screen: 

...
2026-06-11 12:39:53 INF Creating kind cluster cluster=test-cluster
2026-06-11 12:40:01 INF Connecting to the local Kubernetes cluster
2026-06-11 12:40:01 INF Creating local Traefik bootstrap namespace and placeholder LoadBalancer service
2026-06-11 12:40:01 INF Waiting for the local Traefik LoadBalancer IP
2026-06-11 12:40:01 INF
Now start cloud-provider-kind in another terminal with: sudo cloud-provider-kind

And then start cloud-provider-kind in another terminal: 

sudo cloud-provider-kind

Cloud-Provider-Kind works by automatically allocating a local IP address in the range of your Docker network for each Service of type LoadBalancer. For example in the next steps you will see 172.18.0.3. It will most likely be different for your local environment.

kubara should then continue with the bootstrapping after just a couple seconds (If not look into the Troubleshooting section at the bottom of this page):

...
2026-06-11 12:41:17 INF Bootstrapping ArgoCD
2026-06-11 12:41:18 INF ArgoCD manifest applied successfully
2026-06-11 12:41:18 INF Waiting for ArgoCD components to be ready
2026-06-11 12:42:02 INF ArgoCD components are ready
2026-06-11 12:42:02 INF
🎉 Local kubara bootstrap complete!

📝 Next steps:
1. Commit and push all repository contents generated by kubara.
2. Ensure the Git repository is reachable by Argo CD.
   If you did not provide both ARGOCD_GIT_USERNAME and ARGOCD_GIT_PAT_OR_PASSWORD, ensure the Git repository is public so Argo CD can pull it.

Argo CD should be reachable in a couple of minutes via:
    https://172.18.0.3.traefik.me/argocd

You can otherwise immediately access the Argo CD UI via:
    kubectl --kubeconfig .local/kind.kubeconfig port-forward svc/argocd-server -n argocd 8080:443
    then open http://localhost:8080/argocd in your browser

Log in with:
    wizard / magic

Other useful links:
  - Portal:  https://172.18.0.3.traefik.me
  - OpenBao: https://openbao.172.18.0.3.traefik.me/ui login with root


2026-06-11 12:42:02 INF ArgoCD bootstrap completed successfully

6. What's next?

One more step and you should have a running platform in the next couple of minutes. Read the instructions in your terminal, they will look similar to the example in the section above but most likely with a different ip range.

They essentially give instructions to do the following:

  1. IMPORTANT: Commit and push all repository contents generated by kubara.
  2. Once more ensure the Git repository is reachable by Argo CD. If you did not provide both ARGOCD_GIT_USERNAME and ARGOCD_GIT_PAT_OR_PASSWORD, ensure the Git repository is public so Argo CD can pull it.
  3. Wait a few minutes until Argo CD syncs the applications from your repository or force a refresh via the UI.
    • Connect to ArgoCD via port-forwarding and open http://localhost:8080/argocd
    • Open Argo CD and check whether all apps become Healthy and Synced. (Maybe force a refresh)
    • Open Argo CD Settings -> Repositories and check whether Argo can access your repository (is it public? is your pat correct?)
  4. Once the platform components are ready, open the exposed UIs through the local ingress host.
  5. You should be able to reach the kubara Developer Portal via https://<your-ip>.traefik.me

If Argo CD cannot fetch your repository, double-check the repository URL and credentials in your .env. If you did not provide Git credentials, the repository must be public for this local evaluation flow.

7. Understanding the generated files

After the bootstrap finished, you will usually see three important areas in your repository:

  • managed-service-catalog/: the generated Helm charts and shared templates Argo CD uses for deployments
  • customer-service-catalog/: the cluster-specific values that describe what should run on test-cluster
  • .local/: local runtime artifacts used only for the evaluation environment

The .local/ directory is not part of your GitOps state. It only contains helper files for your local machine, for example:

  • kind.kubeconfig: kubeconfig for the local kind cluster
  • kind-config.yaml: the kind cluster definition used during bootstrap
  • generate.env: the environment snapshot kubara used for local generation
  • openbao/: temporary local Helm values for the OpenBao bootstrap step
  • external-secrets/: the generated local ClusterSecretStore manifest

You can inspect the local cluster with the dedicated kubeconfig:

kubectl --kubeconfig .local/kind.kubeconfig get pods -A
kubectl --kubeconfig .local/kind.kubeconfig get ingress -A
kubectl --kubeconfig .local/kind.kubeconfig get applications -n argocd

For more details about the directory and file structure have a look at the concept pages: - Overview of Core Concepts - What is a Catalog - How the local kind preset works - How to create your own Catalog - How to add an Application - How to add an AppSet

Troubleshooting

macOS + Colima

On macOS using Colima the bootstrapping might get stuck due to a combination of bugs in cloud-provider-kind and lima-guest-agent.

  1. If your bootstrap command doesn't proceed beyond this point: 
    2026-06-11 10:45:35 INF Creating local Traefik bootstrap namespace and placeholder LoadBalancer service
2026-06-11 10:45:35 INF Waiting for the local Traefik LoadBalancer IP
  2. Restart cloud-provider-kind
  3. If the process still gets stuck, watch the cloud-provider-kind terminal output. Repeat this step if needed. You should no longer see failing readiness checks like: 
    I0611 10:51:09.391260   94008 proxy.go:342] unexpected error trying to get load balancer kindccm-6c8d6f6b98d6 readiness :Get "http://127.0.0.1:32810/ready": EOF
I0611 10:51:10.390284   94008 proxy.go:342] unexpected error trying to get load balancer kindccm-6c8d6f6b98d6 readiness :Get "http://127.0.0.1:32810/ready": EOF
I0611 10:51:11.393015   94008 proxy.go:342] unexpected error trying to get load balancer kindccm-6c8d6f6b98d6 readiness :Get "http://127.0.0.1:32810/ready": EOF
I0611 10:51:12.393818   94008 proxy.go:342] unexpected error trying to get load balancer kindccm-6c8d6f6b98d6 readiness :Get "http://127.0.0.1:32810/ready": EOF
  4. Otherwise restart cloud-provider-kind again

OpenBao only runs with in-memory

OpenBao runs with its dev mode for lax evaluation purposes. This causes the following:

  • It only runs with an in-memory database and with a restart its pod, runtime or host system its database will be lost and you will have to rerun: kubara bootstrap --local test-cluster
  • The instance is not secure and always unsealed
  • The instances root token is not a random string but instead always root

How to clean up your local environment

When you are done with the evaluation, remove the local cluster and stop cloud-provider-kind.

  1. Removes the Kubernetes cluster itself: 

    kind delete cluster --name test-cluster

  2. Stop cloud-provider-kind If you started it in a separate terminal with sudo cloud-provider-kind, stop it there with Ctrl+C. 

    # in the terminal where cloud-provider-kind is running
Ctrl+C

Optional: check whether the local LoadBalancer IP is still attached. Sometimes the LoadBalancer IP added by cloud-provider-kind may still be present on the loopback device after cleanup. This is optional to fix and usually disappears after a reboot anyway.

Check whether the IP is still present:

ip addr show lo

If needed, remove it manually:

sudo ip addr del <your-ip>/32 dev lo

Check the loopback aliases:

ifconfig lo0

If needed, remove the alias manually:

sudo ifconfig lo0 -alias <your-ip>

Replace <your-ip> with the address you saw during bootstrap, for example 172.18.0.3.