Skip to main content

Global View virtual appliance deployment

The Global View virtual appliance is delivered as an OVA (Open Virtualization Appliance) package that ships as a pre-configured, self-contained VM to simplify deployment and reduce operational overhead. Instead of manually installing and configuring each component, you deploy a single OVA that includes everything needed to run Global View out of the box.

The following components are pre-installed and configured. No manual setup required.

Component

Role

K3s

Lightweight, CNCF-certified Kubernetes distribution running Global View microservices.

Helm

Kubernetes package manager used to deploy and manage application components.

Docker

Container runtime for building and managing container images.

If you are deploying the Virtana Infrastructure Observability (IO) OVA, see IO Virtual Edition Guide.

Before you deploy the Global View virtual appliance, complete the virtual appliance prerequisites. See Virtual appliance (OVA) deployment prerequisites.

Virtual appliance installation

Select the hypervisor platform you are deploying to:

  • VMware vCenter

  • Nutanix

  • KVM

  • OpenShift Virtualization

Deploying the OVA in VMware vCenter is a critical step when setting up the Virtana Global View Virtual Appliance. The OVA serves as a pre-packaged, self-contained virtual machine that bundles the entire Global View application stack, including Keycloak (authentication), GrowthBook (feature management), and the main dashboard, into a single deployable unit. This approach ensures consistent, error-free deployments by eliminating manual OS and software configuration.

Deploy using either the VMware vSphere Client UI or the following ovftool CLI:

./ovftool --X:logFile=ovftool-log.txt \
  --X:logLevel=verbose --acceptAllEulas \
  --name="virtana-globalview" \
  --datastore="ds01" \
  --network="dv-net-xx" \
  --diskMode=thin \
  --vmFolder="testfolder" \
  ./virtana-k8s-xxxx.ova \
  vi://${USERNAME}:${PASSWORD}@${vCENTER_HOSTNAME}/<DATACENTER>/host/<COMPUTE_CLUSTER>/

This is a sample of the ovftool command. Modify parameters as needed.

Deploying the OVA in Nutanix is essential when setting up the Virtana Global View Virtual Appliance, as it provides a hyperconverged infrastructure (HCI) platform capable of hosting the pre-packaged virtual appliance. By deploying through Nutanix, organizations that have standardized on HCI infrastructure can leverage their existing environment without needing a separate VMware setup.

Deployment in Nutanix consists of two steps:

  1. Upload virtana-k8s-xxxx.ova and deploy the OVA from Prism Central. Refer to Deploying an OVA as VM for detailed steps.

  2. Power on and verify the VM from Prism Element. Refer to Managing a VM (AHV) for detailed steps.

Deploying the Virtual Machine in KVM (Kernel-based Virtual Machine) is essential when setting up the Virtana Global View Virtual Appliance on a Linux-based infrastructure. KVM is an open-source, type-1 hypervisor built directly into the Linux kernel, making it a cost-effective and high-performance alternative to proprietary platforms like VMware or Nutanix. The Global View application stack can be deployed as a VM on KVM by converting the OVA into a compatible disk image, such as QCOW2, and importing it using tools like virt-manager or virsh.

