How sativarsainath-26/runq works
Main Components Identification
• Host-side Components:
• Docker CLI, Docker daemon, and docker-containerd-shim that trigger containers.
• runq “proxy” (cmd/proxy) that is the entry point in the container. This component starts Qemu, configures network ports, mounts storage, and manages signals. Display it as the bridge between Docker and the VM guest.
• runq-exec (cmd/runq-exec) used for executing commands in running containers.
• nsenter (cmd/nsenter) for entering namespaces.
• External dependencies such as TLS certificates, the vhost_vsock module, and device configurations.
• Qemu binary and related configuration files in the “qemu” and “initrd” directories. These are set up under /var/lib/runq/qemu.
• VM Guest Components:
• The runq “init” process (cmd/init) that is the first process (PID 1) in the VM guest.
• The guest kernel booted by Qemu.
• The actual application container that runs inside the VM guest.
• Devices and storage components (devices such as block, virtio-blk, 9pfs-mounted filesystems, and network interfaces) that are attached inside the VM.
• Supporting and Shared Libraries:
• Utility packages and core packages (internal/ and pkg/vm) that provide configuration, loopback, kernel modules, etc.
• Build scripts and Makefiles spread across the project that streamline the development and integration.
Relationships and Interactions
• Docker client invoking the Docker daemon that passes the container specification to the runq runtime.
• From the Docker daemon, illustrate two execution paths:
a) Traditional runc container (for coexistence) and
b) The runq container where the proxy initiates a VM “guest”.
• Within the VM guest, illustrate how the “init” process sets up networking (creating namespaces, mounting disks, etc.) and finally launches the application. Show how runq-exec later interacts with the running guest via Vsock and TLS.
• Role of Qemu in providing the virtual hardware (network, disk, and CPU emulation) and show that the Qemu binaries and container kernel images come from the “qemu” directory. Also note that the “initrd” prepares the boot image.
• Relationships for storage management (volumes, rootdisk, and devices) and network configuration (macvtap, virtio, and even possibility for macvlan).
Architectural Patterns and Design Principles
• Separation between host and guest execution environments.
• That runq adheres to a minimalistic design where it integrates with Docker without modifying existing Docker tools.
• How multiple commands and configuration files (like TLS setup and seccomp profiles) contribute to security and isolation.
Relevant Technologies and Frameworks
• Docker integration (runc, containerd, Docker API).
• Linux KVM, Qemu, and virtio components.
• TLS security for runq-exec client authentication.
• Network bridging through macvtap and DNS proxying when needed.
• The use of bind mounts for loader modules into the VM.
• Libseccomp usage for sandboxing.
Instructing the Principal Software Engineer
[Docker CLI] → [Docker daemon/containerd shim] → [runq proxy (cmd/proxy)]
│
▼
[Qemu (with custom configurations)]
│
▼
[VM Guest: runq init (cmd/init) → Application]
Additionally, show the side processes:
• nsenter (for namespace entry)
• Qemu’s use of separate volumes and configuration directories.
• Clear labels for each component.
• Adding annotations that reference specific assembly points based on directory names (for instance, the qemu, initrd, internal, and pkg directories) to underline where the components originate.
• Every component’s purpose—for instance, that the “proxy” is effectively an enhanced Docker entry point that triggers Qemu, and “init” is the VM’s startup process.
• Host components vs. guest components.
• Core runtime binaries (cmd/* components) vs. supporting libraries (internal/* and pkg/*).
• External integrations (Docker, TLS, network interfaces, storage attachments).