diff --git a/README.md b/README.md index 03dcc48f..5e884f38 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,7 @@ To uninstall MicroShift, run the following command: ## Documentation -* [Build MicroShift Upstream](./docs/build.md) -* [Run MicroShift Upstream](./docs/run.md) +* [Build MicroShift](./docs/build.md) +* [MicroShift Host Deployment](./docs/run.md) +* [MicroShift Bootc Deployment](./docs/run-bootc.md) * [GitHub Workflows](./docs/workflows.md) diff --git a/docs/build.md b/docs/build.md index 0198a2ea..60bbad08 100644 --- a/docs/build.md +++ b/docs/build.md @@ -1,4 +1,4 @@ -## Build MicroShift Upstream +## Build MicroShift ### Overview diff --git a/docs/run-bootc.md b/docs/run-bootc.md new file mode 100644 index 00000000..1052d7ba --- /dev/null +++ b/docs/run-bootc.md @@ -0,0 +1,117 @@ +# MicroShift Bootc Deployment + +MicroShift can be run on the host or inside a Bootc container. +This document describes how to run MicroShift inside a Bootc container. + +See [MicroShift Host Deployment](./run.md) on how to run MicroShift on the host. + +## Deployment + +### Start the Cluster + +Run `make run` to start MicroShift inside a Bootc container. + +The following options can be specified in the make command line using the `NAME=VAL` format. + +| Name | Required | Default | Comments +|-------------------|----------|----------|--------- +| LVM_VOLSIZE | no | 1G | TopoLVM CSI backend volume +| ISOLATED_NETWORK | no | 0 | Use `--network none` podman option + +This step creates a single-node MicroShift cluster. The cluster can be extended using `make add-node` to add one node at a time. + +This step includes: +* Loading the `openvswitch` module required when OVN-K CNI driver is used + when compiled with the non-default `WITH_KINDNET=0` image build option. +* Preparing a TopoLVM CSI backend (default 1GB, configurable via `LVM_VOLSIZE`) on the host to be used by MicroShift when + compiled with the default `WITH_TOPOLVM=1` image build option. +* Creating a podman network for easier multi-node cluster support with name resolution. + +```bash +make run +``` + +> Specify the `ISOLATED_NETWORK=1` make option to run MicroShift inside a Bootc +> container without Internet access. +> +> Such a setup requires a MicroShift Bootc image built with `make image EMBED_CONTAINER_IMAGES=1`. +> This ensures all the required container image runtime dependencies are embedded +> and the operating system network settings are adjusted to allow a successful +> MicroShift operation. +> +> See the [config_isolated_net.sh](../src/config_isolated_net.sh) script for more +> information. + +### Container Login + +Log into the container by running the following command. The command is displayed as +part of the summary from `make run` and `make add-node` command output. + +For example, the first node in a cluster is named `microshift-okd-1`: +```bash +sudo podman exec -it microshift-okd-1 /bin/bash -l +``` + +Verify that all the MicroShift services are up and running successfully. +```bash +export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig +oc get nodes +oc get pods -A +``` + +### Add Node to Cluster + +To create a multi-node cluster, you can add additional nodes after creating the +initial cluster with `make run`. + +```bash +make add-node +``` + +> Note: The `add-node` target requires a non-isolated network (`ISOLATED_NETWORK=0`). +> Each additional node will be automatically joined to the cluster. + +### Check Cluster Status + +Run the following commands to check the status of your MicroShift cluster. + +```bash +# Wait until the MicroShift service is ready (checks all nodes) +make run-ready + +# Wait until the MicroShift service is healthy (checks all nodes) +make run-healthy + +# Show current cluster status including nodes and pods +make run-status +``` + +### Stop Cluster + +Run the following command to stop the MicroShift cluster. + +```bash +make stop +``` + +If you have stopped the MicroShift cluster, you can start it again using the following command. + +```bash +make start +``` + +## Cleanup + +Run the following command to stop the MicroShift cluster and clean up the LVM +volume used by the TopoLVM CSI backend. + +```bash +make clean +``` + +Run the following command to perform a full cleanup, including the +MicroShift Bootc images. + +```bash +make clean-all +``` diff --git a/docs/run.md b/docs/run.md index 26750161..3a9a3ae3 100644 --- a/docs/run.md +++ b/docs/run.md @@ -1,6 +1,10 @@ -# Run MicroShift Upstream +# MicroShift Host Deployment MicroShift can be run on the host or inside a Bootc container. +This document describes how to run MicroShift on the host. + +See [MicroShift Bootc Deployment](./run-bootc.md) on how to run MicroShift +inside a Bootc container. ## MicroShift RPM Packages @@ -88,101 +92,6 @@ sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config oc get pods -A ``` -## MicroShift Bootc Image - -### Start the Container - -Run `make run` to start MicroShift inside a Bootc container. - -The following options can be specified in the make command line using the `NAME=VAL` format. - -| Name | Required | Default | Comments -|-------------------|----------|----------|--------- -| LVM_VOLSIZE | no | 1G | TopoLVM CSI backend volume -| ISOLATED_NETWORK | no | 0 | Use `--network none` podman option - -This step creates a single-node MicroShift cluster. The cluster can be extended using `make add-node` to add one node at a time. - -This step includes: -* Loading the `openvswitch` module required when OVN-K CNI driver is used - when compiled with the non-default `WITH_KINDNET=0` image build option. -* Preparing a TopoLVM CSI backend (default 1GB, configurable via `LVM_VOLSIZE`) on the host to be used by MicroShift when - compiled with the default `WITH_TOPOLVM=1` image build option. -* Creating a podman network for easier multi-node cluster support with name resolution. - -```bash -make run -``` - -> Specify the `ISOLATED_NETWORK=1` make option to run MicroShift inside a Bootc -> container without Internet access. -> -> Such a setup requires a MicroShift Bootc image built with `make image EMBED_CONTAINER_IMAGES=1`. -> This ensures all the required container image runtime dependencies are embedded -> and the operating system network settings are adjusted to allow a successful -> MicroShift operation. -> -> See the [config_isolated_net.sh](../src/config_isolated_net.sh) script for more -> information. - -### Container Login - -Log into the container by running the following command. The commands for doing so are displayed as -part of the summary from `make run` and `make add-node`. - -For example, the first node in a cluster is named `microshift-okd-1`: -```bash -sudo podman exec -it microshift-okd-1 /bin/bash -l -``` - -Verify that all the MicroShift services are up and running successfully. -```bash -export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig -oc get nodes -oc get pods -A -``` - -### Start the Container - -If you have stopped the MicroShift cluster, you can start it again using the following command. - -```bash -make start -``` - -### Stop the Container - -Run the following command to stop the MicroShift Bootc container. - -```bash -make stop -``` - -### Add Node to Cluster - -To create a multi-node cluster, you can add additional nodes after creating the initial cluster with `make run`. - -```bash -make add-node -``` - -> Note: The `add-node` target requires a non-isolated network (`ISOLATED_NETWORK=0`). Each additional node will be automatically joined to the cluster. - -### Check Cluster Status - -Run the following commands to check the status of your MicroShift cluster. - -```bash -# Wait until the MicroShift service is ready (checks all nodes) -make run-ready - -# Wait until the MicroShift service is healthy (checks all nodes) -make run-healthy - -# Show current cluster status including nodes and pods -make run-status -``` - ## Cleanup ### RPM @@ -204,19 +113,3 @@ MicroShift DEB packages. echo y | sudo microshift-cleanup-data --all sudo apt purge -y 'microshift*' ``` - -### Bootc Containers - -Run the following command to stop the MicroShift Bootc container and -clean up the LVM volume used by the TopoLVM CSI backend. - -```bash -make clean -``` - -Run the following command to perform a full cleanup, including the -MicroShift Bootc images. - -```bash -make clean-all -```