Projects/pulumi-kvm/README.md

# Instructions for creating projects using these templates
***Note: This assumes SSH access to KVM hosts and Pulumi is [installed](https://www.pulumi.com/docs/install/).***

## Login to the backend
Log in to your [pulumi backend](https://www.pulumi.com/docs/iac/concepts/state-and-backends/), in this example a file-based local backend will be used. This will create a state file in your home directory (~/ on Linux, for example)

`pulumi login --local`

## Copying and modifying the template
Create a new directory with the name of the project. Copy the templates from the `stack_templates` and `python_templates` directories for the specific node type.

Example:
```
mkdir app-cluster
cp stack_templates/cluster_static_pulumi app-cluster/Pulumi.app-cluster.yaml
cp python_templates/cluster_static_template.py app-cluster/__main__.py
cp Pulumi_yaml_template app-cluster/Pulumi.yaml
```

Edit to fit the project. The `Pulumi_yaml_template` is already formatted with the runtime an virtual environment. The name and description should be edited to fit the name and description of the project. If using a different runtime and toolchain, edit accordingly. This assumes the runtime is `python` and the toolchain is `uv`

## Create the pulumi stack
After editing the files, create the pulumi stack
```
cd app-cluster
pulumi stack init --copy-config-from Pulumi.<stack-name>.yaml
```

A glimpse of the what the directory should look like at this state is found in the [sample-projects](./sample-projects) directory

and create a bare uv project and add the packages

```
uv init --bare
uv add pulumi pyyaml
```

## Add the terraform-provider for libvirt
Pulumi no longer maintains a dedicated provider for libvirt. A local [terraform provider](https://www.pulumi.com/registry/packages/libvirt/) will need to be installed

`pulumi package add terraform-provider dmacvicar/libvirt`

This will add the source package to the `pyproject.toml` file created when `uv` initialized the project 

# Add the hashed password
A password will need to be set in order to access the console. SSH access is public key/certificate based.

`pulumi config set --secret kvm:password_hash <value>`

Ensure the password is stored securely and can be retrieved readily in the event troubleshooting from the console is necessary.

Preview the stack before deploying

`pulumi preview`

And deploy the stack

`pulumi up`

The resources are destroyed by executing

`pulumi destroy`

# Limitations

- The major limitation is that Pulumi does not start the KVM guest. The guest will need to manually (or some how programmatically) started for the cloud-init workflow to begin. Once the cloud-init workflow completes, the guest will reboot and will be ready for use.
- The `os-variant` that is normally necessary by `virt-install` is not set. This can be set manually after Pulumi deploys the guest or anytime the guest is shutdown.