vdi module - password reset handling

Author: scott-nag

community/modules/scripts/vdi-setup/README.md

@@ -2,16 +2,37 @@
 
 Creates a containerised Guacamole instance. Works with the Rocky, Debian and Ubuntu images shown in blueprint example below.
 
-### Secret Manager Integration
+## Features
 
-The VDI module supports flexible Secret Manager integration:
+- **VDI Tool Support**: Currently supports Guacamole for web-based VDI access
+- **User Provisioning**: Supports local user creation with secure password management
+- **VNC Integration**: Configures VNC servers for desktop access
+- **Secret Manager Integration**: Secure password storage and retrieval for VDI users and webapp admin
+- **VDI Monitoring System**: Automatic monitoring and reconfiguration capabilities with password reset flags and deployment status updates
+- **Debug Mode**: Comprehensive logging when enabled via the `debug` variable
 
-- **Default Behavior**: Secrets are stored in the deployment project
-- **Automatic Password Generation**: If no `secret_name` is provided, random passwords are generated and stored
-- **Existing Secret Retrieval**: Provide `secret_name` to use existing secrets from Secret Manager
-- **Cross-Project Secrets**: Use `secret_project` to specify a different GCP project if providing secrets
+## Secret Manager Integration
 
-## Basic Example (Guacamole)
+The module integrates with Google Cloud Secret Manager for secure password handling:
+
+- **VDI Users**: Passwords are stored in Secret Manager with the pattern `vdi-user-password-{username}-{deployment_name}`
+- **Webapp Admin**: Password is stored in Secret Manager with the pattern `webapp-server-password-{deployment_name}` (always stored, not just when reset is enabled)
+- **Password Sources**: Users can specify `secret_name` to fetch existing passwords, provide `password` directly, or let the system generate random passwords
+- **Reset Functionality**: Both individual user passwords (`reset_password`) and webapp admin password (`reset_webapp_admin_password`) can be forced to regenerate
+- **Database Updates**: Password resets update existing database records without re-initializing the entire database
+
+## VDI Monitoring System
+
+The module includes a monitoring system that:
+
+- **Deployment Status**: Updates instance metadata to reflect deployment state (`available`, `reconfiguring`)
+- **Password Reset Flags**: Supports `reset_password` for individual users and `reset_webapp_admin_password` for the webapp admin account
+- **Automatic Reconfiguration**: Detects changes and triggers reconfiguration when needed
+- **Status Tracking**: Maintains deployment status through instance metadata
+
+## Usage
+
+### Basic Configuration
 
 ```yaml
 blueprint_name: vdi-test
@@ -51,9 +72,13 @@ deployment_groups:
     settings:
       vnc_flavor: tigervnc
       vdi_tool: guacamole
-      user_provision: local_users
       vdi_user_group: vdiusers
       vdi_resolution: 1920x1080
+      # Enable debug mode for verbose logging
+      debug: true
+      # Force reset of webapp admin password (optional)
+      reset_webapp_admin_password: false
+      user_provision: local_users
       vdi_users:
       # Alice: password generated and saved to Secret Manager in deployment project
       - username: alice
@@ -67,6 +92,10 @@ deployment_groups:
         port: 5903
         secret_name: charlie-password
         secret_project: another-project-id
+      # David: auto-generated password with reset flag (triggers password regeneration)
+      - username: david
+        port: 5904
+        reset_password: true
 
   - id: guac_vm
     source: modules/compute/vm-instance
@@ -79,6 +108,8 @@ deployment_groups:
         #project: debian-cloud
         #family: ubuntu-2204-lts
         #project: ubuntu-os-cloud
+        name_prefix: debian
+        add_deployment_name_before_prefix: true
       machine_type: e2-highcpu-8
       tags: ["guacamole"]
     use:
@@ -98,18 +129,18 @@ echo -n "BobPassword123" | gcloud secrets create a-password-for-bob --data-file=
 echo -n "CharliePassword123" | gcloud secrets create charlie-password --data-file=- --project=another-project-id
 ```
 
-### Accessing Guacamole VDI
+### Accessing VDI
 
 After deployment, you can access the VDI in several ways:
 
-1. **Guacamole Web Interface**:
+1. **Web Interface** (for Guacamole):
    - Access web interface:
      - http://$VM_PUBLIC_IP:8080/guacamole/#/
-     - Note: It is not advisable to serve Guacamole directly from a public IP in production environments. You should consider placing the VDI behind a reverse proxy, load balancer, or tunnel to it directly over IAP (see below).
+     - Note: It is not advisable to serve the web interface directly from a public IP in production environments. You should consider placing the VDI behind a reverse proxy, load balancer, or tunnel to it directly over IAP (see below).
 
    - Admin credentials:
-     - Username: `guacadmin`
-     - Password: Retrieve the `webapp-server...` secret from Secret Manager
+     - Username: `guacadmin` (for Guacamole)
+     - Password: Retrieve the `webapp-server-password-{deployment_name}` secret from Secret Manager
 
 2. **User VDI Access**:
    - Each user's credentials are stored in Secret Manager
