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.

Virtual appliance deployment prerequisites

Before deploying the Virtana Global View virtual appliance, you must complete the following prerequisites outlined in this document. Each step is critical to ensuring a successful deployment.

OVA resource requirements

An OVA (Open Virtual Appliance) is a pre-packaged virtual machine file used to deploy software in virtualized environments like VMware ESXi. The Virtana Global View application is distributed as an OVA file, such as virtana-k8s-xxxx.ova, allowing you to deploy the entire platform as a ready-to-use virtual appliance.

The configuration below is bundled with the OVA. No manual modification is needed unless your environment requires customization.

Table 26.

Configuration parameter

Configuration

Compatibility

ESXi 6.5 and later

Guest OS

Ubuntu 64-bit (Linux)

CPU

12 vCPUs

Memory

48 GB RAM

Disk 01 (root volume)

200 GB (Thin Provision)

Disk 02 (Virtana data)

300 GB (Thin Provision)

SCSI Controller

VMware Paravirtual

Network Adapter Type

VMXNET3



SMTP configuration

SMTP (Simple Mail Transfer Protocol) is the standard Internet protocol used for sending emails between servers. SMTP configuration is mandatory for Global View deployment. The deployment validation will fail if valid SMTP details are not provided. SMTP configuration is mandatory for Global View deployment to enable email-based functionality, including user onboarding invitations, forgot password/password reset emails, and alert and notification emails.

Gather the following details from your existing SMTP server before beginning deployment:

Parameter

Description

SMTP_HOST

SMTP server hostname or IP address

SMTP_PORT

SMTP server port (typically 25, 587, or 465)

SMTP_USERNAME

SMTP authentication username

SMTP_PASSWORD

SMTP authentication password

SMTP_FROM_EMAIL

Sender email address

These values must be provided during Global View deployment in the input.env file. The deployment process validates the SMTP configuration to help prevent application setup failures caused by incorrect SMTP settings.

DNS records

DNS (Domain Name System) records are entries in a DNS server that map human-readable domain names (like globalview.example.com) to machine-readable IP addresses (like 192.168.1.10) or other domain names. DNS records are required for deployment because the platform exposes multiple web-accessible services that must each be reachable through a dedicated hostname.

Create the following DNS records, all pointing to the VM's IP address:

Table 27.

Service

Purpose

Example Hostname

Keycloak

An open-source identity and access management, SSO, and user authentication

example-keycloak.example.com

Global View

Main application dashboard

example-globalview.example.com

GrowthBook

An open-source platform for feature flagging (controls GV feature rollout)

example-growthbook.example.com

GrowthBook API

GrowthBook API endpoint

example-growthbook-api.example.com



Download and verify the OVA

The OVA files are available on demand. Contact Virtana Support if you'd like to try it out.

Files to download:

  • virtana-k8s-xxxx.ova

  • virtana-k8s-xxxx.ova.sha256

After downloading, verify the integrity of the OVA locally.

Run the command in your local environment.

sha256sum -c virtana-k8s-xxxx.ova.sha256

Expected output:

virtana-k8s-xxxx.ova: OK

Download the image bundle (Optional)

The approach depends on whether the VM has internet access and whether you have a private registry.

Internet access - no private registry

Images will be automatically pulled from the Docker Hub Virtana registry. No additional steps required. Proceed to install applications.

Internet access - with private registry

Perform the steps:

  1. Download the image list text file from Virtana Egnyte.

  2. Pull images on an internet-connected machine and push them to your private registry.

  3. Update the IMAGE_REGISTRY and DOCKER_SERVER variables in the input file input.env to point to your private image registry:

    CONNECTIVITY_TO_INTERNET='yes'
    IMAGE_REGISTRY='custom-registry:8443'
    DOCKER_SERVER='https://custom-registry:8443/'

No internet access - with private registry

Perform the steps:

  1. Download the image list text file gv-images-list.txt, from Virtana Egnyte.

  2. Pull images on an internet-connected machine and push them to your private registry.

  3. Download Helm charts from Egnyte and place them in /home/virtana/helm-charts/ on the VM.

  4. Update the IMAGE_REGISTRY and DOCKER_SERVER variables in the input file input.env to point to your private image registry:

    CONNECTIVITY_TO_INTERNET='no'
    IMAGE_REGISTRY='custom-registry:8443'
    DOCKER_SERVER='https://custom-registry:8443/'

