From 06e641dd38628c836d8bb40cd341d32395bb03f7 Mon Sep 17 00:00:00 2001 From: Scott J Dickerson Date: Wed, 4 Sep 2024 23:16:56 -0400 Subject: [PATCH 1/3] :book: WSL/Windows setup docs, rework setup docs - Move minikube environment setup docs to its own document. - Document what works for setting up minikube, OLM and the Konveyor operator on WSL / Windows Signed-off-by: Scott J Dickerson --- README.md | 103 +++++-------------- docs/local-minikube-setup.md | 134 ++++++++++++++++++++++++ hack/wsl/README.md | 162 ++++++++++++++++++++++++++++++ hack/wsl/shim_scripts/kubectl.sh | 2 + hack/wsl/shim_scripts/minikube.sh | 25 +++++ 5 files changed, 350 insertions(+), 76 deletions(-) create mode 100644 docs/local-minikube-setup.md create mode 100644 hack/wsl/README.md create mode 100644 hack/wsl/shim_scripts/kubectl.sh create mode 100644 hack/wsl/shim_scripts/minikube.sh diff --git a/README.md b/README.md index e40038f562..3d241f7956 100644 --- a/README.md +++ b/README.md @@ -6,19 +6,19 @@ Konveyor UI component # Build and Test Status -| branch | last merge CI | last merge image build | nightly CI | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| main | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Amain+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Amain+event%3Apush) | [![Nightly CI (repo level @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml?query=branch%3Amain+event%3Aschedule) | -| release-0.5 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Aschedule) | -| release-0.4 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.4+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.ymlquery=branch%3Arelease-0.4+event%3Aschedule) | -| release-0.3 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Aschedule) | - -| branch | last merge e2e CI | nightly e2e CI | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| main | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Amain+event%3Apush) | [![Nightly CI (global konveyor CI @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml?query=branch%3Amain+event%3Aschedule) | -| release-0.5 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Aschedule) | -| release-0.4 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Aschedule) | -| release-0.3 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Aschedule) | +| branch | last merge CI | last merge image build | nightly CI | +| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| main | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Amain+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Amain+event%3Apush) | [![Nightly CI (repo level @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-repo.yaml?query=branch%3Amain+event%3Aschedule) | +| release-0.5 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.5+event%3Aschedule) | +| release-0.4 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.4+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.ymlquery=branch%3Arelease-0.4+event%3Aschedule) | +| release-0.3 | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Apush) | [![Multiple Architecture Image Build](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/image-build.yaml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (repo level)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-repo.yml?query=branch%3Arelease-0.3+event%3Aschedule) | + +| branch | last merge e2e CI | nightly e2e CI | +| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| main | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=main&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Amain+event%3Apush) | [![Nightly CI (global konveyor CI @main)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml/badge.svg?branch=main&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/nightly-ci-global.yaml?query=branch%3Amain+event%3Aschedule) | +| release-0.5 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.5&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.5+event%3Aschedule) | +| release-0.4 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.4&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.4+event%3Aschedule) | +| release-0.3 | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=push)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Apush) | [![CI (global konveyor CI)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml/badge.svg?branch=release-0.3&event=schedule)](https://github.com/konveyor/tackle2-ui/actions/workflows/ci-global.yml?query=branch%3Arelease-0.3+event%3Aschedule) | # Development @@ -45,75 +45,26 @@ With an existing Tackle2 environment available, one can start a locally served t npm run start:dev ``` -## Tackle2 environment setup +## Konveyor environment setup -With the UI project setup out of the way, you can now begin setting up you local Tackle2 dev environment. The preferred local development option is to setup a minikube instance. -Alternatively, for information on general Kubernetes installation refer to [Tackle2 operator readme](https://github.com/konveyor/tackle2-operator#readme) file. - -### Minikube setup - -[Minikube](https://github.com/kubernetes/minikube) implements a local Kubernetes cluster on macOS, Linux, and Windows. See the minikube getting started guide [here.](https://minikube.sigs.k8s.io/docs/start/) - -All you need to run minikube is [Docker](https://docs.docker.com/engine/install/) (or similarly compatible) container or a Virtual Machine environment. - -By default, Minikube uses a [driver](https://minikube.sigs.k8s.io/docs/drivers/) with 6,000 MB of memory and 2 CPUs. This is not enough to run all the services, so we need to increase the allocated memory. In our experience, 10 GB of memory and 4 CPUs is fine: - -```sh -$ minikube config set memory 10240 -$ minikube config set cpus 4 -``` - -Note: Depending on your driver, administrator access may be required. Common choices include Docker for container-based virtualization and KVM for hardware-assisted virtualization on Linux systems. If you're not sure which driver is best for you or if you're encountering compatibility issues, Minikube also supports auto-selecting a driver based on your system's capabilities and installed software. - -From a terminal run: - -```sh -$ minikube start --addons=dashboard --addons=ingress -``` - -Note: We need to enable the dashboard and ingress addons. The dashboard addon installs the dashboard service that exposes the Kubernetes objects in a user interface. The ingress addon allows us to create Ingress CRs to expose the Tackle UI and Tackle Hub API. - -Since the olm addon is disabled until OLM issue [2534](https://github.com/operator-framework/operator-lifecycle-manager/issues/2534) is resolved we need to install the [OLM manually](https://github.com/operator-framework/operator-lifecycle-manager/releases) i.e. for version `v0.28.0` we can use: - -```sh -curl -L https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.28.0/install.sh -o install.sh -chmod +x install.sh -./install.sh v0.28.0 -``` - -See also official Konveyor instructions for [Provisioning Minikube](https://konveyor.github.io/konveyor/installation/#provisioning-minikube). - -### Configuring kubectl for minikube - -You will need `kubectl` on your PATH and configured to control minikube in order to proceed. There are two ways to set this up: - -1. **Install kubectl yourself** - - If you already [have the `kubectl` CLI tool installed](https://kubernetes.io/docs/tasks/tools/#kubectl) and available on your PATH, the `minikube start` command should configure it to control the minikube cluster. You should see the following message when minikube starts if this worked correctly: - - ``` - 🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default - ``` - -2. **Use a shell alias for minikube's built-in kubectl** - - Minikube provides its own internal `kubectl` which you can use by running `minikube kubectl --` followed by your CLI arguments. If you want to use the built-in `minikube kubectl` as the `kubectl` on your PATH, you can set a shell alias. The following example shows how to do it for Bash on Fedora 35. - - ```sh - $ mkdir -p ~/.bashrc.d - $ cat << EOF > ~/.bashrc.d/minikube - alias kubectl="minikube kubectl --" - EOF - $ source ~/.bashrc - ``` +The process for setting up a Konveyor operator to run on a local Kubernetes cluster via +minikube is detailed in the [local setup document](docs/local-minikube-setup.md). ### Installing the Konveyor operator -Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator) +There are a few good ways to install the Konveyor operator: + +- Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator) -Alternative 1, use the script [`hack/setup-operator.sh`](./hack/setup-operator.sh). It is a local variation of the script from the operator that still allows overriding portions of the Tackle CR with environment variables. +- Alternative 1, use the script [`hack/setup-operator.sh`](./hack/setup-operator.sh). It + is a local variation of the script from the operator that still allows overriding portions + of the Tackle CR with environment variables. -Alternative 2, the [konveyor/operator git repository](https://github.com/konveyor/operator) provides a script to install Tackle locally using `kubectl`. You can [inspect its source here](https://github.com/konveyor/operator/blob/main/hack/install-tackle.sh). This script creates the `konveyor-tackle` namespace, CatalogSource, OperatorGroup, Subscription and Tackle CR, then waits for deployments to be ready. +- Alternative 2, the [konveyor/operator git repository](https://github.com/konveyor/operator) + provides a script to install Tackle locally using `kubectl`. You can + [inspect its source here](https://github.com/konveyor/operator/blob/main/hack/install-tackle.sh). + This script creates the `konveyor-tackle` namespace, CatalogSource, OperatorGroup, Subscription + and Tackle CR, then waits for deployments to be ready. #### Customizing the install script (optional) diff --git a/docs/local-minikube-setup.md b/docs/local-minikube-setup.md new file mode 100644 index 0000000000..1f89c2280a --- /dev/null +++ b/docs/local-minikube-setup.md @@ -0,0 +1,134 @@ +# Setting up Konveyor on a local minikube instance + +The preferred local development for the tackle2-ui is to install the Konveyor +operator on a minikube instance. When the operator is installed and running, +the ui development server can attach to it and use the running hub api. There +will also be a running UI instance to work with. + +The setup process follows the general steps: + +- install minikube +- start minikube with the **dashboard** and **ingress** addons +- install the operator framework (OLM) +- install the Konveyor operator +- optionally add test data + +## Konveyor Documentation + +A guide for installing minikube and Konveyor is also available in the general project +documentation. See document [Installing Konveyor](https://konveyor.github.io/konveyor/installation). + +For information on general Kubernetes installation refer to +[Konveyor operator readme](https://github.com/konveyor/tackle2-operator#readme). + +## Install and start minikube + +[Minikube](https://github.com/kubernetes/minikube) implements a local Kubernetes cluster +and is available on macOS, Linux, and Windows. All you need to run minikube is a container +runtime ([Docker](https://docs.docker.com/engine/install/) or [podman](https://podman.io/docs/installation)) +or a Virtual Machine environment. + +See the minikube [getting started guide](https://minikube.sigs.k8s.io/docs/start/) for install +details for your platform. + +By default, Minikube uses a [driver](https://minikube.sigs.k8s.io/docs/drivers/) with 6 GB +of memory and 2 CPUs. This may not be enough to run all the services, so we need to increase +the allocated memory. In our experience, 10 GB of memory and 4 CPUs is fine: + +```sh +minikube config set memory 10240 +minikube config set cpus 4 +``` + +> [!IMPORTANT] +> Depending on your driver, administrator access may be required. Common driver choices are +> Docker for container-based virtualization and KVM for hardware-assisted virtualization on Linux +> systems. If you're not sure which driver is best for you or if you're encountering compatibility +> issues, minikube supports auto-selecting a driver based on your system's capabilities and +> installed software. + +Start minikube with the command: + +```sh +minikube start --addons=dashboard --addons=ingress +``` + +> [!NOTE] +> We need to enable the **dashboard** and **ingress** addons. The dashboard addon installs +> the dashboard service that provides a web UI for the Kubernetes objects. The ingress addon +> allows us to create Ingress CRs to expose the Tackle UI and Tackle Hub API. + +## Install OLM + +Since Konveyor is deployed as an operator, the [operator framework](https://operatorframework.io/)'s +[operator lifecycle manager (OLM)](https://olm.operatorframework.io/) needs to be installed +on our new minikube instance before installing the Konveyor operator. + +Since the minikube olm addon is disabled until OLM issue +[2534](https://github.com/operator-framework/operator-lifecycle-manager/issues/2534) +is resolved we need to install the [OLM manually](https://github.com/operator-framework/operator-lifecycle-manager/releases). + +For version `v0.28.0` (latest version as of 17-May-2024) use the scripts: + +```sh +curl -L https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.28.0/install.sh -o install.sh +chmod +x install.sh +./install.sh v0.28.0 +``` + +## Install the Konveyor Operator + +See also official Konveyor instructions for [Provisioning Minikube](https://konveyor.github.io/konveyor/installation/#provisioning-minikube). + +## Sample Data + +## Optional Setup + +### Configuring kubectl for minikube + +You will need `kubectl` on your PATH and configured to control minikube in order to proceed. +There are a few ways to set this up: + +1. **Install kubectl yourself** + + If you already [have the `kubectl` CLI tool installed](https://kubernetes.io/docs/tasks/tools/#kubectl) + and available on your PATH, the `minikube start` command should configure it to control the minikube + cluster. You should see the following message when minikube starts if this worked correctly: + + ``` + 🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default + ``` + +2. **Use a shell alias for minikube's built-in kubectl** + + Minikube provides its own internal `kubectl` which you can use by running `minikube kubectl --` + followed by your CLI arguments. If you want to use the built-in `minikube kubectl` as the `kubectl` + on your shell, you can setup a shell alias. + + The following example shows how to setup an alias for bash on Fedora 35: + + ```sh + $ mkdir -p ~/.bashrc.d + $ cat << EOF > ~/.bashrc.d/minikube + alias kubectl="minikube kubectl --" + EOF + $ source ~/.bashrc + ``` + + > [!WARNING] + > The alias will only work for an interactive shell. If you want to use `minikube kubectl --` + > as the command in scripts, you'll need to use a shim shell script. + +3. **Use a shim shell script to route kubectl to minikube** + + To be able to use `minikube kubectl --` as the command `kubectl` in general use (interactive + prompt and in other scripts), a simple shell script can be used. Any location that is in + the `$PATH` can be used. Installing for all system users can typically be done to `/usr/local/bin`: + + ```sh + $ cat << EOF > kubectl.sh + #! /usr/bin/env bash + minikube kubectl -- $@ + EOF + $ sudo install -m 777 kubectl.sh /usr/local/bin/kubectl + ``` diff --git a/hack/wsl/README.md b/hack/wsl/README.md new file mode 100644 index 0000000000..09d176650d --- /dev/null +++ b/hack/wsl/README.md @@ -0,0 +1,162 @@ +# Windows Subsystem for Linux + +Running Konveyor on Windows has the same basic requirements as running +on Linux or Mac: + +- A kubernetes / minikube instance +- OLM installed on the instance to be able to use Operators + +Both of these currently need to run on top of WSL providing a container +runtime. There are various way to achieve this, but one way that was +found to work is detailed below. + +> [!NOTE] +> Note: Installing a fedora distribution to WSL and then setting up an environment +> directly on that distribution is possible. This most likely involves nested +> virtualization and may require additional network configurations to run correctly. + +## Installing + +Podman desktop or docker desktop can be used to setup WSL and a base +container runtime environment. Podman desktop allows for easy installation +of minikube from within its GUI. + +General steps: + +- Install docker or podman on top of the WSL runtime +- Install the windows binary of minikube +- Configure your default WSL instance to: + - be able to download and run bash scripts + - use the `minikube` installed to windows + - map the `kubectl` command to use the `minikube kubectl --` command. This is needed + to be able to run the normal OLM and Konveyor install scripts. +- Install OLM +- Install Konveyor +- _(optional)_ Import a base set of data + +### Podman Desktop or Docker Desktop + +Both docker desktop and podman desktop can be installed, but really just pick one. + +#### Podman Desktop + +Install page: https://podman-desktop.io/docs/installation/windows-install + +The install has a few extra options to help setup WSL, the podman runtime[^1], and other +tools that I found more useful than Docker Desktop. + +[^1]: Standard install of podman on windows: https://podman.io/docs/installation#windows + +#### Docker Desktop + +Install page: https://www.docker.com/products/docker-desktop/ + +Note: After installing, you'll either need to sign in to docker or hit skip a +bunch of times to start using docker. If this is annoying, Podman Desktop doesn't +do that. + +### Minikube + +Minikube can be installed from podman desktop: https://podman-desktop.io/docs/minikube + +Install page: https://minikube.sigs.k8s.io/docs/start + +- Download the [latest release of the Windows stable .exe download](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fwindows%2Fx86-64%2Fstable%2F.exe+download) +- Run the installer (no changes to the default options are needed) + +### Configure the default WSL to be able to run windows binaries, bash scripts, minikube and kubectl + +#### Configuring the Docker Desktop WSL distribution + +Docker desktop's WSL instance appears to use a version of alpine linux, so curl and +bash probably need to be installed manually. To install them, from the WSL prompt +run: + +``` +apk add curl bash +``` + +#### Configuring the podman machine WSL distribution + +The podman WSL distribution is based on fedora so curl and bash should already be +available. + +The distribution may need extra configurations to be able to invoke windows binaries. +To verify windows binaries can be called, from the podman WSL instance (which should +be the default if only podman / podman desktop is installed), run the command + +``` +/mnt/c/Windows/System32/notepad.exe +``` + +If the notepad application opens, everything is ok. + +If an error occurs, the distribution needs to be reconfigured[^2]: + +- from the WSL command line run: + + ``` + sudo sh -c 'echo :WSLInterop:M::MZ::/init:PF > /usr/lib/binfmt.d/WSLInterop.conf' + ``` + +- Exit the shell + +- Either reboot or from the windows command prompt run: + + ``` + wsl --shutdown + ``` + +- Open the WSL shell and try running notepad again. It should work this time. + +[^2]: See this github comment: https://github.com/microsoft/WSL/issues/8843#issuecomment-1459120198 + + + +#### Setting up the WSL instance to run the windows version of minikube / kubectl + +Installing minikube as a windows binary has advantages, but for the OLM and Konveyor +install scripts to work unmodified, the most reliable way I found is to use a pair +of shell scripts. These scripts will then call the installed windows binary. + +The scripts should be copied into a folder listed in the `$PATH`. Typically +the path `/usr/local/bin` is included and is a good location to put the scripts. + +- Install a [shell script for `minikube`](shim_scripts/minikube.sh) to call the installed + windows binary: + + ``` + curl https://raw.githubusercontent.com/konveyor/tackle2-ui/main/hack/wsl/shim_scripts/minikube.sh + sudo install -m 777 minikube.sh /usr/local/bin/minikube + ``` + +- Install a [shell script for `kubectl`](shim_scripts/kubectl.sh) to use the kubectl + embedded in minikube `minikube kubectl --`: + + ``` + curl https://raw.githubusercontent.com/konveyor/tackle2-ui/main/hack/wsl/shim_scripts/kubectl.sh + sudo install -m 777 kubectl.sh /usr/local/bin/kubectl + ``` + +- Test that minikube and kubectl are working: + ``` + minikube profile list + kubectl cluster-info + ``` + +### Install OLM on minikube + +Follow the normal OLM install process in +[local minikube setup](/docs/local-minikube-setup.md#install-olm) docs. + +### Install Konveyor Operator on minikube + +Follow the normal Konveyor operator install process in +[local minikube setup](/docs/local-minikube-setup.md#install-the-konveyor-operator) docs. diff --git a/hack/wsl/shim_scripts/kubectl.sh b/hack/wsl/shim_scripts/kubectl.sh new file mode 100644 index 0000000000..1ed2a6604a --- /dev/null +++ b/hack/wsl/shim_scripts/kubectl.sh @@ -0,0 +1,2 @@ +#! /usr/bin/env bash +minikube kubectl -- $@ diff --git a/hack/wsl/shim_scripts/minikube.sh b/hack/wsl/shim_scripts/minikube.sh new file mode 100644 index 0000000000..a5a5b683c6 --- /dev/null +++ b/hack/wsl/shim_scripts/minikube.sh @@ -0,0 +1,25 @@ +#! /usr/bin/env bash +TARGET=/usr/local/bin + +if [ ! -e "$TARGET/minikube.exe" ]; then + [[ $(id -u) -ne 0 ]] && SUDO=sudo || SUDO= + + roots=( + "/mnt/c/Users/*/AppData/Local/Microsoft/WindowsApps" + "/mnt/c/Program Files/Kubernetes/Minikube" + "/mnt/host/c/Users/*/AppData/Local/Microsoft/WindowsApps" + "/mnt/host/c/Program Files/Kubernetes/Minikube" + ) + + shopt -s nullglob + IFS=$'\n' + for root in $roots; do + if [ -e "${root}/minikube.exe" ]; then + echo "linking to ${root}/minikube.exe" + $SUDO ln -s "${root}/minikube.exe" "$TARGET/minikube.exe" + break + fi + done +fi + +minikube.exe $@ From 3955d7b8bcc2e696fefe75ae7058ac987eb874ac Mon Sep 17 00:00:00 2001 From: Scott J Dickerson Date: Sat, 7 Sep 2024 12:49:09 -0400 Subject: [PATCH 2/3] Doc updates - move some docs to `docs/` - rework the main README.md: - have a quick start section - move some details to `development.md` - move environment install docs to `local-minikube-setup.md` - rework the Windows docs Signed-off-by: Scott J Dickerson --- README.md | 57 ++++++++----- development.md => docs/development.md | 12 ++- docs/local-minikube-setup.md | 24 +++++- tests.md => docs/tests.md | 0 hack/README.md | 10 +-- hack/wsl/README.md | 113 +++++++++++++++++++------- 6 files changed, 153 insertions(+), 63 deletions(-) rename development.md => docs/development.md (93%) rename tests.md => docs/tests.md (100%) diff --git a/README.md b/README.md index 3d241f7956..e79b23ae46 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,12 @@ Konveyor UI component ## Prerequisites -- [NodeJS](https://nodejs.org/en/) >= 16.x -- [minikube](https://minikube.sigs.k8s.io/docs/start) (optional): setup your local minikube instance with your container manager of choice. (Docker, Hyperkit, Hyper-V, KVM, Parallels, Podman, VirtualBox, or VMware Fusion/Workstation.) +- [Node.js](https://nodejs.org/en/) >= 20 (see the `engines` block of [package.json](./package.json) for specifics) +- [minikube](https://minikube.sigs.k8s.io/docs/start) (optional): setup your local minikube instance with your container manager of choice -## Installation +## Quick start + +### Clone the repository To get started, clone the repo to your development workstation and install the required dependencies locally with NPM. @@ -37,21 +39,45 @@ cd tackle2-ui npm install ``` -## Quick start +### Connect to or setup a Konveyor instance + +- **Existing instance?** Make sure `kubectl` is configured to connect to the cluster where + the existing operator is deployed. + +- **New instance?** The process for setting up a Konveyor operator to run on a local Kubernetes + cluster via minikube is detailed in the [local setup document](docs/local-minikube-setup.md). + +### Run the development server -With an existing Tackle2 environment available, one can start a locally served tackle2-ui instance with: +With an existing Konveyor environment available, and `kubectl` configured to use it, a local development server served tackle2-ui instance can be started with: ```sh npm run start:dev ``` +Your development server should start up and serve the locally running UI from: + +``` +http://localhost:9000 +``` + ## Konveyor environment setup +There are many ways to setup a kubernetes instance and deploy the Konveyor operator for +use as a development environment. The recommendation is to setup minikube and deploy +the operator there. D + +Summary of tasks to setup a local environment: + +1. Setup an kubernetes instance with OLM to support the Konveyor operator +2. Install the Konveyor operator +3. Create the Konveyor CR + +### Setus up a local insta Konveyor operator + The process for setting up a Konveyor operator to run on a local Kubernetes cluster via minikube is detailed in the [local setup document](docs/local-minikube-setup.md). -### Installing the Konveyor operator - There are a few good ways to install the Konveyor operator: - Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator) @@ -78,12 +104,6 @@ $ export AUTH_REQUIRED=true #### Running the install script -Before proceeding, if you are on macOS you will need to use [Homebrew](https://brew.sh/) to install the `coreutils` package: - -```sh -$ brew install coreutils -``` - To run the install script (requires `kubectl` on your PATH configured for minikube): ```sh @@ -92,7 +112,10 @@ $ curl https://raw.githubusercontent.com/konveyor/operator/main/hack/install-tac Alternatively, you can clone the [konveyor/operator git repository](https://github.com/konveyor/operator) and run `./hack/install-tackle.sh` from your clone, or you can execute its commands manually. -⚠️ Note: While CRDs are being established, you may see the script output `NotFound` errors. You can safely ignore these. The script will wait 30 seconds to check for the CRD again before proceeding. +> [!WARNING] +> While CRDs are being established, you may see the script output `NotFound` errors. +> You can safely ignore these. The script will wait and recheck for the CRD again before +> proceeding. The installation is complete when the script outputs "condition met" messages and terminates. @@ -192,12 +215,6 @@ Please read the [Pull Request (PR) Process](https://github.com/konveyor/release- section of the [Konveyor versioning and branching doc](https://github.com/konveyor/release-tools/blob/main/VERSIONING.md) for more information. -## File Naming Conventions - -- Use kebab-case for file names. -- The root page/parent level components are placed directly in their respective directories. -- Presentation layer components are placed within the `components/` subdirectory of the parent component. - # Contributing We welcome contributions to this project! If you're interested in contributing, diff --git a/development.md b/docs/development.md similarity index 93% rename from development.md rename to docs/development.md index 3ec657c916..ecf8dbc838 100644 --- a/development.md +++ b/docs/development.md @@ -6,6 +6,12 @@ This document describes the process for running and developing tackle2-ui on you Tackle2-ui can be developed using macOS(x86_64 only) or Linux environments. +## File Naming Conventions + +- Use kebab-case for file names. +- The root page/parent level components are placed directly in their respective directories. +- Presentation layer components are placed within the `components/` subdirectory of the parent component. + ## React hooks Our project utilizes [Hooks](https://reactjs.org/docs/hooks-intro.html) wherever possible as this pattern has been proven and settled on in the react community. The hooks pattern is highly testable and provides a clear way to reuse stateful logic without overcomplicating components with complex lifecycle methods. Overall, we have largely left class components behind and have adopted functional components / hooks as the way forward. @@ -17,7 +23,7 @@ For handling spacing/layout requirements that do not fit the standard PF mold, w ## Form development -We are using [react-hook-form](https://react-hook-form.com) in tandem with [patternfly](https://www.patternfly.org). Custom wrapper components have been developed to aid with this integration and their usage can be referenced in the [proxy-form](./client/src/app/pages/proxies/proxy-form.tsx) component. +We are using [react-hook-form](https://react-hook-form.com) in tandem with [patternfly](https://www.patternfly.org). Custom wrapper components have been developed to aid with this integration and their usage can be referenced in the [proxy-form](/client/src/app/pages/proxies/proxy-form.tsx) component. ### Steps to create a form @@ -62,5 +68,5 @@ export interface FormValues { For more info about working on the Tackle 2.x UI, check out these READMEs: -- [tests.md](./tests.md) -- [internationalization.md](./INTERNATIONALIZATION.md) +- [tests.md](/docs/tests.md) +- [internationalization.md](/INTERNATIONALIZATION.md) diff --git a/docs/local-minikube-setup.md b/docs/local-minikube-setup.md index 1f89c2280a..35d80a2f0d 100644 --- a/docs/local-minikube-setup.md +++ b/docs/local-minikube-setup.md @@ -18,7 +18,7 @@ The setup process follows the general steps: A guide for installing minikube and Konveyor is also available in the general project documentation. See document [Installing Konveyor](https://konveyor.github.io/konveyor/installation). -For information on general Kubernetes installation refer to +For information on generic Kubernetes installation refer to [Konveyor operator readme](https://github.com/konveyor/tackle2-operator#readme). ## Install and start minikube @@ -78,11 +78,27 @@ chmod +x install.sh ## Install the Konveyor Operator -See also official Konveyor instructions for [Provisioning Minikube](https://konveyor.github.io/konveyor/installation/#provisioning-minikube). +Using the official Konveyor instructions for [Provisioning Minikube](https://konveyor.github.io/konveyor/installation/#provisioning-minikube) is an easy way to start. -## Sample Data +_TBD - Move more content from README.md_ -## Optional Setup +## Optional Steps... + +### Considerations for MacOS + +Some core utils used in install and setup scripts may not be available by default on +a Mac. They are available to install via [Homebrew](https://brew.sh/) as the `coreutils` +package: + +```sh +brew install coreutils +``` + +### Sample data from tackle2-hub + +The [tackle2-hub repo](https://github.com/konveyor/tackle2-hub) has some scripts to add +basic entities to a Konveyor instance. Using the scripts is a reasonable way to get a +base setup. Importing that data is [described here](/hack/README.md#adding-a-base-set-of-data-to-an-empty-instance). ### Configuring kubectl for minikube diff --git a/tests.md b/docs/tests.md similarity index 100% rename from tests.md rename to docs/tests.md diff --git a/hack/README.md b/hack/README.md index 718857ef78..85e1488018 100644 --- a/hack/README.md +++ b/hack/README.md @@ -7,13 +7,13 @@ creating/importing various pieces of data. For creating a base set of data in a tackle-hub instance, a good place to start is [tackle-hub's hack folder](https://github.com/konveyor/tackle2-hub/tree/main/hack). -If you have hub running or port forwarded on port :9002, a basic set of data can be -added to the instance by: +If you have the Konveyor operator running on minikube without authentication, a basic +set of data can be added to the instance by: ```sh -> git clone https://github.com/konveyor/tackle2-hub.git -> cd tackle2-hub/hack -> HOST=localhost:9002 ./add/all.sh +git clone https://github.com/konveyor/tackle2-hub.git +cd tackle2-hub/hack +HOST=http://$(minikube ip)/hub ./add/all.sh ``` ## Useful commands diff --git a/hack/wsl/README.md b/hack/wsl/README.md index 09d176650d..2bbed7923a 100644 --- a/hack/wsl/README.md +++ b/hack/wsl/README.md @@ -1,4 +1,4 @@ -# Windows Subsystem for Linux +# Konveyor on Windows Running Konveyor on Windows has the same basic requirements as running on Linux or Mac: @@ -6,35 +6,47 @@ on Linux or Mac: - A kubernetes / minikube instance - OLM installed on the instance to be able to use Operators -Both of these currently need to run on top of WSL providing a container -runtime. There are various way to achieve this, but one way that was -found to work is detailed below. +Minikube needs to run on top of a container platform. There are multiple ways to set +that up (see [minikube drivers](https://minikube.sigs.k8s.io/docs/drivers/)). A +recommended approach is to use a docker or podman container runtime running on top of +WSL. There are various way to achieve this, but one way that was found to work is +described below. > [!NOTE] > Note: Installing a fedora distribution to WSL and then setting up an environment > directly on that distribution is possible. This most likely involves nested > virtualization and may require additional network configurations to run correctly. -## Installing - -Podman desktop or docker desktop can be used to setup WSL and a base -container runtime environment. Podman desktop allows for easy installation -of minikube from within its GUI. +General steps to get going: -General steps: - -- Install docker or podman on top of the WSL runtime -- Install the windows binary of minikube -- Configure your default WSL instance to: +- Install [the windows binary of minikube](#minikube) +- Install [a container runtime](#container-runtime) (docker or podman) on top of the WSL +- Start/create a [minikube instance](#start-a-minikube-instance) +- [Configure your default WSL](#configure-the-default-wsl) instance to: - be able to download and run bash scripts - use the `minikube` installed to windows - map the `kubectl` command to use the `minikube kubectl --` command. This is needed to be able to run the normal OLM and Konveyor install scripts. -- Install OLM -- Install Konveyor -- _(optional)_ Import a base set of data +- Install [OLM](#install-olm-on-minikube) +- Install [Konveyor](#install-konveyor-operator-on-minikube) +- Finally, [access the Konveyor UI](#accessing-the-ui-running-on-minikube) + +## Installing + +### Minikube -### Podman Desktop or Docker Desktop +Install page: https://minikube.sigs.k8s.io/docs/start + +- Download the [latest release of the Windows stable .exe download](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fwindows%2Fx86-64%2Fstable%2F.exe+download) +- Run the installer (no changes to the default options are needed) + +Alternatively, Minikube can be installed from podman desktop: https://podman-desktop.io/docs/minikube + +### Container Runtime + +Podman desktop or docker desktop can be used to setup WSL and a base +container runtime environment. Podman desktop allows for easy installation +of minikube from within its GUI. Both docker desktop and podman desktop can be installed, but really just pick one. @@ -55,18 +67,35 @@ Note: After installing, you'll either need to sign in to docker or hit skip a bunch of times to start using docker. If this is annoying, Podman Desktop doesn't do that. -### Minikube +## Start a minikube instance -Minikube can be installed from podman desktop: https://podman-desktop.io/docs/minikube +General configuration and startup of a minikube instance is covered +[local minikube setup](/docs/local-minikube-setup.md#install-and-start-minikube). +However, on windows it is helpful to explicitly configure the driver to use based on what +container runtime you installed. **Assuming you installed the windows binaries for +minikube, these command should be run in a normal windows Command Prompt.** Sample +commands assuming you have podman installed (substitute podman for any other driver, +such as docker, as needed): -Install page: https://minikube.sigs.k8s.io/docs/start +``` +minikube start --addons=dashboard --addons=ingress --driver=podman +``` -- Download the [latest release of the Windows stable .exe download](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fwindows%2Fx86-64%2Fstable%2F.exe+download) -- Run the installer (no changes to the default options are needed) +If a minikube instance already exists but doesn't have the needed addons, they can +be enabled individually: + +``` +minikube addons enable dashboard +minikube addons enable ingress +``` + +## Configure the default WSL -### Configure the default WSL to be able to run windows binaries, bash scripts, minikube and kubectl +No matter what distribution is setup as default on your WSL environment, it probably +needs additional configurations to be able to run windows binaries, bash scripts, +minikube and kubectl -#### Configuring the Docker Desktop WSL distribution +### Configuring the Docker Desktop WSL distribution Docker desktop's WSL instance appears to use a version of alpine linux, so curl and bash probably need to be installed manually. To install them, from the WSL prompt @@ -76,7 +105,7 @@ run: apk add curl bash ``` -#### Configuring the podman machine WSL distribution +### Configuring the podman machine WSL distribution The podman WSL distribution is based on fedora so curl and bash should already be available. @@ -120,7 +149,7 @@ go back in the WSL shell and should be able to invoke windows .exe files! !!!!!!!! --> -#### Setting up the WSL instance to run the windows version of minikube / kubectl +### Setting up the WSL instance to run the windows version of minikube / kubectl Installing minikube as a windows binary has advantages, but for the OLM and Konveyor install scripts to work unmodified, the most reliable way I found is to use a pair @@ -151,12 +180,34 @@ the path `/usr/local/bin` is included and is a good location to put the scripts. kubectl cluster-info ``` -### Install OLM on minikube +## Install OLM on minikube Follow the normal OLM install process in -[local minikube setup](/docs/local-minikube-setup.md#install-olm) docs. +[local minikube setup](/docs/local-minikube-setup.md#install-olm) docs, but run the +commands in the WSL shell. -### Install Konveyor Operator on minikube +## Install Konveyor Operator on minikube Follow the normal Konveyor operator install process in -[local minikube setup](/docs/local-minikube-setup.md#install-the-konveyor-operator) docs. +[local minikube setup](/docs/local-minikube-setup.md#install-the-konveyor-operator) docs, +but run the commands in the WSL shell. + +## Accessing the UI running on minikube + +Looking at the [Ingress option of the deploy applications](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fwindows%2Fx86-64%2Fstable%2F.exe+download#Ingress) +step in the minikube get started guide, there is a note for Docker Desktop Users: + +> To get ingress to work you'll need to open a new terminal window and run minikube +> tunnel and in the following step use 127.0.0.1 in place of . + +I also found this to be true using podman desktop. + +Using `minikube tunnel` to have the tackle service exposed on localhost should work. +Open a new command prompt window and run (the window will need to remain open for +the tunnel to stay open): + +``` +minikube tunnel +``` + +Once the tunnel is running, Konveyor will be available at `http://127.0.0.1/`. From dd51c62031813d3061b49f1709c9ec5ca0558a66 Mon Sep 17 00:00:00 2001 From: Scott J Dickerson Date: Sat, 7 Sep 2024 15:19:43 -0400 Subject: [PATCH 3/3] Update the docs for setting up minikube Signed-off-by: Scott J Dickerson --- README.md | 97 ++++++++-------------------- docs/local-minikube-setup.md | 121 ++++++++++++++++++++++++++++++----- 2 files changed, 129 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index e79b23ae46..7a6b2adee6 100644 --- a/README.md +++ b/README.md @@ -63,74 +63,28 @@ http://localhost:9000 ## Konveyor environment setup -There are many ways to setup a kubernetes instance and deploy the Konveyor operator for -use as a development environment. The recommendation is to setup minikube and deploy -the operator there. D - Summary of tasks to setup a local environment: 1. Setup an kubernetes instance with OLM to support the Konveyor operator 2. Install the Konveyor operator 3. Create the Konveyor CR +4. Run your [local dev server](#run-the-development-server) -### Setus up a local insta Konveyor operator - -The process for setting up a Konveyor operator to run on a local Kubernetes cluster via -minikube is detailed in the [local setup document](docs/local-minikube-setup.md). - -There are a few good ways to install the Konveyor operator: - -- Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator) - -- Alternative 1, use the script [`hack/setup-operator.sh`](./hack/setup-operator.sh). It - is a local variation of the script from the operator that still allows overriding portions - of the Tackle CR with environment variables. - -- Alternative 2, the [konveyor/operator git repository](https://github.com/konveyor/operator) - provides a script to install Tackle locally using `kubectl`. You can - [inspect its source here](https://github.com/konveyor/operator/blob/main/hack/install-tackle.sh). - This script creates the `konveyor-tackle` namespace, CatalogSource, OperatorGroup, Subscription - and Tackle CR, then waits for deployments to be ready. - -#### Customizing the install script (optional) +The most common and the recommended environment is to [setup minikube and deploy +the operator](ocs/local-minikube-setup.md) there. -The install script provides optional environment variables you can use to customize the images and features used. See [the source of the script](https://github.com/konveyor/operator/blob/main/hack/install-tackle.sh) for all available variables. +A general guide for installing minikube and Konveyor is also available in the project +documentation [Installing Konveyor](https://konveyor.github.io/konveyor/installation). -For example, if you wish to run tackle with keycloak authentication enabled, export the following variable before running the install script: - -```sh -$ export AUTH_REQUIRED=true -``` - -#### Running the install script - -To run the install script (requires `kubectl` on your PATH configured for minikube): - -```sh -$ curl https://raw.githubusercontent.com/konveyor/operator/main/hack/install-tackle.sh | bash -``` - -Alternatively, you can clone the [konveyor/operator git repository](https://github.com/konveyor/operator) and run `./hack/install-tackle.sh` from your clone, or you can execute its commands manually. - -> [!WARNING] -> While CRDs are being established, you may see the script output `NotFound` errors. -> You can safely ignore these. The script will wait and recheck for the CRD again before -> proceeding. - -The installation is complete when the script outputs "condition met" messages and terminates. - -### Start your local development server - -Now that your environment is ready, navigate to your installed tackle-ui directory and run your development server: - -```sh -$ cd tackle2-ui -$ npm run start:dev -``` +For information to help install on any Kubernetes platform see the +[Konveyor operator readme](https://github.com/konveyor/tackle2-operator#readme). ## Understanding the local development environment -Tackle2 runs in a Kubernetes compatible environment (i.e. Openshift, Kubernetes or minikube) and is usually deployed with Tackle2 Operator (OLM). Although the UI pod has access to tackle2 APIs from within the cluster, the UI can also be executed outside the cluster and access Tackle APIs endpoints by proxy. +Konveyor runs in a Kubernetes compatible environment (e.g. Openshift, Kubernetes or minikube) and +is typically deployed with Tackle2 Operator (OLM). Although the UI pod has access to tackle2 APIs +from within the cluster, the UI can also be executed outside the cluster and access Tackle APIs +endpoints by proxy. The React and Patternfly based UI is composed of web pages served by an http server with proxy capabilities. @@ -170,28 +124,27 @@ $ kubectl port-forward svc/tackle-hub -n konveyor-tackle 9002:8080 **Note**: The `npm run port-forward` or `kubectl port-forward` commands need to remain running for the ports to be available. -## Accessing the Kubernetes dashboard +## Accessing the Minikube Kubernetes dashboard -We may need to access the dashboard, either simply to see what's happening under the hood, or to -troubleshoot an issue. The dashboard addon is enabled in the default in recommended `minikube start` -command in the [Minikube setup section](#minikube-setup). +We may need to access the dashboard, either simply to see what's happening under +the hood, or to troubleshoot an issue. -There are two ways to setup access to the dashboard. +There are two ways to setup access to the dashboard: -First, we can use the `minikube dashboard` command. Use to following to open on an explicit -port and only show the URL instead of opening the default browser directly: +1. We can use the `minikube dashboard` command. Use to following to open on an explicit + port and only show the URL instead of opening the default browser directly: -```sh -$ minikube dashboard --port=18080 --url=true -``` + ```sh + $ minikube dashboard --port=18080 --url=true + ``` -Second, we can use the `kubectl port-forward` command to enable access to the dashboard: +2. We can use the `kubectl port-forward` command to enable access to the dashboard: -```sh -$ kubectl port-forward svc/kubernetes-dashboard -n kubernetes-dashboard 30090:80 -``` + ```sh + $ kubectl port-forward svc/kubernetes-dashboard -n kubernetes-dashboard 30090:80 + ``` -We can now access the minikube dashboard on `http://localhost:30090` + We can now access the minikube dashboard on `http://localhost:30090` ## Troubleshooting diff --git a/docs/local-minikube-setup.md b/docs/local-minikube-setup.md index 35d80a2f0d..ff732a5a6c 100644 --- a/docs/local-minikube-setup.md +++ b/docs/local-minikube-setup.md @@ -2,7 +2,7 @@ The preferred local development for the tackle2-ui is to install the Konveyor operator on a minikube instance. When the operator is installed and running, -the ui development server can attach to it and use the running hub api. There +the UI development server can attach to it and use the operator's hub api. There will also be a running UI instance to work with. The setup process follows the general steps: @@ -13,14 +13,6 @@ The setup process follows the general steps: - install the Konveyor operator - optionally add test data -## Konveyor Documentation - -A guide for installing minikube and Konveyor is also available in the general project -documentation. See document [Installing Konveyor](https://konveyor.github.io/konveyor/installation). - -For information on generic Kubernetes installation refer to -[Konveyor operator readme](https://github.com/konveyor/tackle2-operator#readme). - ## Install and start minikube [Minikube](https://github.com/kubernetes/minikube) implements a local Kubernetes cluster @@ -78,9 +70,89 @@ chmod +x install.sh ## Install the Konveyor Operator -Using the official Konveyor instructions for [Provisioning Minikube](https://konveyor.github.io/konveyor/installation/#provisioning-minikube) is an easy way to start. +There are a few good ways to install the Konveyor operator: + +- Use the script [`hack/setup-operator.sh`](/hack/setup-operator.sh). It is a local variation of + the script from the operator that applies all CRs needed to install the Konveyor operator and + setup the Tackle instance. Use of this script is described in the next section. + +- Follow the official instructions for [Installing Konveyor Operator](https://konveyor.github.io/konveyor/installation/#installing-konveyor-operator) + +- Use one of the `hack/install-*` scripts in the [konveyor/operator](https://github.com/konveyor/operator) + repository. These scripts require `kubectl` and the `operator-sdk`. + +### Running the setup script + +To run the setup script without cloning the repo, make sure the `kubectl` command (not alias) +is working and configured for minikube instance, and that the bash shell is available: + +```sh +curl https://raw.githubusercontent.com/konveyor/tackle2-ui/main/hack/setup-operator.sh -o setup-operator.sh +chmod +x setup-operator.sh +./setup-operator.sh +``` + +You may also run the script directly from you tackle2-ui clone: + +```sh +cd tackle2-ui/hack +./setup-operator.sh +``` -_TBD - Move more content from README.md_ +> [!WARNING] +> While CRDs are being established, you may see the script output `NotFound` errors. +> You can safely ignore these. The script will wait and recheck for the CRD again before +> proceeding. + +The installation is complete when the script outputs "condition met" messages and terminates. + +### Customizing the setup script + +The setup script provides optional environment variables that may be used to customize the +images used, settings, and features enabled during the install. + +Configuration environment variable include: +| variable | default | description | +| --- | --- | --- | +| TACKLE*CR | *(empty)\_ | Allows specifying the full Tackle CR | +| ADDON_ANALYZER_IMAGE | quay.io/konveyor/tackle2-addon-analyzer:latest | image for the ADDON_ANALYZER pod | +| ANALYZER_CONTAINER_REQUESTS_CPU | 0 | cpu count for the analyzer (0 is no restriction) | +| ANALYZER_CONTAINER_REQUESTS_MEMORY | 0 | memory size for the analyzer (0 is no restriction) | +| FEATURE_AUTH_REQUIRED | false | include keycloak SSO in operator deployment | +| HUB_BUCKET_VOLUME_SIZE | 100Gi | PV claim size for the HUB buckets | +| HUB_DATABASE_VOLUME_SIZE | 10Gi | PV claim size for the HUB database | +| HUB_IMAGE | quay.io/konveyor/tackle2-hub:lates | image for the HUB pod | +| IMAGE_PULL_POLICY | Always | When should images needed by the operator be pulled **link to docs for the pull policy** | +| NAMESPACE | konveyor-tackle | kubernetes namespace used | +| OPERATOR_INDEX_IMAGE | quay.io/konveyor/tackle2-operator-index:latest | base operator container image | +| UI_IMAGE | quay.io/konveyor/tackle2-ui:latest | image for the UI pod | +| UI_INGRESS_CLASS_NAME | nginx | nginx is the used as the ingress for minikube to access the UI | + +For example, if you wish to run tackle with keycloak authentication enabled, export the following variable before running the install script: + +```sh +export FEATURE_AUTH_REQUIRED=true +./setup-operator.sh +``` + +If the `TACKLE_CR` variable is defined, its contents will be used to create the `Tackle` +instance in lieu of one built in the script based on the other config variables. For +example, this will create a Tackle instance with authentication turned on and the UI +using a specially built test image: + +```sh +export TACKLE_CR=$(cat < ~/.bashrc.d/minikube + mkdir -p ~/.bashrc.d + cat << EOF > ~/.bashrc.d/minikube alias kubectl="minikube kubectl --" EOF - $ source ~/.bashrc + source ~/.bashrc ``` > [!WARNING] @@ -142,9 +214,24 @@ There are a few ways to set this up: the `$PATH` can be used. Installing for all system users can typically be done to `/usr/local/bin`: ```sh - $ cat << EOF > kubectl.sh + cat << EOF > kubectl.sh #! /usr/bin/env bash minikube kubectl -- $@ EOF - $ sudo install -m 777 kubectl.sh /usr/local/bin/kubectl + sudo install -m 777 kubectl.sh /usr/local/bin/kubectl ``` + +## Starting Over + +If at any point your minikube Konveyor operator instance stops working properly, it +is simple to destroy the environment and rebuild. + +To destroy an existing minikube instance (with Konveyor installed): + +```sh +minikube stop +minikube delete +``` + +Rebuild by starting a new instance of minikube and following the rest of the +install steps in this document.