{"id":13929230,"url":"https://github.com/nestybox/kindbox","last_synced_at":"2025-10-04T16:12:23.248Z","repository":{"id":48839457,"uuid":"277208428","full_name":"nestybox/kindbox","owner":"nestybox","description":"Kubernetes in Docker in Sysbox","archived":false,"fork":false,"pushed_at":"2021-10-12T04:44:45.000Z","size":60,"stargazers_count":39,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-03T07:11:19.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nestybox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-05T00:58:09.000Z","updated_at":"2025-03-02T14:55:21.000Z","dependencies_parsed_at":"2022-09-04T22:33:05.923Z","dependency_job_id":null,"html_url":"https://github.com/nestybox/kindbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestybox%2Fkindbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestybox%2Fkindbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestybox%2Fkindbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestybox%2Fkindbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nestybox","download_url":"https://codeload.github.com/nestybox/kindbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254304836,"owners_count":22048480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-07T18:02:11.963Z","updated_at":"2025-10-04T16:12:18.213Z","avatar_url":"https://github.com/nestybox.png","language":"Shell","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"## Introduction\n\nKindbox is a simple open-source tool created by Nestybox to easily create K8s clusters with Docker + Sysbox.\n\nCheck out this [video](https://asciinema.org/a/VCgF094wb4CuVeI8h3iDKhh5m?speed=1.75).\n\n\u003cp align=\"center\"\u003e\u003cimg alt=\"sysbox\" src=\"docs/figures/kindbox.png\" width=\"800x\" /\u003e\u003c/p\u003e\n\nKindbox does some of the same things that the K8s.io KinD tool does (e.g., cluster\ncreation, destruction, etc.) but it's much simpler, more flexible, does not\nrequire complex container images, and it's even more efficient.\n\nKindbox is not meant to compete with the K8s.io KinD tool. Rather, it's meant to\nprovide a reference example of how easy it is to deploy a K8s cluster inside\ncontainers when using the Sysbox container runtime.\n\nKindbox is a simple bash script wrapper around Docker commands. Feel free to\nmodify it to fit your needs.\n\n## Kindbox Simplicity \u0026 Flexibility\n\nKindbox is a very simple and flexible tool: it's a bash script wrapper around\nDocker commands that create, destroy, and resize a Kubernetes-in-Docker cluster.\n\nThat is, Kindbox talks to Docker, Docker talks to Sysbox, and Sysbox creates or\ndestroys the containers.\n\nThe reason the tool is so simple is that the Sysbox container runtime creates\nthe containers such that they can run K8s seamlessly inside. Thus, Kindbox need\nonly deploy the containers with Docker and run `kubeadm` within them to set them\nup. **It's that easy**.\n\nFor this same reason, no specialized Docker images are needed for the containers\nthat act as K8s nodes. In other words, the K8s node image does not require\ncomplex entrypoints or complex Docker commands for its deployment.\n\nThis in turn enables you to fully control the contents of the images that make\nup the k8s nodes, as well as the process for launching the K8s cluster.\n\n## Using Kindbox\n\nBy default, Kindbox uses a Docker image called `nestybox/k8s-node` for the containers\nthat make up the cluster.\n\nIt's a simple image that includes systemd, Docker, the K8s `kubeadm` tool, and\npreloaded inner pod images for the K8s control plane.\n\nThe Dockerfile is [here](https://github.com/nestybox/dockerfiles/tree/master/k8s-node)\n\nFeel free to copy it and customize it per your needs.\n\n### Cluster Creation\n\n1) Create a cluster called `mycluster` with 10 nodes (1 master + 9 workers):\n\n```console\n$ kindbox create --num-workers=9 mycluster\n\nCreating a K8s cluster with Docker + Sysbox ...\n\nCluster name             : mycluster\nWorker nodes             : 9\nDocker network           : mycluster-net\nNode image               : nestybox/k8s-node:v1.18.2\nK8s version              : v1.18.2\nPublish apiserver port   : false\n\nCreating the K8s cluster nodes ...\n  - Creating node mycluster-master\n  - Creating node mycluster-worker-0\n  - Creating node mycluster-worker-1\n  - Creating node mycluster-worker-2\n  - Creating node mycluster-worker-3\n  - Creating node mycluster-worker-4\n  - Creating node mycluster-worker-5\n  - Creating node mycluster-worker-6\n  - Creating node mycluster-worker-7\n  - Creating node mycluster-worker-8\n\nInitializing the K8s master node ...\n  - Running kubeadm init on mycluster-master ... (may take up to a minute)\n  - Setting up kubectl on mycluster-master ...\n  - Initializing networking (flannel) on mycluster-master ...\n  - Waiting for mycluster-master to be ready ...\n\nInitializing the K8s worker nodes ...\n  - Joining the worker nodes to the cluster ...\n\nCluster created successfully!\n\nUse kubectl to control the cluster.\n\n1) Install kubectl on your host\n2) export KUBECONFIG=${KUBECONFIG}:${HOME}/.kube/mycluster-config\n3) kubectl config use-context kubernetes-admin@mycluster\n4) kubectl get nodes\n\nAlternatively, use \"docker exec\" to control the cluster:\n\n$ docker exec mycluster-master kubectl get nodes\n```\n\nThis takes Kindbox less than 2 minutes and consumes \u0026lt; 1GB overhead on my laptop\nmachine!\n\nIn contrast, this same cluster requires 2.5GB when using K8s.io KinD +\nSysbox, and 10GB when using K8s.io KinD without Sysbox.\n\nThis means that with Sysbox, you can deploy large and/or more K8s clusters on\nyour machine quickly and without eating up your disk space.\n\n2) Setup kubectl on the host so we can control the cluster:\n\n(This assumes you've [installed kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) on your host).\n\n```console\n$ export KUBECONFIG=${KUBECONFIG}:${HOME}/.kube/mycluster-config\n\n$ kubectl config use-context kubernetes-admin@mycluster\nSwitched to context \"kubernetes-admin@mycluster\".\n```\n\n3) Use kubectl to verify all is good:\n\n```console\n$ kubectl get nodes\nNAME                 STATUS   ROLES    AGE     VERSION\nmycluster-master     Ready    master   4m43s   v1.18.3\nmycluster-worker-0   Ready    \u003cnone\u003e   3m51s   v1.18.3\nmycluster-worker-1   Ready    \u003cnone\u003e   3m53s   v1.18.3\nmycluster-worker-2   Ready    \u003cnone\u003e   3m52s   v1.18.3\nmycluster-worker-3   Ready    \u003cnone\u003e   3m53s   v1.18.3\nmycluster-worker-4   Ready    \u003cnone\u003e   3m51s   v1.18.3\nmycluster-worker-5   Ready    \u003cnone\u003e   3m52s   v1.18.3\nmycluster-worker-6   Ready    \u003cnone\u003e   3m50s   v1.18.3\nmycluster-worker-7   Ready    \u003cnone\u003e   3m50s   v1.18.3\nmycluster-worker-8   Ready    \u003cnone\u003e   3m50s   v1.18.3\n```\n\nFrom here on, we use kubectl as usual to deploy pods, services, etc.\n\nFor example, to create an nginx deployment with 10 pods:\n\n```console\n$ kubectl create deployment nginx --image=nginx\n$ kubectl scale --replicas=10 deployment nginx\n$ kubectl get pods -o wide\nNAME                    READY   STATUS    RESTARTS   AGE   IP            NODE                 NOMINATED NODE   READINESS GATES\nnginx-f89759699-6ch9m   1/1     Running   0          21s   10.244.11.4   mycluster-worker-6   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-8jrc8   1/1     Running   0          21s   10.244.10.4   mycluster-worker-5   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-dgxq8   1/1     Running   0          28s   10.244.2.15   mycluster-worker-1   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-hx5tt   1/1     Running   0          21s   10.244.5.15   mycluster-worker-3   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-l9v5p   1/1     Running   0          21s   10.244.1.10   mycluster-worker-0   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-pdnhb   1/1     Running   0          21s   10.244.12.4   mycluster-worker-4   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-qf46b   1/1     Running   0          21s   10.244.2.16   mycluster-worker-1   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-vbnx5   1/1     Running   0          21s   10.244.3.14   mycluster-worker-2   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-whgt7   1/1     Running   0          21s   10.244.13.4   mycluster-worker-8   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-zblsb   1/1     Running   0          21s   10.244.14.4   mycluster-worker-7   \u003cnone\u003e           \u003cnone\u003e\n```\n\n### Cluster Network\n\nWith Kindbox, you have full control over the container network used by the\ncluster.\n\nFor example, you can deploy the cluster on a Docker network that you create:\n\n    $ docker network create mynet\n    $ kindbox create --num-workers=9 --net mynet mycluster\n\nNormally each cluster would be on a dedicated network for extra isolation, but\nit's up to you to decide. If you don't choose a network, Kindbox automatically\ncreates one for the cluster (with the name `\u003ccluster-name\u003e-net`).\n\n### Cluster Resizing\n\nKindbox also allows you to easily resize the cluster (i.e., add or remove worker\nnodes).\n\nHere we resize the cluster we previously created from 9 to 4 worker nodes.\n\n```console\n$ kindbox resize --num-workers=4 mycluster\n\nResizing the K8s cluster (current = 9, desired = 4) ...\n  - Destroying node mycluster-worker-4\n  - Destroying node mycluster-worker-5\n  - Destroying node mycluster-worker-6\n  - Destroying node mycluster-worker-7\n  - Destroying node mycluster-worker-8\nDone (5 nodes removed)\n```\n\nThen verify K8s no longer sees the removed nodes:\n\n```console\n$ kubectl get nodes\nNAME                 STATUS   ROLES    AGE   VERSION\nmycluster-master     Ready    master   32m   v1.18.3\nmycluster-worker-0   Ready    \u003cnone\u003e   31m   v1.18.3\nmycluster-worker-1   Ready    \u003cnone\u003e   31m   v1.18.3\nmycluster-worker-2   Ready    \u003cnone\u003e   31m   v1.18.3\nmycluster-worker-3   Ready    \u003cnone\u003e   31m   v1.18.3\n```\n\nYou can also verify K8s has re-scheduled the pods away to the remaining nodes:\n\n```console\n$ kubectl get pods -o wide\nNAME                    READY   STATUS    RESTARTS   AGE   IP            NODE                 NOMINATED NODE   READINESS GATES\nnginx-f89759699-dgxq8   1/1     Running   0          10m   10.244.2.15   mycluster-worker-1   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-hx5tt   1/1     Running   0          10m   10.244.5.15   mycluster-worker-3   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-l6l7b   1/1     Running   0          28s   10.244.5.16   mycluster-worker-3   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-l9v5p   1/1     Running   0          10m   10.244.1.10   mycluster-worker-0   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-nbd2l   1/1     Running   0          28s   10.244.2.17   mycluster-worker-1   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-qf46b   1/1     Running   0          10m   10.244.2.16   mycluster-worker-1   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-rfklb   1/1     Running   0          28s   10.244.1.11   mycluster-worker-0   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-tr9tr   1/1     Running   0          28s   10.244.1.12   mycluster-worker-0   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-vbnx5   1/1     Running   0          10m   10.244.3.14   mycluster-worker-2   \u003cnone\u003e           \u003cnone\u003e\nnginx-f89759699-xvx52   1/1     Running   0          28s   10.244.3.15   mycluster-worker-2   \u003cnone\u003e           \u003cnone\u003e\n```\n\nWhen resizing the cluster upwards, Kindbox allows you to choose the container\nimage for newly added K8s nodes:\n\n```console\n$ kindbox resize --num-workers=5 --image=\u003cmy-special-node\u003e mycluster\n```\n\nThis means you can have a K8s cluster with a mix of different node images. This\nis useful if you need some specialized K8s nodes.\n\n### Multiple Clusters\n\nYou can easily create multiple K8s clusters on the host by repeating the\n`kindbox create` command (step (1) above).\n\nAnd you can use `kubectl config use-context` to point to the cluster you wish to\nmanage (see step (2) above).\n\nOn my laptop (4 CPU \u0026 8GB RAM), I am able to create three small clusters without\nproblem:\n\n```console\n$ kindbox list -l\nNAME                   WORKERS         NET                  IMAGE                          K8S VERSION\ncluster3               5               cluster3-net         nestybox/k8s-node:v1.18.2      v1.18.2\ncluster2               5               cluster2-net         nestybox/k8s-node:v1.18.2      v1.18.2\nmycluster              4               mycluster-net        nestybox/k8s-node:v1.18.2      v1.18.2\n```\n\nWith Sysbox, the clusters are well isolated from each other: the K8s nodes are in\ncontainers strongly secured via the Linux user namespace, and each cluster is in\na dedicated Docker network (for traffic isolation).\n\n### Cluster Destruction\n\nTo destroy a cluster, simply type:\n\n```console\n$ kindbox destroy mycluster\nDestroying K8s cluster \"mycluster\" ...\n  - Destroying node mycluster-worker-0\n  - Destroying node mycluster-worker-1\n  - Destroying node mycluster-worker-2\n  - Destroying node mycluster-worker-3\n  - Destroying node mycluster-master\n\nCluster destroyed. Remove stale entry from $KUBECONFIG env-var by doing ...\n\n  export KUBECONFIG=`echo ${KUBECONFIG} | sed \"s|:${HOME}/.kube/mycluster-config||\"`\n```\n\nTo see what else you can do with Kindbox, type `kindbox help`.\n\nAnd remember, it should be fairly easy to add functionality to Kindbox, as it's\njust a bash wrapper around Docker commands that manage the cluster.\n\nIf you would like Nestybox to add more functionality, please file an\n[issue](docs/issue-guidelines.md) in the Sysbox Github repo, or [contact us](#support).\n\n## Support\n\nReach us at our [slack channel][slack] or at `contact@nestybox.com` for any questions.\nSee our [contact info](#contact) below for more options.\n\n## About Nestybox\n\n[Nestybox](https://www.nestybox.com) enhances the power of Linux containers.\n\nWe are developing software that enables containers to run **any type of\nworkload** (not just micro-services), and do so easily and securely.\n\nOur mission is to provide users with a fast, efficient, easy-to-use, and secure\nalternative to virtual machines for deploying virtual hosts on Linux.\n\n## Contact\n\nWe are happy to help. You can reach us at:\n\nEmail: `contact@nestybox.com`\n\nSlack: [Nestybox Slack Workspace][slack]\n\nPhone: 1-800-600-6788\n\nWe are there from Monday-Friday, 9am-5pm Pacific Time.\n\n## Thank You\n\nWe thank you **very much** for using Kindbox. We hope you find it useful.\n\nYour trust in us is very much appreciated.\n\n\\-- _The Nestybox Team_\n\n[slack]: https://join.slack.com/t/nestybox-support/shared_invite/enQtOTA0NDQwMTkzMjg2LTAxNGJjYTU2ZmJkYTZjNDMwNmM4Y2YxNzZiZGJlZDM4OTc1NGUzZDFiNTM4NzM1ZTA2NDE3NzQ1ODg1YzhmNDQ\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnestybox%2Fkindbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnestybox%2Fkindbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnestybox%2Fkindbox/lists"}