No internet access - without private registry

Perform the steps:

  1. Download the image bundle from virtana-global-view-<GV_VERSION>-images-bundle.tgz from Egnyte.

  2. Copy the bundle to /opt/virtana on the Virtana OVA VM.

  3. Do not extract the bundle manually. The deploy script handles extraction automatically.

  4. Set in CONNECTIVITY_TO_INTERNET='no' in input.env.

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)"

Deploy VM in OpenShift Virtualization

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: changeme

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='yes'
IMAGE_REGISTRY='localhost:5000'         
DOCKER_SERVER='https://index.docker.io/v2/'  
DOCKER_USERNAME='freeops'
DOCKER_PASSWORD='8Ua9d6uxBjQ!P@WK'
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=''             
THINGWORX_AGENT_MODEL=''               

The following table describes each field in the configuration file.

Table 30.

Field

Description

Mandatory configuration

CONNECTIVITY_TO_INTERNET

Whether the VM has internet access. Set to no for air-gapped/closed network environments.

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.

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.

Run these commands from the OVA VM to find the latest available Helm chart versions for CO_NORTH_HELM_VERSION (Helm chart version for the Container Observability backend component) and GLOBAL_VIEW_HELM_VERSION:

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

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.

Ensure that the values for CO_NORTH_HELM_VERSION and GLOBAL_VIEW_HELM_VERSION in the input.env file are updated to the latest versions available in the Virtana Helm repository.

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



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

Upgrade the Global View version

Ensure that the GLOBAL_VIEW_HELM_VERSION and CO_NORTH_HELM_VERSION (optional) values in the input.env file are updated to the latest versions available in the Virtana Helm repository.

Run the following commands to get the latest available version.

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

(Optional) This action is required if any of the following conditions apply:

  • The VM does not have internet connectivity.

  • A private container image registry is not available in your environment.

  • You prefer to deploy using a pre-packaged image bundle.

Perform the steps to use the image bundle:

  1. Obtain the image bundle file (virtana-global-view-<GV_VERSION>-images-bundle.tgz) from the Virtana Support team.

  2. Copy the bundle file to the Virtana OVA VM under the /opt/virtana directory.

  3. Do not extract the bundle manually.

    The deployment process will automatically extract and load the images.

The following table shows the respective commands to upgrade both Keycloak and Global View:

Table 32.

Actions

Command

Upgrade Keycloak and Global View together

bash /home/virtana/deploy.sh all

Upgrade Keycloak only

bash /home/virtana/deploy.sh keycloak

Upgrade Global View only

bash /home/virtana/deploy.sh globalview



Direct OVA-to-OVA upgrades are not supported. To move to a new OVA version, deploy a new VM from the latest OVA and back up and restore the data volumes from the previous OVA. The backup and restore flow is to be tested and validated.

Additional settings

The Additional Settings section provides supplementary configuration and operational guidance for managing the GV OVA deployment beyond the standard installation. You can refer to this section when performing post-deployment maintenance activities, such as including version upgrades, certificate rotation, and network troubleshooting, to ensure your Global View environment remains connected to the underlying infrastructure.

Upgrade the K3s Kubernetes version

Check the Current K3s Version and the node's health. To display the current Kubernetes version managed by K3s and the node's health, run the following commands in your terminal:

sudo k3s kubectl version
sudo k3s kubectl get nodes
sudo k3s kubectl get pods -n kube-system

Find the latest stable K3s version. To determine the latest stable K3s release available, run the following commands:

curl -s https://update.k3s.io/v1-release/channels | jq -r '.data[] | select(.id == "stable") | .latest'

Review the K3s release notes for version-specific considerations.

Take a Full VM Backup (Including Disk) in VMware

Important

Before any cluster upgrade, create a full backup of your VM, including all attached disks, using VMware vSphere or your preferred management tool.

In vSphere Web Client, right-click the VM > Snapshot > Take Snapshot. Enable Snapshot the virtual machine's memory and Quiesce guest file system for best protection.

Verify backup completion before proceeding.