Perform the following steps:

  1. Download virtana-gv-kvm-xxxx.x.x.tar.gz from Egnyte and extract it:

    KVM_FILES_PATH="/var/lib/libvirt/images"   
    mkdir -p ${KVM_FILES_PATH}/virtana
    cd ${KVM_FILES_PATH}/virtana
    tar -xvzf virtana-gv-kvm-xxxx.x.x.tar.gz -C ${KVM_FILES_PATH}/virtana/
  2. (Optional) Update the OS machine type in vm.xml (default: q35). Get supported types with: /usr/libexec/qemu-kvm -machine help

    vim virtana-gv-kvm-xxxx.x.x/vm.xml
      <os>
        <type arch="x86_64" machine="q35">hvm</type>
      </os>
  3. Update the network bridge in vm.xml (default: network):

    vim virtana-gv-kvm-xxxx.x.x/vm.xml
        <interface type="network">
          <source network="default"/>
          <model type="virtio"/>
        </interface>
    Or
        <interface type="bridge">
          <source bridge="virbr0"/>
          <model type="virtio"/>
        </interface>
  4. Update disk file paths in vm.xml (default: /var/lib/libvirt/images):

    vim virtana-gv-kvm-xxxx.x.x/vm.xml
        <disk type="file" device="disk">
          <source file="/var/lib/libvirt/images/virtana/virtana-gv-kvm-2026.2.1/disk1.qcow2"/>
          ...
          <source file="/var/lib/libvirt/images/virtana/virtana-gv-kvm-2026.2.1/disk2.qcow2"/>
        </disk>
  5. Define and start the VM:

    virsh list --all
    virsh define virtana-gv-kvm-xxxx.x.x/vm.xml
    virsh start virtana-gv-kvm-xxxx.x.x
    virsh list --all
    virsh dominfo virtana-gv-kvm-xxxx.x.x
  6. Access the VM console and get the IP address:

    virsh console virtana-gv-kvm-xxxx.x.x
    virsh domifaddr virtana-gv-kvm-xxxx.x.x --source agent | grep -E "ipv4" | grep -Ev "(lo|docker0|tunl0)"

