{"id":19838531,"url":"https://github.com/metal-stack/mini-lab","last_synced_at":"2025-04-09T07:10:35.994Z","repository":{"id":37443934,"uuid":"239508913","full_name":"metal-stack/mini-lab","owner":"metal-stack","description":"a small, virtual setup to locally run the metal-stack","archived":false,"fork":false,"pushed_at":"2024-11-26T14:59:21.000Z","size":18487,"stargazers_count":57,"open_issues_count":25,"forks_count":12,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-12-04T10:43:41.635Z","etag":null,"topics":["ansible","bare-metal","cumulus-vx","metal","vagrant"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metal-stack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-10T12:41:04.000Z","updated_at":"2024-11-22T12:18:08.000Z","dependencies_parsed_at":"2024-04-15T11:14:09.420Z","dependency_job_id":"3d749bf0-4f28-446d-9de9-e07eba9f398b","html_url":"https://github.com/metal-stack/mini-lab","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fmini-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fmini-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fmini-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fmini-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metal-stack","download_url":"https://codeload.github.com/metal-stack/mini-lab/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994122,"owners_count":21030050,"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":["ansible","bare-metal","cumulus-vx","metal","vagrant"],"created_at":"2024-11-12T12:18:04.961Z","updated_at":"2025-04-09T07:10:35.965Z","avatar_url":"https://github.com/metal-stack.png","language":"Python","readme":"# mini-lab\n\nThe mini-lab is a small, virtual setup to locally run the metal-stack. It deploys the metal control plane and a metal-stack partition with two simulated leaf switches. The lab can be used for trying out metal-stack, demonstration purposes or development.\n\n![overview components](docs/overview.png)\n\nℹ This project can also be used as a template for writing your own metal-stack deployments.\n\n\u003c!-- TOC depthfrom:2 depthto:6 withlinks:true updateonsave:false orderedlist:false --\u003e\n\n- [Requirements](#requirements)\n- [Known Limitations](#known-limitations)\n- [Try it out](#try-it-out)\n    - [Reinstall machine](#reinstall-machine)\n    - [Free machine](#free-machine)\n- [Flavors](#flavors)\n- [Network Topology](#network-topology)\n\n\u003c!-- /TOC --\u003e\n\n## Requirements\n\n- Linux machine with hardware virtualization support\n- kvm as hypervisor for the VMs (you can check through the `kvm-ok` command)\n- [docker](https://www.docker.com/) \u003e= 24.x.y (for using kind and our deployment base image)\n- [kind](https://github.com/kubernetes-sigs/kind/releases) == v0.23.0 (for hosting the metal control plane)\n- [containerlab](https://containerlab.dev/install/) \u003e= v0.56.0\n- the lab creates a docker network on your host machine with the address block `203.0.113.0/24`, designated as TEST-NET-3 for documentation and examples.\n- (recommended) haveged to have enough random entropy (only needed if the PXE process does not work)\n\nHere is some code that should help you to set up most of the requirements:\n\n ```bash\n# If UFW enabled.\n# Disable the firewall or allow traffic through Docker network IP range.\nsudo ufw status\nsudo ufw allow from 172.17.0.0/16\n\n# Install kvm\nsudo apt install -y git curl qemu qemu-kvm haveged\n\n# Install Docker\ncurl -fsSL https://get.docker.com | sh\n# if you want to be on the safe side, follow the original installation\n# instructions at https://docs.docker.com/engine/install/ubuntu/\n\n# Ensure that your user is member of the group \"docker\"\n# you need to login again in order to make this change take effect\nsudo usermod -G docker -a ${USER}\n\n# Install containerlab\nbash -c \"$(curl -sL https://get.containerlab.dev)\"\n\n# Install kind (kubernetes in docker), for more details see https://kind.sigs.k8s.io/docs/user/quick-start/#installation\nsudo curl -Lo /usr/local/bin/kind \"https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64\"\nsudo chmod +x /usr/local/bin/kind\n```\n\nThe following ports are used statically on your host machine:\n\n| Port | Bind Address | Description                        |\n|:----:|:------------ |:---------------------------------- |\n| 6443 |   0.0.0.0    | kube-apiserver of the kind cluster |\n| 4443 |   0.0.0.0    | HTTPS ingress                      |\n| 4150 |   0.0.0.0    | nsqd                               |\n| 8080 |   0.0.0.0    | HTTP ingress                       |\n\n## Known Limitations\n\n- to keep the demo small there is no EVPN\n- machine restart and destroy does not work because we cannot change the boot order via IPMI in the lab easily (virtual-bmc could, but it's buggy)\n- login to the machines is possible with virsh console, login to the firewall is possible with SSH from your local machine\n\n## Try it out\n\n```bash\ngit clone https://github.com/metal-stack/mini-lab.git\ncd mini-lab\n```\n\nStart the mini-lab with a kind cluster, a metal-api instance as well as two containers wrapping leaf switches and another container that hosts two user-allocatable machines:\n\n```bash\nmake\n# containerlab will ask you for root permissions (https://github.com/srl-labs/containerlab/issues/669)\n```\n\nAfter the deployment and waiting for a short amount of time, two machines in status `PXE booting` become visible through `metalctl machine ls`:\n\n```bash\ndocker compose run --rm metalctl machine ls\n\nID                                          LAST EVENT   WHEN     AGE  HOSTNAME  PROJECT  SIZE          IMAGE  PARTITION\n00000000-0000-0000-0000-000000000001        PXE Booting  3s\n00000000-0000-0000-0000-000000000002        PXE Booting  5s\n```\n\nWait until the machines reach the waiting state:\n\n```bash\ndocker compose run --rm metalctl machine ls\n\nID                                          LAST EVENT   WHEN     AGE  HOSTNAME  PROJECT  SIZE          IMAGE  PARTITION\n00000000-0000-0000-0000-000000000001        Waiting      8s                               v1-small-x86         mini-lab\n00000000-0000-0000-0000-000000000002        Waiting      8s                               v1-small-x86         mini-lab\n```\n\nCreate a firewall and a machine with:\n\n```bash\nmake firewall\nmake machine\n```\n\n__Alternatively__, you may want to issue the `metalctl` commands on your own:\n\n```bash\ndocker compose run --rm metalctl network allocate \\\n        --partition mini-lab \\\n        --project 00000000-0000-0000-0000-000000000000 \\\n        --name user-private-network\n\n# lookup the network ID and create a machine\ndocker compose run --rm metalctl machine create \\\n        --description test \\\n        --name machine \\\n        --hostname machine \\\n        --project 00000000-0000-0000-0000-000000000000 \\\n        --partition mini-lab \\\n        --image ubuntu-24.4 \\\n        --size v1-small-x86 \\\n        --networks \u003cnetwork-ID\u003e\n\n# create a firewall that is also connected to the virtual internet-mini-lab network\ndocker compose run --rm metalctl machine create \\\n        --description fw \\\n        --name fw \\\n        --hostname fw \\\n        --project 00000000-0000-0000-0000-000000000000 \\\n        --partition mini-lab \\\n        --image firewall-ubuntu-3.0 \\\n        --size v1-small-x86 \\\n        --networks internet-mini-lab,$(privatenet)\n```\n\nSee the installation process in action\n\n```bash\nmake console-machine01/02\n...\nUbuntu 24.04 machine ttyS0\n\nmachine login:\n```\n\nTwo machines are now installed and have status \"Phoned Home\"\n\n```bash\ndocker compose run --rm metalctl machine ls\nID                                          LAST EVENT   WHEN   AGE     HOSTNAME  PROJECT                               SIZE          IMAGE               PARTITION\n00000000-0000-0000-0000-000000000001        Phoned Home  2s     21s     machine   00000000-0000-0000-0000-000000000000  v1-small-x86  Ubuntu 24.04        mini-lab\n00000000-0000-0000-0000-000000000002        Phoned Home  8s     18s     fw        00000000-0000-0000-0000-000000000000  v1-small-x86  Firewall 3 Ubuntu   mini-lab\n```\n\nLogin with user name metal and the console password from\n\n```bash\ndocker compose run --rm metalctl machine consolepassword 00000000-0000-0000-0000-000000000001\n```\n\nTo remove the kind cluster, the switches and machines, run:\n\n```bash\nmake cleanup\n```\n\n### Reinstall machine\n\nReinstall a machine with\n\n```bash\ndocker compose run --rm metalctl machine reinstall \\\n        --image ubuntu-24.4 \\\n        00000000-0000-0000-0000-000000000001\n```\n\n### Free machine\n\nFree a machine with `make free-machine01` or\n\n```bash\ndocker compose run --rm metalctl machine rm 00000000-0000-0000-0000-000000000001\n```\n\n## Flavors\n\nThere are two versions, or flavors, of the mini-lab environment which differ in regards to the NOS running on the leaves:\n\n- `cumulus`: runs 2 Cumulus switches.\n- `sonic`: runs 2 SONiC switches\n- `capms`: runs the SONiC flavor but with three instead of two machines (this is used for  [cluster-provider-metal-stack](https://github.com/metal-stack/cluster-api-provider-metal-stack) in order to have dedicated hosts for control plane / worker / firewall)\n- `gardener`: installs the [Gardener](https://gardener.cloud) in the mini-lab\n\nIn order to start specific flavor, you can define the flavor as follows:\n\n```bash\nexport MINI_LAB_FLAVOR=sonic\nmake\n```\n\n## Network topology\n\nAn Nginx is running inside of the www container to allow automatic testing of outgoing connections.\n\n![Network topology](docs/network.svg)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fmini-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetal-stack%2Fmini-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fmini-lab/lists"}