Upgrade to the Target K3s Version. Replace <<K3s_VERSION>> below with the desired version string retrieved from Upgrade Strategy. The following command will upgrade K3s to that version with customized install options:

curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION="<<K3s_VERSION>>" INSTALL_K3S_EXEC="--flannel-backend=none --disable traefik --disable servicelb --write-kubeconfig-mode 644" sh -s -

Post-upgrade verification. To display the current Kubernetes version managed by K3s and the nodes' health, run:

sudo k3s kubectl version
sudo k3s kubectl get nodes
sudo k3s kubectl get pods -n kube-system

Manage K3s certificates

K3s relies on a set of TLS certificates to secure communication between the Kubernetes control plane, the kubelet, and cluster components. You can check the certificate validity, interpret expiration warnings, and manually rotate certificates when automatic renewal is not sufficient.

To check the expiration dates of your certificates, run the following command:

sudo k3s certificate check --output table

The following table provides the details that you must check for the relevant certificate:

Table 33.

Property

Details

Default validity

K3s server and client certificates are valid for 365 days (1 year) from their issuance date.

CA certificate validity

Typically valid for 10 years.

Alerts

Kubernetes event CertificateExpirationWarning when within 90 days of expiry.

Automatic renewal

K3s auto-renews expired certificates, or within 90 days of expiry, on every service restart.



You can manually rotate certificates using the K3s CLI with the following command:

sudo k3s certificate rotate
sudo systemctl restart k3s

KVM - VM Networking

KVM - VM Networking defines hosting of VMs on a KVM hypervisor to communicate with the underlying host, physical network, and external services. Understanding this networking model helps you correctly configure VM IP addresses, VLAN tagging, and DNS routing, as well as troubleshoot connectivity issues between the GV VM, its internal Kubernetes pods, and external services such as DNS, SMTP, or upstream APIs.

Host Linux bridge

The host Linux bridge acts as a software switch, connecting VM network interfaces directly to the host's physical NIC. This allows VMs to appear as first-class nodes on the physical network, enabling full Layer 2 connectivity without NAT.

The following diagram illustrates the traversal of network packets through the host’s physical NIC, VLAN interfaces, and bridges before reaching the VM, and how traffic originating from the VM flows back to the external network.

ASCII_view.png
Packet flow
  • Inside the VM, a packet leaves eth0 and hits the host's vnetX via a tap/virtual link.

  • vnetX is a port on Bridge-60 that forwards traffic into the bridge.

  • Bridge-60 routes external traffic out via its uplink enp7s0.60 (VLAN 60 sub-interface).

  • enp7s0.60 tags/untags VLAN 60 on the way to the physical NIC enp7s0, which puts bits on the wire.

DNS traffic flow

Understanding the DNS traffic path is important for troubleshooting name resolution issues, validating network connectivity, and ensuring that both the VM and its workloads (running on K3s) can reliably reach upstream DNS services through the configured bridge network.

VM-level DNS resolution path

Even though the VM subnet is 10.10.60.0/23, DNS servers at 10.10.2.6/7 are reachable through normal routing:

GV VM (10.10.60.101) -> vnet12 (tap) -> Bridge-60 -> enp7s0.60 -> physical switch/router -> DNS (10.10.2.6/7)
Return: 10.10.2.6 -> router -> VLAN 60 -> enp7s0.60 -> Bridge-60 -> vnet12 -> VM

So VM and host are both just regular nodes on 10.10.60.0/23 that can reach DNS at 10.10.2.6/7 through routing.

Pod-level DNS resolution path

Inside the GV VM running K3s (pod CIDR: 10.43.0.0/16, CoreDNS service: 10.43.0.10):

Pod (10.43.A.B) -> kube-proxy/iptables -> CoreDNS service (10.43.0.10) -> CoreDNS pod
-> GV VM kernel routing -> vnet12 -> Bridge-60 -> enp7s0.60 -> physical switch/router -> External DNS
Return: External DNS -> router -> VLAN 60 -> enp7s0.60 -> Bridge-60 -> vnet12 -> GV VM -> CoreDNS pod -> kube-proxy -> Pod

GV VM's first-class L2 connectivity via Bridge-60 ensures pod DNS requests reach the upstream network without additional NAT.

Libvirt default network (virbr0)

