Version: 0.4.0-beta

Wizard Client Web UI Deployment

In addition to the Wizard Client (CLI), the Wizard Client Web UI is available for users who prefer a graphical interface. The Wizard Client Web UI can be deployed using a helm chart on Kubernetes.

Prerequisites

Before you start, ensure the following are available:

A running Kubernetes cluster. Cluster Admin privileges are recommended, though a namespace admin role may be sufficient.
- Please see quick-start for a K3s or docker Compose deployment.
A Kubernetes-compatible load balancer (e.g., MetalLB or LoxiLB) if you plan to expose Wizard Client Web UI using the LoadBalancer service type.
An ingress controller (e.g., NGINX or HAProxy) must be installed if you plan to expose Wizard Client Web UI using Kubernetes Ingress.

Requirements

Access to helm chart : https://charts.cluster-wizard.com/
Prepared Kubernetes secret if needed
- Cluster Wizard server CA

Wizard Client Web UI Installation

Assuming that

Website address is wizard-client-webui.example.com
Load Balancer is used for exposing website externally, and the load balancer ip is 192.168.132.251
Cluster Wizard is deployed in Kubernetes namespace cluster-wizard and accessible on 192.168.100.100:50001
A server CA is provided in secret name cluster-wizard-server-ca

note

The URL needs to be a valid DNS entry.

Preparing Secret

Wizard Client Web UI requires a secret referencing the server’s Certificate Authority (Cluster Wizard server CA) if it is not trusted — such as in cases where it's self-signed. This is optional, but it becomes required when the Cluster Wizard’s CA is not trusted.

kubectl create namespace wizard-client
kubectl create secret generic cluster-wizard-server-ca -n wizard-client \
    --from-file=ca.crt=[server ca]

The server CA could be obtained from Cert Manager if it is used for Cluster Wizard certificates.

kubectl get secret server-ca -n cluster-wizard -o jsonpath='{.data.ca\.crt}' | base64 -d > server-ca.crt
kubectl create secret generic cluster-wizard-server-ca -n wizard-client \
    --from-file=ca.crt=server-ca.crt

Wizard Client Web UI Helm Installation

A matching helm chart version for Wizard Client 0.4.x versions is 0.1.0.

helm repo add cluster-wizard https://charts.cluster-wizard.com/  
helm repo update cluster-wizard  
helm search repo cluster-wizard/wizard-client-webui --versions
helm fetch cluster-wizard/wizard-client-webui --version 0.1.0 --untar
helm -n wizard-client install wizard-client-webui ./wizard-client-webui --values ./wizard-client-webui-values-override.yaml

Helm values

Below is a minimal set of helm values needed to deploy

configMap.backendUrl: backend address, with backPort if backendUrl's same as frondEndUrl
configMap.frontendUrl: frontend website address
configMap.clusterWizardHost: "&clusterWizardHost" is used for etcHost.clusterWizardHost, host name that will be reached by Wizard Client
configMap.clusterWizardPort: Cluster Wizard port that will be reached by Wizard Client
etcHost.clusterWizardIP: Cluster Wizard host IP address
etcHost.clusterWizardHost: "*clusterWizardHost" is referring "&clusterWizardHost" in configMap.clusterWizardHost
clusterWizardCASecretName: secret name for Cluster Wizard server CA if it is used
expose.type: loadBalancer is used here and other types are ingress, clusterIP and nodePort
configuration for loadBalancer
- expose.loadBalancer.IP: external IP address for Webui
- expose.loadBalancer.ports.frontPort : service port for frontend
- expose.loadBalancer.ports.backPort : service port for backend

The wizard-client-webui-values-override.yaml file will be like

---
configMap:
  backendUrl: "wizard-client-webui.example.com:23051"
  frontendUrl: "wizard-client-webui.example.com"

  clusterWizardHost: &clusterWizardHost "cluster-wizard"
  clusterWizardPort: "50001"

etcHost:
  addClusterWizard: true
  clusterWizardIP: "192.168.100.100"
  clusterWizardHost: *clusterWizardHost

clusterWizardCASecretName: "cluster-wizard-server-ca"

expose:
  type: loadBalancer
  loadBalancer:
    IP: "192.168.132.251"
    ports:
      frontPort: 25080
      backPort: 23051

Next Steps

To access the Wizard Client Webui, a user certificate and key are required. The admin certifcate and key would be generated from Cluster Wizard deployment and obtained from the Kubernete's secret admin-cred.

kubectl get secret admin-cred -n cluster-wizard -o jsonpath='{.data.cert}' | base64 -d > admin-cert.crt
kubectl get secret admin-cred -n cluster-wizard -o jsonpath='{.data.private_key}' | base64 -d > admin-private.key

Various Expose Methods

There are a few more methods for exposing services: ingress, proxy server (with clusterIP service) and nodePort.

Ingress

Kubernetes Ingress is an API object that manages external access to services within a cluster, typically HTTP and HTTPS traffic.

