OpenShift Console Plugin For Forklift
forklift-console-plugin is an open source project providing Openshift web console plugin for Migration Toolkit for Virtualization. The plugin adds a web based user interface for Migration Toolkit for Virtualization inside Openshift web console.
Migration Toolkit for Virtualization (Forklift) is a suite of migration tools that facilitate the import of virtualization workloads from oVirt, vmWare and OpenStack to OpenShift Virtualization.
Prerequisites
Quick start
forklift-console-plugin is automatically installed when installing the Forklift operator (ver 2.4+). A user can also install the plugin manually using Helm on a cluster with forklift operator already installed.
The folowing script will use Helm to install the plugin on Openshift with a running forklift controller:
# add the forklift helm repo
helm repo add forklift https://kubev2v.github.io/forklift-console-plugin
# install the chart using the repository package
helm install forklift-console-plugin forklift/forklift-console-plugin \
--set forklift.namespace=<the forklift operator namespace>
forklift-console-plugin will add new menu item under the virtualization
section for virtualization workloads import in Openshift web console.
Development
Using the development constainer image
Use an Openshift cluster you have admin privileges on, or spin your own OpenShift Local cluster, Install Forklift with console plugin feature turned off. On your cluster, grant privileged capabilites to the development service account, and deploy the development environment, if you do not have admin access to an Openshift cluster, you can use KinD or OpenShift Local to create a small development cluster on your PC.
# deploy the development pod
NAMESPACE=konveyor-forklift
IMAGE=quay.io/kubev2v/forklift-console-plugin-dev
TEMPLATE=https://raw.githubusercontent.com/kubev2v/forklift-console-plugin/main/ci/yaml/forklift-plugin-dev.tpl.yaml
# give the development service accoun privileged capabilites
oc create namespace ${NAMESPACE}
oc adm policy add-scc-to-user privileged system:serviceaccount:${NAMESPACE}:default
oc process -f ${TEMPLATE} -p=NAMESPACE=${NAMESPACE} -p=IMAGE=${IMAGE} | oc apply -f -
You can enable the plugin using the web console, or using an oc patch
command
oc patch consoles.operator.openshift.io cluster \
--patch '{ "spec": { "plugins": ["forklift-console-plugin"] } }' --type=merge
login into the develoment environment using user:dev password: dev.
# use the IP of any node in the cluster your network setup can reach
# for example, use crc command to get the crc node ip
HOST=$(crc ip)
ssh dev@${HOST} -p 30022 # password: dev
# inside the develpment environment
cd forklift-console-plugin
# add your git remote
# edit the code
# start a develoment server on port 9443
npm run start --port 9443 \
--server-type https \
--server-options-key /var/serving-cert/tls.key \
--server-options-cert /var/serving-cert/tls.crt
See develop-with-crc for more information about Forklift plugin development environment on Openshift.
Alternatively, see develop-with-kind for more information about Forklift plugin development environment on kubernetes cluster deployed using KinD.
Development on local PC
Requirements
forklift-console-plugin development require web development tools, and a kubernetes or Openshift cluster. You can use any available Openshift cluster, or deploy your own small development cluster on your local PC, using OpenShift Local or KinD.
requirements | |
---|---|
nodejs | JavaScript runtime environment |
kubernetes | An Openshift or kubernetes cluster for development |
kubectl | The Kubernetes command-line tool |
Mock data is avaliable for development without needing to use forklift API servers, it is also posible to use the forklift API servers for development. you can install forklift and kubevirt operators if you want to interact with these APIs.
optional | |
---|---|
oc | The Openshift command-line tool |
forklift | forklift controller running on the development cluster |
kubevirt | kubevirtcontroller running on the development cluster |
Spin your own small kubernetes
It is posible to create a small Openshift environment using OpenShift Local or KinD. Openshift local will install all the neccary services. When installing a cluster using KinD, you may want to setup a custom development enviormnet manually.
This example script is using KinD to deploy a minimal kubernetes cluster with storage, registry and admin user.
# deploy small local kubernetes cluster using kind command line utility
bash ci/deploy-cluster.sh
# delete the cluster and local registry, this script will remove any
# workload or data currenly in the local cluster or the local registry
# this script may be usufull for development when starting a new session
bash ci/clean-cluster.sh
Note:
Running virtualized workloads (e.g. virtual machines) on this cluster requires starting the cluster using the root user (e.g. sudo bash ci/deploy-cluster.sh
)
See cli docs for more information about Openshift local and Kind.
Running development server on local PC using mock data
In one terminal window, run:
npm install
DATA_SOURCE=mock npm run start
This will install the node modules needed for development and start the plugin development server,
the start
script uses this environment varialbles:
Environment varialbles | Description |
---|---|
DATA_SOURCE | 'mock' or 'remote', when set to 'mock', the plugin will show recorded data, (default 'remote') |
BRAND_TYPE | 'RedHat' or 'Konveyor', when set to 'RedHat' some strings will change to reflect downstream product names, (default 'Konveyor') |
Make sure you are connected to your kubernetes cluster and in another terminal window, run:
npm run start:console
[ Optional, if running using Openshift cluster you can use npm run start:console:oauth
, this command will run the Openshift console using the clusters oAuth server. ]
This will run the OpenShift console in a container connected to the cluster you are currently logged into. The plugin HTTP server runs on port 9001 with CORS enabled, the development server will be available at http://localhost:9000
start:console
script uses this environment varialbles:
Environment varialbles | Description |
---|---|
CONSOLE_IMAGE | The console image to run ( default quay.io/openshift/origin-console:latest ) |
CONSOLE_PORT | Expose the console web application on port ( default 9000 ) |
INVENTORY_SERVER_HOST | URL of Forklift inventory server ( default http://localhost:30088 ) |
MUST_GATHER_API_SERVER_HOST | URL of Forklift must gather server ( default http://localhost:30089 ) |
BRIDGE_K8S_AUTH_BEARER_TOKEN | Bearer token of user account ( on openshift token default to $(oc whoami -t) ) |
BRIDGE_K8S_MODE_OFF_CLUSTER_ENDPOINT | Kubernetes API servere URL (default, guess useing kubeconfig file) |
Note: when running the plugin on a cluster with no forklift install, you can install only the missing CRDs using this command:
kubectl apply -f ci/yaml/crds
Running development server on local PC using remote forklift API server
When running OpenShift Local you can install forklift and kubevirt using the OperatorHub, on KinD you can use the CI scripts.
Before starting the development server, set the inventory and must-gather hosts to match the forklift API servers, for example:
# example of using forklift API running inside our Openshift cluster (using the oc command line utility)
export BRIDGE_K8S_MODE_OFF_CLUSTER_ENDPOINT:=$(oc whoami --show-server)
export BRIDGE_K8S_AUTH_BEARER_TOKEN=$(oc whoami --show-token)
export INVENTORY_SERVER_HOST=https://$(oc get routes -o custom-columns=HOST:.spec.host -A | grep 'forklift-inventory' | head -n 1)
export MUST_GATHER_API_SERVER_HOST=https://$(oc get routes -o custom-columns=HOST:.spec.host -A | grep 'forklift-mustgather' | head -n 1)
# start the openshift web console using Openshift oAuth server
# NOTE:
# when using forklift API server with authentication feature turned on
# we need to run the development server using openshift oauth service
npm run start:console:oauth
# start the forklift console plugin (default is DATA_SOURCE=remote)
npm run start
For more information about plugin development options, see the forklift-console-plugin docs.
Learn more
Reference | |
---|---|
Forklift | Migration toolkit for virtualization |
Openshift web console | Openshift web console is a web based user interface for Openshift. |
OpenShift Dynamic Plugin SDK | Dynamic plugin SDK for Openshift user interfaces. |
Forklift documentation | Usage documentation for the migration toolkit for viertualization. |
Forklict CI | Collection of scripts and tools used in forklict development. |
Patternfly | Open source design system used for Openshift user interfaces development. |