virbr0 uses NAT, so external systems cannot directly reach VMs unless port forwarding is configured. Use the host Linux bridge for production-like setups where VMs need routable IPs.

Table 34.

Property

Details

Type

libvirt-managed interface network.

Purpose

Isolated virtual network with built-in DHCP, DNS, and NAT.

Default IP range

192.168.122.0/24

External access

VM traffic is NATed through the host; external systems cannot directly reach VMs.

Best for

Testing, development, or temporary VMs only.



VM -> vnet -> virbr0 (DHCP + NAT) -> Host NIC -> Switch -> Internet

Unlike a host-managed bridge, virbr0 does not integrate VMs as full participants in the physical network. Instead, it keeps them in an isolated network environment.

This setup is useful for testing and development scenarios. However, it is not ideal for production environments, where VMs need routable IP addresses and full network visibility.

GV OVA Support and Operating Model

This section outlines the security baseline applied at image build time, the supported upgrade and patching strategies, and the operational responsibilities shared between you and Virtana. You can refer to this section to understand the boundaries of supported operations.

Security Baseline

GV OVA is delivered as a hardened, appliance-style VM with clearly defined ownership and support boundaries.

Operating system hardening

Built on Ubuntu Server 22.04 LTS with CIS benchmark hardening applied during image build. The following security assessment reports are available on request:

CIS Compliance

CIS (Center for Internet Security) Compliance ensures that the GV OVA's operating system is configured according to globally recognized security best practices. The compliance reports are available on request from Virtana Support, which you can use to satisfy your organization's audit or security review.

  • OSCAP (OpenSCAP) CIS compliance report

  • CIS benchmark alignment verified

  • Hardening applied at image build time

Vulnerability Assessment

Vulnerability Assessment verifies that the GV OVA is free from known security risks before being delivered to customers. You receive a pre-validated, security-reviewed appliance without needing to run your own vulnerability scans before deployment.

  • Lynis OS hardening assessment report

  • Nessus vulnerability scan report

  • Critical or High findings resolved before release

Access model

The Access Model defines your interaction with the GV OVA and clarifies the boundaries of supported operations.

  • SSH access is available only for bootstrapping and troubleshooting.

  • You are not expected to perform OS or Kubernetes modifications.

  • Privileged access is intended for Virtana-supported operations: troubleshooting, patching, and recovery.

  • Unauthorized changes can cause configuration drift and are outside our supported operating model.

Kubernetes security (K3s)

The GV OVA includes a K3s cluster fully managed by Virtana. You are not required to perform Kubernetes hardening or lifecycle operations.

The table below outlines the key properties and security features of the K3s Kubernetes distribution bundled with the GV OVA:

Table 35.

Property

Details

Certification

CNCF-certified Kubernetes distribution (originally by Rancher).

Production-ready

Designed for production in constrained environments.

Secure by default

Sensible security defaults appropriate for most use cases.

Certificate management

Automated certificate distribution and control plane setup that reduces misconfiguration risk.

CIS controls

Many CIS controls are met by default. Advanced hardening options exist, but are not required for this appliance model.



Upgrade and patch strategy

Virtana follows a structured approach that combines Helm-based application upgrades with coordinated vulnerability remediation, ensuring that you can keep your Global View deployment current and secure with minimal operational effort.

Application upgrade (Helm-based)

Application upgrades for the GV OVA are delivered through Helm, the standard package manager for Kubernetes, which simplifies version management and rollback.

  • The OVA is deployed once, for example, 2025.12.1.

  • For a new release, for example, 2026.1.1, an upgrade bundle is uploaded to Egnyte.

  • Customers can upgrade via SSH/SFTP (air-gapped) and run the deploy script, or perform a direct Helm upgrade if the internet is available.

Vulnerability remediation

You can identify and resolve across the GV OVA's lifecycle, both before and after deployment.

Table 36.

Phase

Actions

Pre-release

  • CIS hardening via Lynis and OSCAP,

  • Nessus scan,

  • Critical and High vulnerabilities fixed or documented.

Post-deployment

Vulnerabilities are addressed by coordinated patching or by remote access if RemoteWisdom is installed and enabled.



Operational responsibility matrix

The table below defines responsibilities between you and Virtana after deploying the GV OVA. Since the OVA is deployed in your environment, you may need to execute certain tasks. Virtana provides guidance, scripts, and support.

