mnl/VM-Operator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 4 Wiki Activity Actions

Add documentation.

Browse source
This commit is contained in:
Michael Lipp 2025-03-05 23:24:03 +01:00
parent 5ae162445c
commit 7dc68b5ac7
6 changed files with 179 additions and 57 deletions
Download patch file Download diff file Expand all files Collapse all files

145
webpages/pools.md
View file

@ -7,67 +7,100 @@ layout: vm-operator
*Since 4.0.0*
## Prepare the VM
Not all VMs are replacements for carefully maintained individual PCs.
In many workplaces, a standard configuration can be used where
user-specific data is kept in each user's home directory on a shared
file system. In such cases, an alternative to providing individual
PCs is to offer a pool of VMs and allocate them from the pool to users
as needed.
## Pool definitions
The VM-operator supports this use case with a CRD for pools.
```yaml
apiVersion: "vmoperator.jdrupes.org/v1"
kind: VmPool
metadata:
namespace: vmop-dev
name: test-vms
spec:
retention: "PT4h"
loginOnAssignment: true
permissions:
- user: admin
may:
- accessConsole
- start
- role: user
may:
- accessConsole
- start
```
The `retention` specifies how long the assignment of a VM from the pool to
a user is retained after the user closes the console. This allows a user
to interrupt his work for this period of time without risking that
another user takes over the VM. The time is specified as
[ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations).
Setting `loginOnAssignment` to `true` triggers automatic login of the
user (as described in [section auto login](auto-login.html)) when
the VM is assigned. The `permissions` property defines what a user can
do with a VM assigned to him.
VMs become members of one (or more) pools by adding the pool name to
property `spec.pools` (an array of strings), e.g.:
```yaml
apiVersion: "vmoperator.jdrupes.org/v1"
kind: VirtualMachine
spec:
pools:
- test-vms
```
## Accessing a VM from the pool
Users can access a VM from a pool using the widget described in
[user view](user-gui.html). The widget must be configured to
provide access to a pool instead of to a specific VM.
![VM Access configuration](ConfigAccess-preview.png){: width="500"}
Assignment happens when the "start" icon is pushed. If the assigned VM
is not running, it will also be started. The assigned VM's name is
shown in the widget above the action icons.
![VM Access via pool](PoolAccess-preview.png)
Apart from showing the assigned VM, the widget behaves in the same way
as it does when configured to access a specific VM.
## Requirements on the guest
Some provisions must be made on the guest to ensure that VMs from
pools work as expected.
### Shared file system
Mount a shared file system as home file system on all VMs in the pool.
If you want to use the sample script for logging in a user, the filesystem
must support POSIX file access control lists (ACLs).
When using the
[sample agent](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent),
the filesystem must support POSIX file access control lists (ACLs).
### Restrict access
### User management
The VMs should only be accessible via a desktop started by the VM-Operator.
All VMs in the pool must map a given user name to the same user
id. This is typically accomplished by using a central user management,
such as LDAP. The drawback of such a solution is that it is rather
complicated to configure.
* Disable the display manager.
As an alternative, the sample auto login agent provides a very simple
approach that uses the shared home directory for managing the user ids.
Simplified, the script searches for a home directory with the given user
name and derives the user id from it. It then checks if the user id is
known by the guest operating system. If not, the user is added.
```console
# systemctl disable gdm
# systemctl stop gdm
```
* Disable `getty` on tty1.
```console
# systemctl mask getty@tty1
# systemctl stop getty@tty1
```
You can, of course, disable `getty` completely. If you do this, make sure
that you can still access your master VM through `ssh`, else you have
locked yourself out.
Strictly speaking, it is not necessary to disable these services, because
the sample script includes a `Conflicts=` directive in the systemd service
that starts the desktop for the user. However, this is mainly intended for
development purposes and not for production.
The following should actually be configured for any VM.
* Prevent suspend/hibernate, because it will lock the VM.
```console
# systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
```
### Install the VM-Operator agent
The VM-Operator agent runs as a systemd service. Sample configuration
files can be found
[here](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent).
Copy
* `99-vmop-agent.rules` to `/usr/local/lib/udev/rules.d/99-vmop-agent.rules`,
* `vmop-agent` to `/usr/local/libexec/vmop-agent` and
* `vmop-agent.service` to `/usr/local/lib/systemd/system/vmop-agent.service`.
Note that some of the target directories do not exist by default and have to
be created first. Don't forget to run `restorecon` on systems with SELinux.
Enable everything:
```console
# udevadm control --reload-rules
# systemctl enable vmop-agent
# udevadm trigger
```
Details can be found in the comments of the sample script.