Running Multi-Node Kubernetes Locally with k3d and OrbStack

OrbStack's built-in Kubernetes only supports single-node clusters. If you need multiple nodes to test scheduling or distributed systems, you'd normally switch to k3d or kind and lose OrbStack's automatic domains and TLS. After some experimenting, I found a way to use k3d for multi-node clusters while keeping OrbStack's domain features.

The configuration

Here's the k3d config file that makes this work:

apiVersion: k3d.io/v1alpha5

kind: Simple

metadata:

  name: local

agents: 2

registries:

  create:

    name: local

ports:

  - port: 5642:80

    nodeFilters:

      - loadbalancer

options:

  runtime:

    labels:

      - label: dev.orbstack.domains=*.k3d.local

        nodeFilters:

          - loadbalancer

      - label: dev.orbstack.http-port=80

        nodeFilters:

          - loadbalancer

This creates a cluster with two worker nodes, one control plane, and one load balancer. The key part is the port mapping and the OrbStack labels on the load balancer node.

How it works

The port mapping 5642:80) maps port 5642 on your host to port 80 inside the load balancer container. You don't actually use port 5642 for anything - it just needs to be mapped for the container port to be accessible. I'm not entirely sure why this is necessary (it seems to be something about how k3d's load balancer works internally), but without it, the setup doesn't work.

The OrbStack labels route any request to *.k3d.local to port 80 on the load balancer container, where Traefik handles the ingress traffic.

Using it

Once you've created the cluster with this config, you can create a standard Kubernetes ingress and it'll automatically work with HTTPS locally. Here's an example for ArgoCD:

apiVersion: networking.k8s.io/v1

kind: Ingress

metadata:

  name: argocd-server

  annotations:

    ingress.kubernetes.io/ssl-redirect: "false"

spec:

  rules:

    - host: argocd.k3d.local

      http:

        paths:

          - path: /

            pathType: Prefix

            backend:

              service:

                name: argocd-server

                port:

                  number: 80

After applying this ingress, you can visit https://argocd.k3d.local in your browser and it'll route to your ArgoCD service running in the k3d cluster. OrbStack handles the TLS certificate automatically.