Virtual Machine / Cloud Installation
This page covers only the differences when installing the gateway on a VM (VMware / Hyper-V / KVM / Proxmox) or a public cloud (AWS EC2 / Azure VM / GCP) instead of physical H/W. For the standard procedure for a new installation, see Quick Install (2026.05+ container). Refer to Full H/W Setup only for maintaining legacy native boxes.
The 2026.05+ container mode works as-is inside a VM — Docker is based on cgroups/namespaces
rather than nested virtualization, so performance on a VM matches native. If the cgroup
MemoryMax=12G exceeds the VM's memory limit, adjust it (e.g. MemoryMax=6G via a systemd drop-in).
1. Specification Requirements
| Tier | vCPU | RAM | Disk | Notes |
|---|---|---|---|---|
| Small (≤ 1k tags) | 4 vCPU | 8 GB | 100 GB SSD | Development/test |
| Medium (1k–10k tags) | 8 vCPU | 16 GB | 256 GB SSD + 1 TB | Standard for production |
| Large (10k+ tags) | 16 vCPU | 32 GB | 512 GB NVMe + 2 TB | Large scale |
Beware of CPU overcommit — if the host overcommits CPU beyond 1:4, Cassandra commitlog flushes are delayed and surface as alarms. Dedicated CPU is recommended.
2. Disk Layout — Recommended
Separating /opt and /data1 onto separate disks (or separate LVM volumes) gives you:
- Preservation of
/data1/pp-data(user flows / Cassandra / backups) even when/opt/kopensis replaced during an upgrade - Isolation of disk IO load (Cassandra commitlog vs sstable)
/dev/sda → / (OS) ~ 50 GB
/dev/sdb → /opt ~ 100 GB SSD (게이트웨이 코드)
/dev/sdc → /data1 ~ 1 TB+ (시계열 데이터)
3. VMware vSphere
| Recommended |
|---|
| Virtual H/W version ≥ 14 (ESXi 6.7+) |
| VMXNET3 NIC (faster than Intel E1000) |
| paravirtual SCSI (higher throughput than LSI Logic) |
| Enable CPU reservation (Cassandra stability) |
| Enable memory reservation — full sized (ballooning disabled) |
Add tools.guestlib.enableHostInfo = TRUE — host time synchronization |
4. KVM / Proxmox
| Recommended |
|---|
cpu host mode (passthrough) |
virtio NIC + virtio-blk / virtio-scsi |
Install qemu-guest-agent (guest health check) |
| Disable memory ballooning (Cassandra heap stability) |
Disk cache mode = none (lower latency) or writeback (higher throughput) |
5. Hyper-V
| Recommended |
|---|
| Generation 2 (UEFI) |
| Disable Dynamic Memory (variable Cassandra heap → swapping) |
| Latest Integration Services (time synchronization) |
Virtual NIC Adapter Type = Synthetic (not Legacy) |
6. Public Cloud
6.1 AWS EC2
| Item | Recommended |
|---|---|
| Instance | m5.xlarge (4 vCPU / 16 GB) — small/medium / m5.2xlarge (8/32) — production |
| AMI | Amazon Linux 2 (Fedora 38 is preferred, but RHEL-family is compatible) |
| Disk | gp3 (/opt 100 GB), gp3 (/data1 1 TB+) — io1/io2 for the Cassandra commitlog |
| Security Group | inbound 80 / 443 / 22 (admin IPs only), MQTT 1883 / OPC-UA 12000 (if needed — usually inside the VPC) |
| EFA / enhanced networking | enabled (lower latency) |
| Placement | Cluster placement group (large scale) |
Connect to the on-premise PLC network via AWS PrivateLink / VPC Peering.
6.2 Azure VM
| Item | Recommended |
|---|---|
| Size | D4s_v5 (4 vCPU / 16 GB) — small/medium / D8s_v5 — production |
| Disk | Premium SSD (P30 / P40) for /data1 |
| Accelerated Networking | enabled |
| ExpressRoute / VPN | connection to on-premise PLCs |
6.3 GCP
| Item | Recommended |
|---|---|
| Machine type | e2-standard-4 — small/medium / n2-standard-8 — production |
| Disk | pd-ssd (guarantees 1k IOPS for the Cassandra commitlog) |
| Cloud Interconnect / VPN | on-premise connection |
7. Cloud-to-On-Premise PLC Network Connection
PLCs are usually on-premise (inside the plant), so a gateway running in the cloud cannot communicate with them directly. Two patterns:
Pattern A — Cloud gateway + on-premise gateway
[PLC] ─── [온프레 게이트웨이] ─── (Sparkplug B / MQTT) ─── [클라우드 게이트웨이] ─── [상위 플랫폼]
The on-premise gateway handles PLC collection and Sparkplug publishing; the cloud gateway receives and consolidates. This is the recommended pattern.
Pattern B — Reach the PLC network directly over VPN / SD-WAN
[PLC] ─── [VPN 게이트웨이] ──VPN── [클라우드 게이트웨이] ─── [상위 플랫폼]
Higher latency plus line costs. Recommended only for one or two small sites.
8. Boot Automation (cloud-init)
Automatic installation when the instance boots on a VM / cloud — cloud-init user-data example:
#cloud-config
package_update: true
write_files:
- path: /root/pp-edge-install.env
owner: root:root
permissions: '0600'
content: |
export EDGE_ID=EDGE_VM_001
export SITE_ID=SITE_00001
export SERVER_HOST=192.168.0.41
export SERVER_API_KEY=<platform-api-key>
runcmd:
- mkdir -p /data1 /opt/kopens
- . /root/pp-edge-install.env && bash < <(curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh)
- bash /opt/kopens/install/bin/health.sh
In production, specify a fixed edge.id and fixed site.id explicitly in cloud-init.
9. Common Pitfalls (VM / Cloud Specific)
| Symptom | Cause / Resolution |
|---|---|
| Cassandra dies frequently | Memory ballooning enabled. Switch to fixed memory |
| Frequent MQTT keepalive timeouts | Cloud NAT idle timeout is short. Change keepalive in app.properties from 60 → 30 seconds |
| Time shows 1970 after boot | Virtual time synchronization disabled. Install VMware tools / qemu-guest-agent |
| Slow disk IO | gp2 / standard HDD. Move to gp3 or SSD |
| OPC-UA certificate invalid every time | Virtual hostname changes (DHCP). Include all possible IPs/hostnames in the certificate SAN |
| Insufficient network throughput | virtio / VMXNET3 / Accelerated Networking not enabled |
10. Learn More
- Standard installation: Quick Install
- Production acceptance criteria: Production Readiness
- legacy native: (legacy) Full H/W Setup
- Air-gapped network: Offline / Air-Gapped Installation
- Network topology: Network Configuration (NIC Layout)
- Post-installation checklist: Post-Install Checklist