@@ -124,65 +155,4 @@ After deployment, you can access the VDI in several ways:
        --zone=us-central1-a
    ```
 
-   - Guacamole will then be accessible from http://localhost:8080/guacamole/
-
-<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
-## Requirements
-
-| Name | Version |
-|------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
-| <a name="requirement_archive"></a> [archive](#requirement\_archive) | ~> 2.0 |
-| <a name="requirement_google"></a> [google](#requirement\_google) | >= 3.83 |
-
-## Providers
-
-| Name | Version |
-|------|---------|
-| <a name="provider_archive"></a> [archive](#provider\_archive) | ~> 2.0 |
-| <a name="provider_google"></a> [google](#provider\_google) | >= 3.83 |
-| <a name="provider_terraform"></a> [terraform](#provider\_terraform) | n/a |
-
-## Modules
-
-| Name | Source | Version |
-|------|--------|---------|
-| <a name="module_startup_script"></a> [startup\_script](#module\_startup\_script) | ../../../../modules/scripts/startup-script | n/a |
-
-## Resources
-
-| Name | Type |
-|------|------|
-| [google_storage_bucket.bucket](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket) | resource |
-| [terraform_data.input_validation](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
-| [archive_file.roles_tar](https://registry.terraform.io/providers/hashicorp/archive/latest/docs/data-sources/file) | data source |
-
-## Inputs
-
-| Name | Description | Type | Default | Required |
-|------|-------------|------|---------|:--------:|
-| <a name="input_deployment_name"></a> [deployment\_name](#input\_deployment\_name) | The name of the deployment. | `string` | n/a | yes |
-| <a name="input_labels"></a> [labels](#input\_labels) | Key-value pairs of labels to be added to created resources. | `map(string)` | n/a | yes |
-| <a name="input_project_id"></a> [project\_id](#input\_project\_id) | Project in which the HPC deployment will be created. | `string` | n/a | yes |
-| <a name="input_region"></a> [region](#input\_region) | Region to place bucket containing startup script. | `string` | n/a | yes |
-| <a name="input_user_provision"></a> [user\_provision](#input\_user\_provision) | User type to create (local\_users supported. os-login to do. | `string` | `"local_users"` | no |
-| <a name="input_vdi_resolution"></a> [vdi\_resolution](#input\_vdi\_resolution) | Desktop resolution for VNC sessions (e.g. 1920x1080). | `string` | `"1920x1080"` | no |
-| <a name="input_vdi_tool"></a> [vdi\_tool](#input\_vdi\_tool) | VDI tool to deploy (guacamole currently supported). | `string` | `"guacamole"` | no |
-| <a name="input_vdi_user_group"></a> [vdi\_user\_group](#input\_vdi\_user\_group) | Unix group to create/use for VDI users. | `string` | `"vdiusers"` | no |
-| <a name="input_vdi_users"></a> [vdi\_users](#input\_vdi\_users) | List of VDI users to configure. Passwords are handled securely by the Ansible roles: if secret\_name is provided, the password is fetched from Secret Manager; if neither password nor secret\_name is provided, a random password is generated and stored in Secret Manager. If secret\_project is provided, it specifies the GCP project where the secret is stored (defaults to the deployment project). | <pre>list(object({<br/>    username       = string<br/>    port           = number<br/>    secret_name    = optional(string)<br/>    secret_project = optional(string)<br/>  }))</pre> | `[]` | no |
-| <a name="input_vdi_webapp_port"></a> [vdi\_webapp\_port](#input\_vdi\_webapp\_port) | Port to serve the Webapp interface from if applicable | `string` | `"8080"` | no |
-| <a name="input_vnc_flavor"></a> [vnc\_flavor](#input\_vnc\_flavor) | The VNC server flavor to use (tigervnc currently supported) | `string` | `"tigervnc"` | no |
-| <a name="input_vnc_port_max"></a> [vnc\_port\_max](#input\_vnc\_port\_max) | Maximum valid VNC port. | `number` | `5999` | no |
-| <a name="input_vnc_port_min"></a> [vnc\_port\_min](#input\_vnc\_port\_min) | Minimum valid VNC port. | `number` | `5901` | no |
-| <a name="input_debug"></a> [debug](#input\_debug) | Enable debug mode for verbose logging during VDI setup. | `bool` | `false` | no |
-
-## Outputs
-
-| Name | Description |
-|------|-------------|
-| <a name="output_guacamole_admin_password_secret"></a> [guacamole\_admin\_password\_secret](#output\_guacamole\_admin\_password\_secret) | The name of the Secret Manager secret containing the Guacamole admin password |
-| <a name="output_guacamole_admin_username"></a> [guacamole\_admin\_username](#output\_guacamole\_admin\_username) | The admin username for Guacamole |
-| <a name="output_startup_script"></a> [startup\_script](#output\_startup\_script) | Combined startup script that installs VDI (VNC, Guacamole, users). |
-| <a name="output_vdi_runner"></a> [vdi\_runner](#output\_vdi\_runner) | Shell runner wrapping Ansible playbook + roles (for custom-image or direct use). |
-| <a name="output_vdi_user_credentials"></a> [vdi\_user\_credentials](#output\_vdi\_user\_credentials) | Map of VDI user credentials stored in Secret Manager |
-<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+   - The web interface will then be accessible from http://localhost:8080/guacamole/ (for Guacamole)