In the helm chart, rewrite rules was added such that backend server URL is in a form of [frontend server URL]/backend. These annotations are for Nignx and HAProxy ingress classes. If a different ingress class is used, appropriate annotations need to be added.

The following example wizard-client-webui-values-override.yaml file is for the case where

haproxy ingress class is used
A cert manager's cluster issuer (named selfsigned-cluster-issuer) is used for automatic certificate generation
The complete frontend server URL is https://wizard-client-webui.example.com

configMap:
  backendUrl: "wizard-client-webui.example.com/backend"
  frontendUrl: "wizard-client-webui.example.com"

expose:
  type: ingress
  ingress:
    tls:
      enabled: true
      clusterIssuer: "selfsigned-cluster-issuer"
      certSource: "secret"
      secretName: "wizard-client-webui.example.com"
    host: wizard-client-webui.example.com
    className: "haproxy"

For http service, remove the tls section.

Over Proxy Server

A proxy server is an intermediary server that sits between clients and other servers. It acts as a gateway, receiving requests from clients and forwarding them to destination servers, then returning the responses back to the clients.

In Kubernetes clusters, an application proxy server (such as Nginx Proxy server and HAProxy) is often used. We can use a proxy server to expose wizard-client-webui servers.

Depending on how a proxy server is configured, the values are similar either to that of ingress or to that of load balancer. If the proxy server provides TLS communication, tlsOverProxy.enabled should be true. The FrontendURL and BackendURL should be set accordingly.

The following example wizard-client-webui-values-override.yaml shows how to specify values when

tls commuincation is provided by a proxy server
the same rewrite rule is implemented in a proxy server

---
configMap:
  backendUrl: "wizard-client-webui.example.com/backend"
  frontendUrl: "wizard-client-webui.example.com"

expose:
  tlsOverProxy:
    enabled: true

This will create a Kubernetes service object of clusterIP type. A proxy server forwards requests to the frontend/backend server to this service.

Node Port

NodePort is a type of Kubernetes Service that exposes an application running in a cluster by allocating a specific port on every node in the cluster. It's one of the primary ways to make services accessible from outside the Kubernetes cluster.

NodePort value is similar to that of load balancer. A simple example wizard-client-webui-values-override.yaml is shown below.

---
configMap:
  backendUrl: "wizard-client-webui.example.com:30003"
  frontendUrl: "wizard-client-webui.example.com:30002"

expose:
  internalTLS:
    enabled: true
    secretName: "tls-secret"
  type: nodePort

info

To add a host, a token for node-wizard is necessary. This token will be printed when node-wizard is installed. To retrieve this token, run the following command.

sudo /root/bin/node_wizard/node-wizard --token

To attach a PCI device, its PCI address needs to be added to allowed (PCI address) list.

# Add a PCI address to the allowed list
sudo /root/bin/node_wizard/node-wizard --add-allowed [PCI address]
# To print the list
sudo /root/bin/node_wizard/node-wizard --list-allowed

To prevent a bridge to be attached, the network device/bridge needs to be added to disallowed list

# Add a Device/Bridge to the disallowed list
sudo /root/bin/node_wizard/node-wizard --add-disallowed [network device/bridge]
# To print the list
sudo /root/bin/node_wizard/node-wizard --list-disallowed

Troubleshooting

Quick Diagnostic Commands

Run these first to quickly assess the situation:

# Check if pods are running
kubectl get pods -n wizard-client

# Check for event logs (e.g., FailedMount, CrashLoopBackOff)
kubectl describe pod <pod-name> -n wizard-client

# Check Wizard Client logs
kubectl logs deployment/wizard-client-webui -n wizard-client

# Check if Wizard Client Web UI service is running
kubectl get service -n wizard-client

Common Problems

The cluster-wizard helm repo is not available

Helm Output:

helm search repo cluster-wizard/wizard-client-webui --versions
No results found

helm fetch cluster-wizard/wizard-client-webui --version 0.1.0 --untar
Error: repo cluster-wizard not found

Cause: The cluster-wizard helm repo is not available.
Solution: Add the cluster-wizard repo. helm repo add cluster-wizard https://charts.cluster-wizard.com/. See Helm Installation for detailed steps.

Helm release already installed in namespace

Helm Output:

Error: INSTALLATION FAILED: cannot re-use a name that is still in use

Cause: Helm sees a release named wizard-client already installed in namespace wizard-client. Helm release names must be unique per namespace.
Solution:
1. Check if wizard-client is already deployed
```
helm list -n wizard-client
```
1. If you want to update the existing deployment, use:
```
helm -n wizard-client upgrade --install wizard-client-webui ./wizard-client-webui --values ./wizard-client-webui-values-override.yaml
```
This applies your changes to the current release without uninstalling it.
1. If you want a clean install of the Wizard Client Web UI deployment:
  
  a. Delete existing release:
```
helm uninstall wizard-client-webui -n wizard-client
```
  b. Reinstall Wizard Client Web UI, see Wizard Client Web UI Helm Installation.
```
helm -n wizard-client install wizard-client-webui ./wizard-client-webui --values ./wizard-client-webui-values-override.yaml
```

Missing "wizard-client" Kubernetes namespace

Helm Output:

Error: INSTALLATION FAILED: create: failed to create: namespaces "wizard-client" not found

Cause: The Kubernetes namespace wizard-client has not been created.
Solution: Create Kubernetes namespace wizard-client
```
kubectl create namespace wizard-client
```

Missing Kubernetes secret

Wizard Client Pod Status stuck in CreateContainerConfigError

kubectl get pods -n wizard-client shows Status: CreateContainerConfigError

kubectl get pods -n wizard-client
NAME                                   READY   STATUS                       RESTARTS   AGE
wizard-client-webui-6f44c77d64-ssjdf   0/1     CreateContainerConfigError   0          7m8s

Pod details show secret "cluster-wizard-server-ca" not found

kubectl describe pod wizard-client-webui-6f44c77d64-ssjdf shows secret "cluster-wizard-server-ca" not found

 kubectl describe pod wizard-client-webui-6f44c77d64-ssjdf -n wizard-client
 Events:
   Type     Reason     Age                   From               Message
   ----     ------     ----                  ----               -------
   Normal   Scheduled  2m59s                 default-scheduler  Successfully assigned cluster-wizard-yk/wizard-client-webui-6f44c77d64-ssjdf to k8s-worker03
   Warning  Failed     53s (x12 over 2m58s)  kubelet            Error: secret "cluster-wizard-server-ca" not found

Cause: The secret referenced by clusterWizardCASecretName was not created.
Solution: Create the secret if the server CA is used. If it is not used, do not set clusterWizardCASecretName for Helm installation. See Preparing Secret.

Pending Kubernetes service

Wizard Client Kubernetes Service stuck in pending state.

kubectl get service -n wizard-client shows EXTERNAL-IP: <pending>

kubectl get service -n wizard-client
NAME                          TYPE           CLUSTER-IP      EXTERNAL-IP       PORT(S)                           AGE
wizard-client-webui-service   LoadBalancer   10.233.37.160   <pending>         25080:31511/TCP,23051:30637/TCP   3d23h

Cause: The service type is not configured correctly or required Kubernetes components are missing.
Solution: Configure the service expose properly for Helm installation. See Helm Installation or Various Expose Methods. If load bancer or ingress is used for expose, install any required Kubernetes components for that. See Prerequisites

Unable to reach Wizard Client Web UI

Wizard Client Web UI URL cannot be opened from a web browser.

This site can’t be reached
Check if there is a typo in wizard-client-webui.example.com.
DNS_PROBE_FINISHED_NXDOMAIN

Cause: The domain name is not in a valid DNS entry.
Solution: Add the domain name to a DNS entry.

A user certificate and private key files are required to login but not provided from Wizard Client Web UI.
Cause: Admin credentials are generated during Cluster Wizard deployment.
Solution: Obtain the admin credentials from the Kubernete's secret admin-cred. See Next Steps.

A user cannot login.

Error with login process. Please retry later or verify your credentials !

Cause: A private key or certificate file is not valid or don't match.
Solution: Use a valid key/certificate files or re-generate keys/csr to get a valid certificate file from admin.

Wizard Client Web UI is reachable using IP address but login failed.
Cause: A domain name is used for frontendUrl/backendUrl not IP address.
Solution: Use the domain name as URL instead of IP address if the domain name is used as configMap.frontendUrl and configMap.backendUrl for deployment.

Prerequisites​

Requirements​

Wizard Client Web UI Installation​

Preparing Secret​

Wizard Client Web UI Helm Installation​

Helm values​

Next Steps​

Various Expose Methods​

Ingress​

Over Proxy Server​

Node Port​

Troubleshooting​

Quick Diagnostic Commands​

Common Problems​

The cluster-wizard helm repo is not available​

Helm release already installed in namespace​

Missing "wizard-client" Kubernetes namespace​

Missing Kubernetes secret​

Pending Kubernetes service​

Unable to reach Wizard Client Web UI​

First login after deployment​

Error with login process​

Error with login process using IP address​

Prerequisites

Requirements

Wizard Client Web UI Installation

Preparing Secret

Wizard Client Web UI Helm Installation

Helm values

Next Steps

Various Expose Methods

Ingress

Over Proxy Server

Node Port

Troubleshooting

Quick Diagnostic Commands

Common Problems

The cluster-wizard helm repo is not available

Helm release already installed in namespace

Missing "wizard-client" Kubernetes namespace

Missing Kubernetes secret

Pending Kubernetes service

Unable to reach Wizard Client Web UI

First login after deployment

Error with login process

Error with login process using IP address