Perform the following steps to deploy Global View using OpenShift Virtualization:

  1. Create the namespace:

    oc new-project controlplane
  2. Check available StorageClasses:

    oc get sc
    oc get sc <sc-name> -o yaml | grep volumeBindingMode

    Note

    volumeBindingMode must be Immediate. Recommended StorageClass type is RWX (RWO is acceptable if RWX is unavailable).

  3. Create a working directory: mkdir -p ./virtana && cd ./virtana

  4. (Optional) Create a StorageClass with volumeBindingMode: Immediate:

    cat << EOF > virtana-storage-class.yaml
    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: <STORAGE_CLASS_NAME>-immediate
    provisioner: <PROVISIONER>
    parameters:
      type: <STORAGE_TYPE>
      encrypted: "true"
    reclaimPolicy: Retain
    volumeBindingMode: Immediate
    allowVolumeExpansion: true
    EOF
    oc apply -f virtana-storage-class.yaml
  5. Create DataVolumes (CDI Import) - 170Gi for root, 320Gi for data:

    cat << EOF > virtana-rootdisk.yaml
    apiVersion: cdi.kubevirt.io/v1beta1
    kind: DataVolume
    metadata:
      name: virtana-rootdisk
      namespace: controlplane
    spec:
      source:
        upload: {}
      pvc:
        accessModes:
          - <ReadWriteOnce / ReadWriteMany>
        resources:
          requests:
            storage: 170Gi
        storageClassName: <STORAGE_CLASS_NAME>
    EOF
    
    cat << EOF > virtana-datadisk.yaml
    apiVersion: cdi.kubevirt.io/v1beta1
    kind: DataVolume
    metadata:
      name: virtana-datadisk
      namespace: controlplane
    spec:
      source:
        upload: {}
      pvc:
        accessModes:
          - <ReadWriteOnce / ReadWriteMany>
        resources:
          requests:
            storage: 320Gi
        storageClassName: <STORAGE_CLASS_NAME>
    EOF
    
    oc apply -f virtana-rootdisk.yaml
    oc apply -f virtana-datadisk.yaml
  6. Verify DataVolume status is UploadReady:

    oc get datavolume -n controlplane
    oc get pvc -n controlplane
  7. Download and extract the Global View KVM tar file from Virtana Support:

    tar -zxvf virtana-gv-kvm-xxxx.x.x.tar.gz
  8. Install virtctl (skip if already installed):

    tar -zxvf virtctl.tar.gz
    chmod +x virtctl
    sudo mv virtctl /usr/local/bin/
    virtctl version
  9. Upload disk images to DataVolumes:

    virtctl image-upload dv virtana-rootdisk \
      -n controlplane \
      --image-path=./virtana-gv-kvm-xxxx.x.x/disk1.qcow2 \
      --insecure
    
    virtctl image-upload dv virtana-datadisk \
      -n controlplane \
      --image-path=./virtana-gv-kvm-xxxx.x.x/disk2.qcow2 \
      --insecure
  10. Deploy the Global View VirtualMachine object:

    cat << EOF > virtana-globalview-vm.yaml
    apiVersion: kubevirt.io/v1
    kind: VirtualMachine
    metadata:
      name: virtana-globalview
      namespace: controlplane
    spec:
      runStrategy: Manual
      template:
        metadata:
          labels:
            kubevirt.io/domain: virtana-globalview
        spec:
          domain:
            cpu:
              cores: 12
            resources:
              requests:
                memory: 48Gi
            devices:
              disks:
                - name: rootdisk
                  disk:
                    bus: virtio
                  bootOrder: 1
                - name: datadisk
                  disk:
                    bus: virtio
              interfaces:
                - name: default
                  masquerade: {}
              rng: {}
            features:
              acpi: {}
            machine:
              type: q35
          networks:
            - name: default
              pod: {}
          volumes:
            - name: rootdisk
              dataVolume:
                name: virtana-rootdisk
            - name: datadisk
              dataVolume:
                name: virtana-datadisk
    EOF
    oc apply -f virtana-globalview-vm.yaml

    The following table describes each field in the configuration file.

    Table 28.

    Field

    Description

    Default value

    Metadata and API

    apiVersion

    Specifies the KubeVirt API version used to define the virtual machine resource.

    kubevirt.io/v1

    kind

    Declares the resource type as a VirtualMachine managed by KubeVirt.

    VirtualMachine

    metadata.name

    The unique name assigned to this virtual machine within the cluster.

    virtana-globalview

    metadata.namespace

    The Kubernetes namespace where the VM will be deployed.

    controlplane

    Run strategy

    runStrategy

    The VM will not start automatically. It must be manually started by the administrator.

    Manual

    CPU and memory

    domain.cpu.cores

    Allocates 12 CPU cores to the VM, matching the OVA resource requirement of 12 vCPUs.

    12

    domain.resources.requests.memory

    Requests 48 GB of RAM for the VM, matching the OVA resource requirement.

    48Gi

    Disks

    disks[0].name

    The root volume disk for the OS and application stack.

    rootdisk

    disks[0].disk.bus

    Uses the virtio bus for high-performance disk I/O.

    virtio

    disks[0].bootOrder

    Marks this disk as the primary boot device.

    1

    disks[1].name

    The secondary disk for Virtana application data.

    datadisk

    disks[1].disk.bus

    Also uses virtio bus for optimal data disk performance.

    virtio

    Networking

    interfaces[0].name

    The primary network interface for the VM.

    default

    interfaces[0].masquerade

    Uses masquerade (NAT) mode, allowing the VM to access external networks through the pod's IP.

    {}

    networks[0].name

    Maps to the default pod network.

    default

    networks[0].pod

    Connects the VM to the Kubernetes pod network.

    {}

    Device and machine features

    devices.rng

    Provides a virtual random number generator for cryptographic operations and security.

    {}

    features.acpi

    Enables ACPI (Advanced Configuration and Power Interface) for proper power management and graceful shutdown.

    {}

    machine.type

    Uses the Q35 machine type, a modern chipset emulation that supports PCIe and is recommended for production VMs.

    q35

    Volumes

    volumes[0].name

    Links to the root disk defined in the disks section

    rootdisk

    volumes[0].dataVolume.name

    References a KubeVirt DataVolume that provisions the 150 GB root storage

    virtana-rootdisk

    volumes[1].name

    Links to the data disk defined in the disks section

    datadisk

    volumes[1].dataVolume.name

    References a KubeVirt DataVolume that provisions the 300 GB Virtana data storage

    virtana-datadisk

    Labels

    template.metadata.labels.kubevirt.io/domain

    A label used for identifying and selecting this VM's pods within the cluster, useful for networking and service discovery

    virtana-globalview



  11. Start the VM and verify it's running:

    virtctl start virtana-globalview -n controlplane
    oc get vmi virtana-globalview -n controlplane
  12. Access the VM console or via SSH:

    virtctl console virtana-globalview -n controlplane  
    virtctl ssh virtana@vmi/virtana-globalview -n controlplane

    Press ctrl+] to exit.

  13. (Optional) Create a LoadBalancer service for external access:

    cat << EOF > virtana-globalview-svc.yaml
    apiVersion: v1
    kind: Service
    metadata:
      name: virtana-globalview-svc
      namespace: controlplane
    spec:
      type: LoadBalancer
      selector:
        kubevirt.io/domain: virtana-globalview
      ports:
        - name: ssh
          port: 22
          targetPort: 22
        - name: https
          port: 443
          targetPort: 443
    EOF
    oc apply -f virtana-globalview-svc.yaml
    oc get service virtana-globalview-svc -n controlplane
    ssh virtana@<LB_IP/HOSTNAME>

