windows-iac-vm-tooling/docs/05-ansible/pipeline.md

# ✅ Ansible Pipeline

[![Ansible](https://img.shields.io/badge/Ansible-Latest-blue?style=flat&logo=ansible)](https://www.ansible.com/)

## Overview

Ansible automates verification of the Windows installer on the provisioned VM. This document details the playbook in [`ansible/pipeline.yml`](../../ansible/pipeline.yml).

---

## Playbook Structure

```mermaid
flowchart TD
    subgraph Playbook["Ansible Pipeline"]
        direction TB
        Play[Play: Verify Installer] --> Tasks[Tasks List]
        Tasks --> T1[Create Workspace] --> T2[Upload Installer] --> T3[Install] --> T4[Verify] --> T5[Assert]
    end
    
    subgraph Hosts["Host Selection"]
        H[windows_vm] --> Play
    end
    
    style Playbook fill:#e3f2fd
    style Hosts fill:#e8f5e9
```

---

## Full Playbook

```yaml
- name: Verify Installer
  hosts: windows_vm
  tasks:
    - name: Create Workspace
      ansible.windows.win_file:
        path: C:\Test
        state: directory

    - name: Upload Signed Installer
      ansible.windows.win_copy:
        src: ./dist/installer_signed.exe
        dest: C:\Test\installer.exe

    - name: Install (Silent Mode)
      ansible.windows.win_command: C:\Test\installer.exe /S
      register: install_result

    - name: Verify Executable Exists
      ansible.windows.win_stat:
        path: "C:\\Program Files\\MyApp\\app.exe"
      register: installed_file

    - name: Assert Installation
      assert:
        that:
          - installed_file.stat.exists
```

---

## Task Details

### 1. Create Workspace

```yaml
- name: Create Workspace
  ansible.windows.win_file:
    path: C:\Test
    state: directory
```

**Purpose:** Creates a directory for temporary files on the Windows VM.

### 2. Upload Installer

```yaml
- name: Upload Signed Installer
  ansible.windows.win_copy:
    src: ./dist/installer_signed.exe
    dest: C:\Test\installer.exe
```

**Purpose:** Copies the signed installer from the build host to the Windows VM.

### 3. Silent Install

```yaml
- name: Install (Silent Mode)
  ansible.windows.win_command: C:\Test\installer.exe /S
  register: install_result
```

**Purpose:** Runs the installer in silent mode (`/S` flag).

### 4. Verify Installation

```yaml
- name: Verify Executable Exists
  ansible.windows.win_stat:
    path: "C:\\Program Files\\MyApp\\app.exe"
  register: installed_file
```

**Purpose:** Checks if the installed executable exists at the expected path.

### 5. Assert Result

```yaml
- name: Assert Installation
  assert:
    that:
      - installed_file.stat.exists
```

**Purpose:** Fails the pipeline if the executable is not found.

---

## Inventory Configuration

### Dynamic Inventory

The inventory is generated in the Forgejo workflow:

```ini
[windows_vm]
<VM_IP> ansible_user=Administrator ansible_password=<password> ansible_connection=winrm ansible_winrm_server_cert_validation=ignore
```

### Inventory Variables

| Variable | Value | Purpose |
|----------|-------|---------|
| `ansible_user` | `Administrator` | Windows admin account |
| `ansible_password` | From secret | WinRM password |
| `ansible_connection` | `winrm` | Connection type |
| `ansible_winrm_server_cert_validation` | `ignore` | Skip cert validation |

---

## Execution Flow

```mermaid
sequenceDiagram
    participant Runner as Forgejo Runner
    participant WinVM as Windows VM
    
    Runner->>WinVM: Connect via WinRM
    WinVM->>Runner: Connection established
    
    Runner->>WinVM: Create C:\Test directory
    WinVM->>Runner: Directory created
    
    Runner->>WinVM: Upload installer_signed.exe
    WinVM->>Runner: File uploaded
    
    Runner->>WinVM: Execute installer.exe /S
    WinVM->>Runner: Installation complete
    
    Runner->>WinVM: Check app.exe exists
    WinVM->>Runner: File found (or not)
    
    alt File exists
        Runner->>Runner: PASS - Continue pipeline
    else File missing
        Runner->>Runner: FAIL - Stop pipeline
    end
```

---

## Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| WinRM connection timeout | Firewall blocking | Disable Private firewall |
| Credential rejected | Wrong password | Verify WIN_ADMIN_PASS |
| File not found | Wrong path | Check installation path |

---

## Next Steps

| Goal | Next Document |
|------|---------------|
| Run pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |
| View Terraform | [OpenTofu Resources](../04-terraform/main.tf.md) |
| Troubleshoot | [Troubleshooting](../07-advanced/troubleshooting.md) |

---

[← Documentation Index](../index.md) | [→ Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) | [← Terraform Variables](../04-terraform/variables.md)