Skip to main content
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​

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.

First login after deployment​

  • 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.

Error with login process​

  • 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.

Error with login process using IP address​

  • 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.