Access the VM

SSH into the VM using the default credentials:

Username: virtana
Password: xxxxxx

You can change the default password immediately after the first login in any production environment.

(Optional) Configure a Static IP Address for the VM

By default, the appliance VM is configured to use DHCP (Dynamic Host Configuration Protocol) networking. If DHCP-based IP address allocation is not available in your environment, you can configure a static IP address by following the steps below.

Before making any changes, collect the following details from your network team:

Table 29.

Required Information

Description

Static IP Address

The fixed IP to assign to the VM.

Default Gateway

The network gateway address.

DNS Server Addresses

One or more DNS server IPs.

DNS Search Domain

The domain used for DNS resolution.



Switch to the root user and open the Netplan configuration file for editing:

su -
vim.tiny /etc/netplan/00-installer-config.yaml

Replace the contents with the following, substituting the placeholder values with the actual details gathered in Step 1:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens192:
      dhcp4: false
      addresses:
        - <STATIC_IP_ADDRESS>/24
      routes:
        - to: default
          via: <DEFAULT_GATEWAY>
      nameservers:
        search:
          - <example.com>
        addresses:
          - <DNS_SERVER_01>
          - <DNS_SERVER_02>

Perform the following steps:

  1. Validate the configuration to check for syntax errors before applying:

    sudo netplan generate
  2. Apply the new network configuration:

    sudo netplan apply

Note

Applying a new network configuration may temporarily interrupt SSH connectivity if the IP address changes. Ensure you have an alternative way to access the VM before proceeding.

Install and upgrade Global View

This section walks you through preparing the environment configuration, installing Keycloak and Global View, and upgrading to newer versions on the Virtana OVA VM.

Prepare the input environment file

Ensure that all required inputs are provided in the file located at /home/virtana/input.env on the VM. Below is the sample configuration:

CONNECTIVITY_TO_INTERNET='no'
IMAGE_REGISTRY='localhost:5000'         
DOCKER_SERVER='https://index.docker.io/v2/'  
DOCKER_USERNAME='<username>'
DOCKER_PASSWORD='<password>'
KEYCLOAK_HOSTNAME='example-keycloak.example.com'
GLOBAL_VIEW_HOSTNAME='example-globalview.example.com'
GROWTHBOOK_HOSTNAME='example-growthbook.example.com'
GROWTHBOOK_API_HOSTNAME='example-growthbook-api.example.com'
TENANT_NAME='xxxxx'                     
INITIAL_ADMIN_USER_FIRSTNAME='xxxxx'
INITIAL_ADMIN_USER_LASTNAME='xxxxx'
INITIAL_ADMIN_USER_EMAIL='xxxxx.xxxxx@xxxxx.com'

