Skip to main content
Version: NG 3.0 (Beta)

Deployment and Installation using vuLauncher

Introduction​

vuLauncher is a standalone application designed to facilitate the deployment of vuSmartMaps™. The application operates via a command-line interface (CLI) and supports installation in two distinct environments:

  1. Virtual Machines: vuSmartMaps can be installed on virtual machines running any of the supported operating systems. The vuLauncher installs the base Kubernetes platform using the kubeadm provider, followed by the deployment of the vuSmartMaps application.
  2. Managed Kubernetes: vuSmartMaps can also be deployed on managed Kubernetes infrastructures, such as Amazon EKS, Azure AKS, Google GKE, OpenShift, and more.

Deployment Specification (D-spec)​

The d-spec is unique to each environment and client installation. It provides control over resource limits for services, service grouping across nodes, and additional configurations.

D-Specs can be generated from the D-Spec utility of the vuSizer tool available here.

Downloading the binary​

  1. Create a folder in the home directory and download the NG installation binary using the below command
- wget https://download.vunetsystems.com/_Downloads_/_vuDocker_/3.0/vuSmartMaps_offline_NG-3.0.tar.gz  - - user=<username> - - password=<password>  - - no-check-certificate
note

If you don’t have access to the download server, download the binaries directly from this URL.

  • Please check with the VuNet support team to get the credentials for the Download server and the d-spec.
  • d-spec is unique for an environment, update the d-spec details according to the deployment environment.
note

Refer to this link if you want to download the online binary, in the case of deployments other than VM-based ones.

  1. Extract the downloaded NG installation binary using the command below
    - tar \-xvzf vuSmartMaps\_offline\_NG-3.0.tar.gz

Starting vuLauncher​

  • To start the vuLauncher, execute the following command
    • username="username of the VM" private_key_path="path to private key" ./build/launcher_linux_x86 --sizing <path to d-spec yaml> --ignore-preflight
  • To get all the possible arguments that can be passed to the launcher binary can be found via
    • “./build/launcher_linux_x86 - - help”
note
  • --sizing if required field, so when we run the launcher with any flags, sizing is a must.
  • If installation has stopped at any point, we can restart using the same command that we used to start
Oops! Installation stopped unexpectedly? Don’t worry—just check the logs for details, resolve the issue, and re-run the launcher command to pick up where you left off.

CLI Arguments​

Below are major cli arguments :

  • - - debug :
    This is to run the launcher in debug mode, which provides some extra debug logs
  • - - view :
    This will print out all the installation stages and service status onto the console. This will accept either installation or services.

  • - - dry-run :
    This will not start the installation routine, but is used to verify if the given dspec file is valid or not

  • - - start :
    This will accept the stage name, and the launcher will start the given stage. This will only start the given stage, and once completed, it will not proceed further.
  • - - remove-master :
    This will reinstall kubernetes in the master node
  • - - remove-worker - -nodes <worker node IP’s> :
    This will reinstall kubernetes cluster on all the given worker nodes
  • - - start-from :
    This will accept the stage name and start from it. Unlike start, this will not stop once a given stage is completed, this will keep going until all the subsequent stages are completed. In order to get a list of all the stage names, run the launcher with --view installation

  • - - version :
    Every launcher will be released with the ng version tag. We can see what version of NG is being deployed using the version flag

  • - - ignore-preflight :
    Every time when we start the vuLauncher, it will run the preflight scripts, which are used to validate the VM's readiness. If we wish to ignore this check, then we can use this flag
  • - - remove-service - - services <release names in comma separated> :
    This will remove the given installed services. If the user wants to remove all the services, then provide only - - remove-service flag.

Launcher Workflow​

When we start the launcher, we will validate all the configuration files (launcher config, d-spec). The entire workflow of the launcher is divided into the following stages :

Copying Kubernetes Package​

  • This stage copies the kubernetes.tar.gz to all the available nodes in the d-spec.
  • This tar file contains all the Kubernetes-related binaries, kubeadm scripts, and docker images.
  • This will be copied to the data tier that we specified in the d-spec. The preference of data tier is vusmart > default > hot > warm > cold > default-replica.

Extract Kubernetes Package​

  • This extracts the kubernetes.tar.gz on all the nodes.
  • Here launcher executes the bash command tar -xzf kubernetes.tar.gz over an ssh connection
  • This stage creates the soft link for containerd and kubelet.
  • The launcher will choose the mount point-based preference: vusmart > default > hot > warm > cold > default-replica.
  • Assuming the mount point chosen is /data, then:
    • /var/lib/containerd -> /data/vunet/containerd
    • /var/lib/kubelet -> /data/vunet/kubelet
    note

    If /var/lib/containerd already exists with some data, then this stage will fail. So please ensure that /var/lib/containerd and /var/lib/kubelet are not present.