Table 37.

Area

Customer

Virtana

OVA deployment (import)

Tick_sym.png

Hypervisor/infrastructure

Tick_sym.png

VM power operations

Tick_sym.png

Initial configuration (input.env and install script)

Tick_sym.png

Guidance/support only

Application upgrades (communication and execution)

Tick_sym.png

Guidance/support only

OS hardening

Tick_sym.png

OS patching

Tick_sym.png

Kubernetes (k3s) lifecycle

Tick_sym.png

Backup configuration and execution

Tick_sym.png

Guidance/support only

Restore procedures

Tick_sym.png

Guidance/support only

Security vulnerability remediation

Tick_sym.png



Summary of responsibilities

This section outlines the shared operating model between the customer and Virtana, clearly defining who owns which tasks across the GV OVA lifecycle.

Customer responsibilities

These are the tasks that you, as the customer, are expected to perform.

  • Perform initial environment-specific configuration and run installation scripts.

  • Apply application upgrades and Helm chart updates as communicated by Virtana.

  • Configure and execute backups, and perform restores when necessary.

Virtana responsibilities

These are the tasks that Virtana owns and manages on your behalf.

  • Harden and patch the OS.

  • Manage the K3s lifecycle.

  • Maintain the application lifecycle (versioned Helm charts).

  • Provide guidance, scripts, and documentation for customer-executed tasks.

  • Remediate security vulnerabilities in the OS, Kubernetes, and application stack.

Shared responsibilities

These are tasks where both you and Virtana collaborate.

  • Backup configuration and restore processes are executed by the customer but supported by Virtana guidance.

  • Collaboration is expected for critical operations like recovery and troubleshooting.

Roadmap items

The following enhancements are planned and do not impact the current support model:

  • Signed OVA to verify authenticity and integrity.

  • Backup and restore to a new OVA appliance.

Support statement

GV OVA is supported as a managed, hardened virtual appliance. Operations outside the documented and supported workflows may impact supportability. For questions related to security posture, upgrades, or operations, contact Virtana Support.

Global View OVA upgrade

This topic describes how to upgrade a Global View OVA (virtual appliance) deployment to version 2026.6.1. Upgrades run in place on the existing virtual machine: you update the deployment script and configuration, then redeploy the Global View application components with Helm.

OVA upgrade guidelines

Review the following guidelines before you upgrade a Global View OVA:

  • OVA-to-OVA upgrades are not supported: After you deploy the OVA as a virtual machine, perform all later Global View upgrades with the standard application upgrade process. Deploying a new OVA version over an existing VM is not supported.

  • Upgrades run in place on the existing VM: Once the Global View VM is deployed and running, you run all future upgrades on the same VM by upgrading the application components with Helm.

  • Review the version-specific upgrade notes first: Starting with Global View 2026.6.1, version-specific upgrade instructions are published for each release. Read the notes that match the version you are upgrading from.

  • Update the Helm values as required: Before you upgrade, review the applicable upgrade notes and make any required changes to the Helm values files in /home/virtana/templates/ , in particular templates/global-view-values.yaml . For the values changes specific to your source version, see the Global View upgrade (2026.6.1).

  • Run the standard deployment script: After you apply the configuration changes, run bash deploy.sh <deployment-type> to perform the upgrade.

Update deploy.sh before you upgrade to 2026.6.1

The deploy.sh script included in Global View OVA versions earlier than 2026.6.1 does not include the configuration changes introduced in Global View 2026.6.1. As a result, upgrades from earlier OVA versions to 2026.6.1 do not correctly update the image registry configuration and the Helm deployment options required for the following components:

  • Redis : The image repository name changes from redis to dhi-redis .

  • SeaweedFS : This component is new in 6.1 and requires image registry configuration.

  • VirtanaAI (Copilot) : The configuration keys move from the LiteLLM paths to the VirtanaAI paths.

  • CRD installation : The CRD deployment step must use the patched values file.