SMTP_CHECK_ENABLED='true'
SMTP_HOST='smtp.xxxxx.com'
SMTP_PORT='587'
SMTP_USERNAME='xxxxx'
SMTP_PASSWORD='xxxxx'
SMTP_FROM_EMAIL='noreplies@xxxxx.com'
CO_NORTH_HELM_VERSION='xxxx.x.x'
GLOBAL_VIEW_HELM_VERSION='xxxx.x.x'

VIRTANA_AI_MODEL_PROVIDER=''
VIRTANA_AI_API_KEY=''
VIRTANA_AI_INFERENCE_ENDPOINT=''

ENABLE_REMOTE_WISDOM='no'
THINGWORX_PLATFORM_URL='virtualinstruments.axeda.com'             
THINGWORX_AGENT_MODEL='GlobalView'               

The following table describes each field in the configuration file.

Table 30.

Field

Description

Mandatory configuration

CONNECTIVITY_TO_INTERNET

Set to yes to download and deploy container images directly from the Virtana container registry over an internet connection.

Set to no to use the container images bundled with the Virtana OVA package, located in /opt/virtana, or retrieve images from a self-hosted private container registry.

IMAGE_REGISTRY

Address of the private container image registry used for deployment.

DOCKER_SERVER

Docker registry server URL for pulling images.

DOCKER_USERNAME

Username for authenticating with the Docker registry.

DOCKER_PASSWORD

Password for authenticating with the Docker registry.

KEYCLOAK_HOSTNAME

External DNS hostname for the Keycloak identity/authentication server.

GLOBAL_VIEW_HOSTNAME

External DNS hostname for the Global View application UI.

GROWTHBOOK_HOSTNAME

External DNS hostname for the GrowthBook feature flagging UI.

GROWTHBOOK_API_HOSTNAME

External DNS hostname for the GrowthBook API endpoint.

TENANT_NAME

Name of the tenant or organization being configured.

INITIAL_ADMIN_USER_FIRSTNAME

First name of the initial administrator user.

INITIAL_ADMIN_USER_LASTNAME

Last name of the initial administrator user.

INITIAL_ADMIN_USER_EMAIL

Email address of the initial administrator user.

SMTP configuration

SMTP_CHECK_ENABLED

Enables or disables SMTP email functionality. Set to falseif no mail server is available.

SMTP_HOST

Hostname of the SMTP mail server.

SMTP_PORT

Port number for the SMTP server.

SMTP_USERNAME

Username for SMTP authentication. Leave blank if auth is not required.

SMTP_PASSWORD

Password for SMTP authentication.

SMTP_FROM_EMAIL

The sender email address used in outgoing emails.

Application versions

CO_NORTH_HELM_VERSION

Helm chart version for the CO North component. Needed for deploying Keycloak.

GLOBAL_VIEW_HELM_VERSION

Helm chart version for the Global View component.

Virtana AI Copilot

VIRTANA_AI_MODEL_PROVIDER

The LLM provider to use, such as OPENAI, GEMINI, or LITELLM.

VIRTANA_AI_API_KEY

API key for the selected AI model provider.

VIRTANA_AI_INFERENCE_ENDPOINT

Inference endpoint URL. Only needed for self-hosted LiteLLM deployments, and leave blank for OpenAI/Gemini.

Remote wisdom agent

ENABLE_REMOTE_WISDOM

Enables integration with the Remote Wisdom agent.

THINGWORX_PLATFORM_URL

URL of the ThingWorx platform for Remote Wisdom connectivity.

THINGWORX_AGENT_MODEL

ThingWorx agent model identifier. Values provided by Virtana Support.



Do not change the values of IMAGE_REGISTRY and DOCKER_SERVER unless using your own private registry.

For a default OVA deployment, the CO_NORTH_HELM_VERSION and GLOBAL_VIEW_HELM_VERSION values in the input.env file are pre-populated based on the OVA release and do not need to be modified.

Run the following commands if you intend to deploy or upgrade to a different Helm chart version than the one bundled with the OVA:

