From 16351394c8fa9ebc116b3f8f5a6c3c386c05b183 Mon Sep 17 00:00:00 2001 From: Jacob Weinstock Date: Thu, 27 Jun 2024 08:36:33 -0600 Subject: [PATCH] Move each playground and readme to its own directory: Signed-off-by: Jacob Weinstock --- README.md | 109 +----------------- capt/README.md | 63 ++++++++++ capt/config.yaml | 4 +- stack/README.md | 40 +++++++ .../docs}/quickstarts/KUBERNETES.md | 0 .../docs}/quickstarts/VAGRANTLVIRT.md | 2 +- .../docs}/quickstarts/VAGRANTVBOX.md | 2 +- {vagrant => stack/vagrant}/.env | 0 {vagrant => stack/vagrant}/Vagrantfile | 0 {vagrant => stack/vagrant}/hardware.yaml | 0 {vagrant => stack/vagrant}/setup.sh | 0 {vagrant => stack/vagrant}/template.yaml | 0 .../vagrant}/ubuntu-download.yaml | 0 {vagrant => stack/vagrant}/workflow.yaml | 0 14 files changed, 110 insertions(+), 110 deletions(-) create mode 100644 capt/README.md create mode 100644 stack/README.md rename {docs => stack/docs}/quickstarts/KUBERNETES.md (100%) rename {docs => stack/docs}/quickstarts/VAGRANTLVIRT.md (99%) rename {docs => stack/docs}/quickstarts/VAGRANTVBOX.md (99%) rename {vagrant => stack/vagrant}/.env (100%) rename {vagrant => stack/vagrant}/Vagrantfile (100%) rename {vagrant => stack/vagrant}/hardware.yaml (100%) rename {vagrant => stack/vagrant}/setup.sh (100%) rename {vagrant => stack/vagrant}/template.yaml (100%) rename {vagrant => stack/vagrant}/ubuntu-download.yaml (100%) rename {vagrant => stack/vagrant}/workflow.yaml (100%) diff --git a/README.md b/README.md index 0ad27e32..c353569b 100644 --- a/README.md +++ b/README.md @@ -1,110 +1,7 @@ # Playground -This playground repository holds example deployments for use in learning and testing. +Welcome to the Tinkerbell Playground! This playground repository holds example deployments for use in learning and testing. The following playgrounds are available: -- [Tinkerbell stack playground](#tinkerbell-stack-playground) -- [Cluster API Provider Tinkerbell (CAPT) playground](#cluster-api-provider-tinkerbell-capt-playground) - -## Tinkerbell Stack Playground - -The following section containers the Tinkerbell stack playground instructions. It is not a production reference architecture. -Please use the [Helm chart](https://github.com/tinkerbell/charts) for production deployments. - -### Quick-Starts - -The following quick-start guides will walk you through standing up the Tinkerbell stack. -There are a few options for this. -Pick the one that works best for you. - -### Options - -- [Vagrant and VirtualBox](docs/quickstarts/VAGRANTVBOX.md) -- [Vagrant and Libvirt](docs/quickstarts/VAGRANTLVIRT.md) -- [Kubernetes](docs/quickstarts/KUBERNETES.md) - -### Next Steps - -By default the Vagrant quickstart guides automatically install Ubuntu on the VM (machine1). You can provide your own OS template. To do this: - -1. Login to the stack VM - - ```bash - vagrant ssh stack - ``` - -1. Add your template. An example Template object can be found [here](https://github.com/tinkerbell/tink/tree/main/config/crd/examples/template.yaml) and more Template documentation can be found [here](https://tinkerbell.org/docs/concepts/templates/). - - ```bash - kubectl apply -f my-OS-template.yaml - ``` - -1. Create the workflow. An example Workflow object can be found [here](https://github.com/tinkerbell/tink/tree/main/config/crd/examples/workflow.yaml). - - ```bash - kubectl apply -f my-custom-workflow.yaml - ``` - -1. Restart the machine to provision (if using the vagrant playground test machine this is done by running `vagrant destroy -f machine1 && vagrant up machine1`) - -## Cluster API Provider Tinkerbell (CAPT) Playground - -The Cluster API Provider Tinkerbell (CAPT) is a Kubernetes Cluster API provider that uses Tinkerbell to provision machines. You can find more information about CAPT [here](https://github.com/tinkerbell/cluster-api-provider-tinkerbell). The CAPT playground is an example deployment for use in learning and testing. It is not a production reference architecture. - -### Getting Started - -The CAPT playground is a tool that will create a local CAPT deployment and a single workload cluster. This includes creating and/or installing a Kubernetes cluster (KinD), the Tinkerbell stack, all CAPI and CAPT components, Virtual machines that will be used to create the workload cluster, and a Virtual BMC server to manage the VMs. - -Start by reviewing and installing the [prerequisites](#prerequisites) and understanding and customizing the [configuration file](./capt/config.yaml) as needed. - -### Prerequisites - -#### Binaries - -- [Libvirtd](https://wiki.debian.org/KVM) >= libvirtd (libvirt) 8.0.0 -- [Docker](https://docs.docker.com/engine/install/) >= 24.0.7 -- [Helm](https://helm.sh/docs/intro/install/) >= v3.13.1 -- [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) >= v0.20.0 -- [clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start#install-clusterctl) >= v1.6.0 -- [kubectl](https://www.downloadkubernetes.com/) >= v1.28.2 -- [virt-install](https://virt-manager.org/) >= 4.0.0 -- [task](https://taskfile.dev/installation/) >= 3.37.2 - -#### Hardware - -- at least 60GB of free and very fast disk space (etcd is very disk I/O sensitive) -- at least 8GB of free RAM -- at least 4 CPU cores - -### Usage - -Create the CAPT playground: - -```bash -# Run the creation process and follow the outputted next steps at the end of the process. -task create-playground -``` - -Delete the CAPT playground: - -```bash -task delete-playground -``` - -### Known Issues - -#### DNS issue - -KinD on Ubuntu has a known issue with DNS resolution in KinD pod containers. This affect the Download of HookOS in the Tink stack helm deployment. There are a few [known workarounds](https://github.com/kubernetes-sigs/kind/issues/1594#issuecomment-629509450). The recommendation for the CAPT playground is to add a DNS nameservers to Docker's `daemon.json` file. This can be done by adding the following to `/etc/docker/daemon.json`: - -```json -{ - "dns": ["1.1.1.1"] -} -``` - -Then restart Docker: - -```bash -sudo systemctl restart docker -``` +- [Tinkerbell stack playground](stack/README.md) +- [Cluster API Provider Tinkerbell (CAPT) playground](capt/README.md) diff --git a/capt/README.md b/capt/README.md new file mode 100644 index 00000000..53885ff9 --- /dev/null +++ b/capt/README.md @@ -0,0 +1,63 @@ +# Cluster API Provider Tinkerbell (CAPT) Playground + +The Cluster API Provider Tinkerbell (CAPT) is a Kubernetes Cluster API provider that uses Tinkerbell to provision machines. You can find more information about CAPT [here](https://github.com/tinkerbell/cluster-api-provider-tinkerbell). The CAPT playground is an example deployment for use in learning and testing. It is not a production reference architecture. + +## Getting Started + +The CAPT playground is a tool that will create a local CAPT deployment and a single workload cluster. This includes creating and installing a Kubernetes cluster (KinD), the Tinkerbell stack, all CAPI and CAPT components, Virtual machines that will be used to create the workload cluster, and a Virtual BMC server to manage the VMs. + +Start by reviewing and installing the [prerequisites](#prerequisites) and understanding and customizing the [configuration file](./capt/config.yaml) as needed. + +## Prerequisites + +### Binaries + +- [Libvirtd](https://wiki.debian.org/KVM) >= libvirtd (libvirt) 8.0.0 +- [Docker](https://docs.docker.com/engine/install/) >= 24.0.7 +- [Helm](https://helm.sh/docs/intro/install/) >= v3.13.1 +- [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) >= v0.20.0 +- [clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start#install-clusterctl) >= v1.6.0 +- [kubectl](https://www.downloadkubernetes.com/) >= v1.28.2 +- [virt-install](https://virt-manager.org/) >= 4.0.0 +- [task](https://taskfile.dev/installation/) >= 3.37.2 + +### Hardware + +- at least 60GB of free and very fast disk space (etcd is very disk I/O sensitive) +- at least 8GB of free RAM +- at least 4 CPU cores + +## Usage + +Get started by looking at the [`config.yaml`](config.yaml) file. This file contains the configuration for the playground. You can customize the playground by changing the values in this file. We recommend you start with the defaults to get started and familiar with the playground before customizing. + +Create the CAPT playground: + +```bash +# Run the creation process and follow the outputted next steps at the end of the process. +task create-playground +``` + +Delete the CAPT playground: + +```bash +task delete-playground +``` + +## Known Issues + +### DNS issue + +KinD on Ubuntu has a known issue with DNS resolution in KinD pod containers. This affect the Download of HookOS in the Tink stack helm deployment. There are a few [known workarounds](https://github.com/kubernetes-sigs/kind/issues/1594#issuecomment-629509450). The recommendation for the CAPT playground is to add a DNS nameservers to Docker's `daemon.json` file. This can be done by adding the following to `/etc/docker/daemon.json`: + +```json +{ + "dns": ["1.1.1.1"] +} +``` + +Then restart Docker: + +```bash +sudo systemctl restart docker +``` diff --git a/capt/config.yaml b/capt/config.yaml index bffa45db..9cd0255f 100644 --- a/capt/config.yaml +++ b/capt/config.yaml @@ -5,11 +5,11 @@ namespace: "tink" counts: controlPlanes: 1 workers: 1 - spares: 1 + spares: 3 versions: capt: 0.5.3 chart: 0.4.5 - kube: v1.29.4 + kube: v1.28.3 os: 20.04 kubevip: 0.8.0 os: diff --git a/stack/README.md b/stack/README.md new file mode 100644 index 00000000..870b694a --- /dev/null +++ b/stack/README.md @@ -0,0 +1,40 @@ +## Tinkerbell Stack Playground + +The following section container the Tinkerbell stack playground instructions. It is not a production reference architecture. +Please use the [Helm chart](https://github.com/tinkerbell/charts) for production deployments. + +## Quick-Starts + +The following quick-start guides will walk you through standing up the Tinkerbell stack. +There are a few options for this. +Pick the one that works best for you. + +## Options + +- [Vagrant and VirtualBox](docs/quickstarts/VAGRANTVBOX.md) +- [Vagrant and Libvirt](docs/quickstarts/VAGRANTLVIRT.md) +- [Kubernetes](docs/quickstarts/KUBERNETES.md) + +## Next Steps + +By default the Vagrant quickstart guides automatically install Ubuntu on the VM (machine1). You can provide your own OS template. To do this: + +1. Login to the stack VM + + ```bash + vagrant ssh stack + ``` + +1. Add your template. An example Template object can be found [here](https://github.com/tinkerbell/tink/tree/main/config/crd/examples/template.yaml) and more Template documentation can be found [here](https://tinkerbell.org/docs/concepts/templates/). + + ```bash + kubectl apply -f my-OS-template.yaml + ``` + +1. Create the workflow. An example Workflow object can be found [here](https://github.com/tinkerbell/tink/tree/main/config/crd/examples/workflow.yaml). + + ```bash + kubectl apply -f my-custom-workflow.yaml + ``` + +1. Restart the machine to provision (if using the vagrant playground test machine this is done by running `vagrant destroy -f machine1 && vagrant up machine1`) diff --git a/docs/quickstarts/KUBERNETES.md b/stack/docs/quickstarts/KUBERNETES.md similarity index 100% rename from docs/quickstarts/KUBERNETES.md rename to stack/docs/quickstarts/KUBERNETES.md diff --git a/docs/quickstarts/VAGRANTLVIRT.md b/stack/docs/quickstarts/VAGRANTLVIRT.md similarity index 99% rename from docs/quickstarts/VAGRANTLVIRT.md rename to stack/docs/quickstarts/VAGRANTLVIRT.md index eb78a430..54e710d3 100644 --- a/docs/quickstarts/VAGRANTLVIRT.md +++ b/stack/docs/quickstarts/VAGRANTLVIRT.md @@ -22,7 +22,7 @@ This option will also create a VM and provision an OS onto it. 1. Start the stack ```bash - cd vagrant + cd stack/vagrant vagrant up # This process will take about 5-10 minutes depending on your internet connection. # Hook is about 400MB in size and the Ubuntu jammy image is about 500MB diff --git a/docs/quickstarts/VAGRANTVBOX.md b/stack/docs/quickstarts/VAGRANTVBOX.md similarity index 99% rename from docs/quickstarts/VAGRANTVBOX.md rename to stack/docs/quickstarts/VAGRANTVBOX.md index b9b311a4..14c5484f 100644 --- a/docs/quickstarts/VAGRANTVBOX.md +++ b/stack/docs/quickstarts/VAGRANTVBOX.md @@ -21,7 +21,7 @@ This option will also create a VM and provision an OS onto it. 1. Start the stack ```bash - cd vagrant + cd stack/vagrant vagrant up # This process will take up to 10 minutes depending on your internet connection. # It will download HookOS, which is a couple hundred megabytes in size, and an Ubuntu cloud image, which is about 600MB. diff --git a/vagrant/.env b/stack/vagrant/.env similarity index 100% rename from vagrant/.env rename to stack/vagrant/.env diff --git a/vagrant/Vagrantfile b/stack/vagrant/Vagrantfile similarity index 100% rename from vagrant/Vagrantfile rename to stack/vagrant/Vagrantfile diff --git a/vagrant/hardware.yaml b/stack/vagrant/hardware.yaml similarity index 100% rename from vagrant/hardware.yaml rename to stack/vagrant/hardware.yaml diff --git a/vagrant/setup.sh b/stack/vagrant/setup.sh similarity index 100% rename from vagrant/setup.sh rename to stack/vagrant/setup.sh diff --git a/vagrant/template.yaml b/stack/vagrant/template.yaml similarity index 100% rename from vagrant/template.yaml rename to stack/vagrant/template.yaml diff --git a/vagrant/ubuntu-download.yaml b/stack/vagrant/ubuntu-download.yaml similarity index 100% rename from vagrant/ubuntu-download.yaml rename to stack/vagrant/ubuntu-download.yaml diff --git a/vagrant/workflow.yaml b/stack/vagrant/workflow.yaml similarity index 100% rename from vagrant/workflow.yaml rename to stack/vagrant/workflow.yaml