Master Node Setup​

    • This stage installs Kubernetes services in the master node. The master node will be identified in the d-spec, marked with is_master: true.

Worker Node Setup​

  • This stage will install Kubernetes in all the worker nodes. This installation will happen in parallel.
  • If any of the worker nodes fails to get installed then, we will mark this as failure.

Kubernetes Validation​

  • Once the Kubernetes cluster is successfully installed, we will validate it again to see all the services are running correctly

Kubernetes Pre-Setup​

  • This stage contains the pre-installation tasks required before installing the actual helm charts. These tasks include:
    • Creating node-labels and taints
    • Creating a secret to pull docker images
    • Executes preK8sManifest

Helm Chart Updates​

  • This stage will update all the helm-charts with the contents in the d-spec.

Service Installation​

  • This stage will install all the helm-charts for the services listed in the d-spec.
  • Each helm-chart will have its dependent helm-charts specified in the values.yaml file, so the launcher will identify the correct order to install helm-chart.
  • If any service helm-chart fails to get installed with an error, then all its parent helm-charts will be skipped.
  • There are two cases that we need to be aware of
    • If the launcher fails at some services and you want to continue from the failed chart onwards, do not specify the –sizing argument when running the command again. This ensures the existing state is not overwritten and installation will resume from the previous failed helm chart.
    • If you want to start services installation from fresh, then you need to manually remove all the helm-charts and then start the launcher with the sizingconfig argument.

Template Upload​

  • This stage handles uploading all the agent binaries, vublock, vustream templates, and other static-files to MinIO UI.
  • This is the last stage of the installation.

Key Points​

  • If the launcher fails at any step, please check the logs; it should display enough information to debug further, and once the issue is fixed, you can re-run the command to start again.

FAQs​

What happens if my vuLauncher installation fails midway? Can I resume, or do I need to start over?

If the installation fails at any stage, vuLauncher allows you to resume from where it stopped. Use the same command without the --sizing argument to avoid overwriting the previous state.

Refer to: Service Installation and CLI Arguments > --start-from

How can I validate if my d-spec file is correctly configured before initiating a full installation?

You can run vuLauncher in dry-run mode using the --dry-run flag. This checks the validity of the d-spec file and highlights issues before actual deployment begins.

Refer to: CLI Arguments > --dry-run

Is it mandatory to expose all listed ports if my setup is on a single-node deployment?

No, for single-node deployments, the required ports must be open internally on the same node, not across multiple nodes.

How does vuLauncher decide where to create containerd and kubelet directories during VM installation?

vuLauncher uses a preference order for mount points to place containerd and kubelet data. If directories like /var/lib/containerd already exist, this stage fails.

Refer to: Launcher Workflow > Create Soft Link

Can I install vuSmartMaps on VMs that already have Kubernetes or Docker installed?

No, the documentation explicitly recommends using fresh VMs. Existing Kubernetes or Docker installations may conflict with vuLauncher’s process.

What should I do if my organization has strict internet access policies? Will vuLauncher still work?

Yes, but in such cases, VuNet support will help install missing Linux dependencies and may ship required images instead of pulling them online.

How does vuLauncher manage service-to-VM mapping for optimized deployment?

The tags in the d-spec file group VMs, allowing services to be mapped to optimized node groups using resource-driven logic during deployment.

Refer to: Deployment Specification (D-spec) > category and tags sections

What are the critical services that need external access, and what are their corresponding port requirements?

Key external communications include downloading installation packages, accessing the GitHub Container Registry, and telemetry data ingestion. Ports like 443, 9092, 4317, 161, etc., must be opened accordingly.

How do I decide whether to set env_name to “vm” or “cloud” in the d-spec file?

Set env_name: "vm" if you're installing on VMs without an existing Kubernetes setup. Use env_name: "cloud" if deploying on an existing managed Kubernetes cluster (e.g., AKS, EKS, GKE).

Refer to: Deployment Specification > env_name parameter

If one of the worker nodes fails during Kubernetes setup, will the whole installation stop?

Yes. vuLauncher will mark the installation as failed if even one worker node setup fails. You'll need to resolve the issue and restart from the worker node setup stage.

Refer to: Launcher Workflow > Worker Node Setup