helm repo update
helm search repo virtana-repo/virtana-global-view
helm search repo virtana-repo/virtana-co-controller

Note

Keycloak Helm chart is bundled as part of the virtana-repo/virtana-co-controller Helm chart.

The OPENAI_API_KEY is not required for initial setup. See the Configure LLM Provider for Virtana AI for instructions on generating one when needed.

Install applications

Both Keycloak and Global View must be installed. You may install them together or sequentially.

Keycloak must be installed before Global View. If installing separately, always run Keycloak first.

For a standard OVA installation, the Helm chart versions in input.env are already set to the correct bundled versions and should not be changed. The deployment script (deploy.sh) will automatically use these versions.

Manual Helm commands are not required for the initial deployment. The helm repo update and helm search commands listed below are only necessary if you are overriding the default bundled versions:

helm repo update
helm search repo virtana-repo/virtana-global-view
helm search repo virtana-repo/virtana-co-controller

Additionally, if you need to override or customize any Helm chart configuration, you can modify the values.yaml file before deployment.

To override any Helm chart configuration, modify the values templates before deployment:

ls -l /home/virtana/templates/

The following table shows the actions and the respective commands:

Table 31.

Action

Command

Install Keycloak and Global View together

bash /home/virtana/deploy.sh all

Install Keycloak only

bash /home/virtana/deploy.sh keycloak

Install Global View only

bash /home/virtana/deploy.sh globalview



Install RemoteWisdom (optional)

RemoteWisdom is an optional remote-connectivity agent for the Global View virtual appliance. When you install it, Virtana Support can securely connect to your Global View deployment to help monitor it and troubleshoot issues. Complete this procedure only if you want to enable remote support for Global View.

To install RemoteWisdom, complete the following steps:

  1. In /home/virtana/input.env, enable RemoteWisdom by setting the following value:

    ENABLE_REMOTE_WISDOM='yes'
  2. In /home/virtana/input.env, confirm that the ThingWorx platform URL and agent model use the following values:

    THINGWORX_PLATFORM_URL='virtualinstruments.axeda.com'
    THINGWORX_AGENT_MODEL='GlobalView'
  3. Get the Global View UUID by running the following command, and then share the output with Virtana Support:

    cat /opt/virtana/remote-wisdom/serial-number
  4. Install RemoteWisdom by running the following command:

    bash deploy.sh remotewisdom

Note

Virtana Support adds your Global View instance to the Virtana ThingWorx platform, using the UUID you provide, to enable communication between the appliance and the platform.

Post-deployment troubleshooting

After a successful Global View deployment, the initial admin registration email may not be received even though SMTP is correctly configured and validated. This can occur when the user-settings-service fails to communicate with the authorization-service during the initial setup sequence.

You may view the following symptoms:

  • Deployment completes successfully with no errors.

  • SMTP test email is received successfully, confirming SMTP configuration is correct.

  • The registration/invitation email for the initial admin user has not been delivered.

  • Without the registration email, the Global View UI cannot be accessed.

A transient inter-service communication failure may occur during the initial deployment, where the user-settings-service is unable to reach the authorization-service. The following error in the user-settings-service logs confirms this issue:

{"level":"error","service":"user-settings-service","error":"Post \"http://authorization-service-svc:5000/internal/authorization/oauth/authorize\": dial tcp 10.43.52.101:5000: connect: connection refused","method":"POST","url":"http://authorization-service-svc:5000/internal/authorization/oauth/authorize","message":"Failed to handle http request."}

If the registration email is not received after a fresh deployment, perform the following steps:

  1. Confirm that SMTP settings in /home/virtana/input.env are correct and that the SMTP test email was received successfully.

  2. Check user-settings-service logs for authorization-service communication errors:

    kubectl logs deploy/user-settings-service -n controlplane | grep -i "authorization"
  3. If the logs confirm the inter-service communication failure, clean up the existing deployment and perform a fresh redeployment:

    bash /home/virtana/deploy.sh all