Skip to content

Ansible Deployment

Ansible Status: Tested Run on: Mgmt Workstation CI/CD: Examples Available

Overview

Two-playbook approach for deploying and configuring the SOFS guest cluster:

Playbook Target Description
deploy-azure-resources.yml localhost Creates Azure resources via Azure CLI including domain join
configure-sofs-cluster.yml sofs_nodes (WinRM) Configures guest OS: anti-affinity, clustering, S2D, SOFS, shares, permissions, Cloud Cache

Capability

Capability Supported
Azure resource provisioning ✅
Domain join (JsonADDomainExtension) ✅ (Phase 2)
Anti-affinity rules ✅ (Phase 3)
Guest OS configuration (WinRM) ✅ (Phases 3–11)
Single/triple layout handling ✅
FSRM quotas ❌ (use PowerShell path)
Cloud Cache DR (multi-provider) ✅

Prerequisites

  • Python 3.9+
  • Python packages: pywinrm, requests-kerberos
  • Azure CLI authenticated (az login)
  • ansible.windows collection: 
    ansible-galaxy collection install ansible.windows
  • WinRM/Kerberos connectivity from the Ansible controller to SOFS VMs
  • All general prerequisites met

File Inventory

File Purpose
inventory/inventory.yml Host inventory + all SOFS variables (single/triple layout, permissions, Cloud Cache)
inventory/hosts.example.yml Example host inventory with sofs_nodes and host_cluster groups
playbooks/deploy-azure-resources.yml Playbook 1: Azure resource deployment + domain join
playbooks/configure-sofs-cluster.yml Playbook 2: Guest cluster configuration (Phases 3–11)
molecule/default/molecule.yml Molecule test configuration
requirements.yml Ansible Galaxy collection requirements
inventory-generated.yml Auto-generated by Terraform (if using Terraform → Ansible path)

Supplemental Playbooks

Playbook Target Description
playbooks/configure-sofs.yml SOFS nodes SMB share creation with CA + ABE + encryption (overlaps Phase 8–9)
playbooks/configure-fslogix.yml AVD session hosts FSLogix registry + Cloud Cache CCDLocations on session hosts

Setup

1. Configure Inventory

If not using Terraform-generated inventory:

cp src/ansible/inventory.yml src/ansible/my-inventory.yml

Update:

  • Azure subscription ID and resource IDs
  • VM IPs in the sofs_nodes group
  • WinRM credentials (use ansible-vault for passwords)
  • All SOFS configuration variables (cluster name, S2D settings, share model)

2. If Using Terraform → Ansible Path

Terraform auto-generates inventory-generated.yml with all values populated from Terraform outputs, including the cloud witness storage key. No manual inventory creation needed.

Azure Resource Deployment

# Dry run
ansible-playbook -i inventory.yml deploy-azure-resources.yml --check

# Deploy
ansible-playbook -i inventory.yml deploy-azure-resources.yml \
  --extra-vars "sofs_admin_password=$(az keyvault secret show --vault-name kv-platform-prod --name sofs-vm-admin-password --query value -o tsv)"

This runs Azure CLI commands on localhost to create the resource group, cloud witness, NICs, VMs, and data disks.

Guest Cluster Configuration

After VMs are deployed, domain-joined, and anti-affinity rules are set:

# Dry run
ansible-playbook -i inventory.yml configure-sofs-cluster.yml --check

# Configure
ansible-playbook -i inventory.yml configure-sofs-cluster.yml \
  --extra-vars "sofs_witness_key=$(az storage account keys list --account-name stsofswitnessprod01 --query '[0].value' -o tsv)"

Actions executed:

# Action
3 Create anti-affinity rule on Azure Local host cluster
4 Verify domain join
5 Install Failover-Clustering, FS-FileServer, RSAT tools
6 Create failover cluster, configure cloud witness
7 Enable S2D, apply guest tuning, create S2D volume(s) — Single layout or Triple layout
8 Add SOFS role, create SMB shares (CA + ABE)
9 Set NTFS permissions (CREATOR OWNER, Domain Users, Domain Admins, SYSTEM)
9b FSRM quotas (not implemented in current Ansible playbook)
9c Configure Cloud Cache CCDLocations (multi-provider)
10 Antivirus exclusions (not implemented in current Ansible playbook)
11 Run validation checks

End-to-End Deployment

# Azure resources
ansible-playbook -i inventory.yml deploy-azure-resources.yml \
  --extra-vars "sofs_admin_password=<password>"

# Wait for VMs to be domain-joined and anti-affinity rules set
# (manual — not yet automated in Ansible)

# Guest configuration
ansible-playbook -i inventory.yml configure-sofs-cluster.yml \
  --extra-vars "sofs_witness_key=<key>"

Session Host Configuration (Post-SOFS)

After the SOFS is fully deployed, configure FSLogix on AVD session hosts:

ansible-playbook -i session-hosts-inventory.yml configure-fslogix.yml

This applies FSLogix registry settings — enables profile containers, sets VHDLocations, configures naming and cleanup. See FSLogix Configuration for details.

Testing

Molecule test scenarios validate playbook syntax and variable handling:

cd src/ansible
pip install molecule molecule-plugins[docker]
molecule test

The molecule/default/molecule.yml defines a test inventory with all SOFS variables including Cloud Cache providers.

Variable Mapping

Ansible inventory variables correspond to the central config/variables.yml structure. Key mappings:

variables.yml Ansible Variable
sofs.cluster_name sofs_cluster_name
sofs.cluster_ip sofs_cluster_ip
sofs.role_name sofs_access_point
s2d.volume_name s2d_volume_name
s2d.volume_size_gb s2d_volume_size_gb
s2d.data_copies s2d_data_copies
domain.fqdn domain_fqdn
domain.netbios domain_netbios
deployment.guest_layout sofs_guest_volume_layout
deployment.guest_resiliency sofs_guest_resiliency
permissions.* sofs_admin_group, sofs_users_group
fslogix.cloud_cache.providers sofs_cloud_cache_providers

Next Steps