Before you run deploy.sh during the upgrade, apply the following updates to the existing script.

  1. Update the Redis image repository:

     sed -i \ 's|\.redis\.image\.repository = strenv(IMAGE_REGISTRY) + "/redis"|.redis.image.repository = strenv(IMAGE_REGISTRY) + "/dhi-redis"|g' \ deploy.sh 
    
  2. Add the SeaweedFS image registry configuration:

     sed -i '/dhi-redis/a\ yq e -i '\''.seaweedfs.image.registry = strenv(IMAGE_REGISTRY)'\'' "$PATCHED_GLOBALVIEW_VALUES" ' deploy.sh 
    
  3. Update the VirtanaAI configuration keys:

     sed -i \ -e 's/\.cp-configs\.litellm\.litellm_api_key/.cp-configs.virtana_ai.virtana_ai_api_key/g' \ -e 's/\.cp-configs\.litellm\.litellm_inference_endpoint/.cp-configs.virtana_ai.virtana_ai_inference_endpoint/g' \ deploy.sh 
    
  4. Update the CRD deployment command so that CRD installation uses the patched values file:

     sed -i '/tags\.crds=true/ { /PATCHED_GLOBALVIEW_VALUES/! s|--set tags\.crds=true \\|--set tags.crds=true -f "$PATCHED_GLOBALVIEW_VALUES" \\| }' deploy.sh 
    

Update the Global View version in input file

Update the Helm version variables and the VirtanaAI (Copilot) configuration in the input.env file before you run the upgrade.

Update the versions

Update GLOBAL_VIEW_HELM_VERSION and, optionally, CO_NORTH_HELM_VERSION in the input.env file to the latest versions available in the Virtana Helm repository. Run the following commands to find the latest available versions:

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

Update the VirtanAI (Copilot) configuration

The OPENAI_API_KEY variable is replaced with a provider-based configuration model that supports OpenAI, Gemini, and LiteLLM. Update the VirtanaAI section of input.env as follows:

# Supported values: 
# OPENAI / GEMINI / LITELLM VIRTANA_AI_MODEL_PROVIDER='' 
# API key for OPENAI, GEMINI, or LITELLM VIRTANA_AI_API_KEY='' 
# Leave blank when using OPENAI or GEMINI. 
# For self-hosted LiteLLM deployments, 
# provide the LiteLLM endpoint URL. 
# Example: https://litellm.example.com VIRTANA_AI_INFERENCE_ENDPOINT='' 

Variable

Description

Default value

VIRTANA_AI_MODEL_PROVIDER

AI provider for the VirtanaAI Copilot. Supported values: OPENAI , GEMINI , LITELLM .

VIRTANA_AI_API_KEY

API key for the selected provider (OpenAI, Gemini, or LiteLLM).

VIRTANA_AI_INFERENCE_ENDPOINT

Inference endpoint URL. Leave blank for OpenAI or Gemini. For a self-hosted LiteLLM deployment, provide the LiteLLM endpoint URL (for example, https://litellm.example.com ).

Download the image bundle (optional)

This step is required if any of the following conditions apply:

  • The VM does not have internet connectivity.

  • A private container image registry is not available in your environment.

  • You prefer to deploy using a pre-packaged image bundle.

To use the image bundle:

  • Obtain the release-specific image bundle file ( virtana-global-view-<GV_VERSION>-images-bundle.tgz ) from the Virtana Support team.

  • Copy the bundle file to the Virtana OVA VM in the /opt/virtana directory.

  • Do not extract the bundle manually. The deployment process extracts and loads the images automatically.

Customize or update the Helm values

You can customize the deployment by editing the Helm values template files before you upgrade. The template files are in /home/virtana/templates/ :

 ls -l /home/virtana/templates/ 

Update the appropriate values file to override the default configuration, such as resource requests and limits, storage settings, ingress configuration, node scheduling preferences, or application-specific parameters.

Note

Review the version-specific upgrade notes before you modify existing values files or upgrade, because configuration options and defaults can change between releases.

Run the upgrade

After you patch deploy.sh , update input.env , and adjust the Helm values, run the deployment script to upgrade Keycloak and Global View. To upgrade only Global View, upgrade Keycloak first, then Global View.

Action

Command

Upgrade Keycloak and Global View together

bash /home/virtana/deploy.sh all

Upgrade Keycloak only (step 1 of 2)

bash /home/virtana/deploy.sh keycloak

Upgrade Global View only (step 2 of 2)

bash /home/virtana/deploy.sh globalview