This directory contains automated scripts for managing Multipass VMs and deploying the SWA (Secure Workload Access) solution.
- Multipass installed: Download from https://multipass.run/install
- Ansible installed: Required for deployment automation
- Terraform installed: Version 1.0 or higher (download)
- CyberArk Certificate Manager SAAS Account: With Workload Identity Manager (Firefly) activated
- Sign up at https://ui.venafi.cloud
- Obtain API key from Settings > API Keys
- Environment Variables: Set before running scripts:
Or add them to
export TF_VAR_apikey="your-cyberark-api-key" export TF_VAR_team_owner_email="[email protected]"
.envfile in the project root - SSH key pair for SWA VMs: Generate a dedicated SSH key:
This creates
ssh-keygen -t ed25519 -f ~/.ssh/swa_multipass -N "" -C "swa-multipass-vms"
~/.ssh/swa_multipass(private key) and~/.ssh/swa_multipass.pub(public key) - SWA Binaries: Download
swa-serverandswa-agentbinaries from releases and place them in thebinaries/directory
For a fully automated setup:
-
Set environment variables:
export TF_VAR_apikey="your-cyberark-api-key" export TF_VAR_team_owner_email="[email protected]"
-
Run the complete setup:
./scripts/00_full-setup.sh
This will execute all steps automatically: deploy VMs, setup Terraform control-plane, configure inventory, test connectivity, deploy SWA, and verify the installation.
Orchestrates the entire deployment pipeline from start to finish.
What it does:
- Runs all setup scripts in sequence (01 → 02 → 03 → 04 → 05 → 06)
- Handles errors gracefully and provides detailed progress output
- Sets up CyberArk control-plane via Terraform
- Deploys VMs, configures inventory, deploys SWA, and verifies
- Displays final summary and next steps
Usage:
./scripts/00_full-setup.shWhen to use: First-time setup or complete redeployment
Deploys three Ubuntu 22.04 VMs using Multipass:
- swa-server-01: SWA server (2 CPUs, 2GB RAM, 10GB disk)
- swa-agent-01: SWA agent (2 CPUs, 2GB RAM, 10GB disk)
- swa-agent-02: SWA agent (2 CPUs, 2GB RAM, 10GB disk)
What it does:
- Creates VMs with cloud-init (Python 3, SSH keys)
- Generates
vm-config.txtwith VM details - Generates
ansible-inventory-snippet.ymlfor Ansible - Validates SSH key exists before deployment
- Idempotent: skips existing VMs
Usage:
./scripts/01_deploy-vms.shOutput Files:
scripts/vm-config.txt- Human-readable VM configurationscripts/ansible-inventory-snippet.yml- Ansible inventory format
Configures CyberArk Workload Identity Manager (formerly Firefly) using Terraform.
What it does:
- Validates required environment variables (TF_VAR_apikey, TF_VAR_team_owner_email)
- Optionally loads variables from
.envfile - Runs
terraform init,plan, andapply - Creates Firefly configuration, Sub CA, and service account
- Saves
terraform_outputs.jsonfor Ansible consumption - Generates service account credentials in
terraform/firefly-deployment/serviceaccount/
Usage:
# Set environment variables first
export TF_VAR_apikey="your-api-key"
export TF_VAR_team_owner_email="[email protected]"
# Then run the script
./scripts/02_setup-terraform.shRequirements:
- Terraform 1.0+ installed
- CyberArk Certificate Manager SAAS account
- Valid API key and email address set as environment variables
- Internet connectivity
Note: This script uses only environment variables (TF_VAR_*), not terraform.tfvars files.
Outputs:
terraform/firefly-deployment/terraform_outputs.json- Terraform outputs for Ansibleterraform/firefly-deployment/serviceaccount/*.pem- Service account credentials
Copies the generated inventory snippet to the Ansible inventory location.
What it does:
- Backs up existing
ansible/inventory/hosts.yml - Copies
ansible-inventory-snippet.ymltoansible/inventory/hosts.yml - Displays the new inventory configuration
Usage:
./scripts/03_update-inventory.shBackup location: ansible/inventory/hosts.yml.backup.YYYYMMDD-HHMMSS
Tests SSH connectivity to all VMs defined in the Ansible inventory.
What it does:
- Uses Ansible ping module to test all hosts
- Tests individual SSH connections to each VM
- Provides troubleshooting tips if connections fail
Usage:
./scripts/04_test-connectivity.shValidates:
- Ansible can reach all VMs
- SSH keys are properly configured
- VMs are ready for deployment
Runs the Ansible playbook to deploy SWA server and agents.
What it does:
- Validates binaries exist in
binaries/directory - Executes
ansible/deploy-swa.ymlplaybook - Deploys SWA server to
swa_serversgroup - Deploys SWA agents to
swa_agentsgroup - Runs with verbose output for debugging
Usage:
./scripts/05_deploy-swa.shKnown Issue: May show errors about /tmp/trust_bundles/*.pem not found. This is a known issue and can be ignored.
Checks that SWA services are running on all VMs.
What it does:
- Checks SWA server systemd service status
- Checks SWA agent systemd service status
- Verifies agent socket exists at
/run/swa-agent/api.sock - Attempts to fetch a test JWT token
- Displays detailed service status and logs
Usage:
./scripts/06_verify-deployment.shChecks:
- Services are active and running
- Socket files are present
- JWT token fetch works (if workload is registered)
Destroys all SWA-related Multipass VMs and cleans up configuration files.
What it does:
- Stops and deletes all SWA VMs
- Purges VMs from Multipass
- Removes generated configuration files
- Requires confirmation before deletion
Usage:
./scripts/07_destroy-vms.shWhen to use: Cleanup or starting fresh
Destroys all CyberArk Workload Identity Manager (Firefly) resources created by Terraform.
What it does:
- Runs
terraform destroyin the firefly-deployment directory - Removes Firefly configuration, Sub CA, policy, and service account
- Optionally cleans up service account credential files
- Removes
terraform_outputs.json
Usage:
./scripts/08_destroy-terraform.shWarning: This is destructive and cannot be undone. Make sure no active workloads are using these resources.
When to use:
- Complete cleanup after testing
- Resetting the control-plane configuration
- Before recreating with different settings
If you prefer to run steps individually:
./scripts/01_deploy-vms.shReview generated configuration:
cat scripts/vm-config.txt
cat scripts/ansible-inventory-snippet.ymlSet environment variables:
export TF_VAR_apikey="your-api-key"
export TF_VAR_team_owner_email="[email protected]"Run Terraform setup:
./scripts/02_setup-terraform.shThis will create the CyberArk Workload Identity Manager configuration.
./scripts/03_update-inventory.sh./scripts/04_test-connectivity.shIf this fails, troubleshoot before proceeding:
# Check VM status
multipass list
# Test manual SSH
ssh -i ~/.ssh/swa_multipass ubuntu@<VM_IP>Ensure binaries are in place:
ls -lh binaries/Deploy:
./scripts/05_deploy-swa.sh./scripts/06_verify-deployment.shDestroy VMs:
./scripts/07_destroy-vms.shDestroy Terraform resources:
./scripts/08_destroy-terraform.shEdit scripts/01_deploy-vms.sh and change these variables:
SERVER_CPUS=2
SERVER_MEM="2G"
SERVER_DISK="10G"
AGENT_CPUS=2
AGENT_MEM="2G"
AGENT_DISK="10G"Edit scripts/01_deploy-vms.sh and modify the array:
AGENT_VMS=("swa-agent-01" "swa-agent-02" "swa-agent-03" "swa-agent-04")Edit both scripts/01_deploy-vms.sh and update:
SSH_PUBLIC_KEY="$HOME/.ssh/your_custom_key.pub"
SSH_PRIVATE_KEY="$HOME/.ssh/your_custom_key"# List all VMs
multipass list
# Get VM details
multipass info swa-server-01
# Shell into a VM
multipass shell swa-server-01
# Stop/Start VMs
multipass stop swa-server-01
multipass start swa-server-01
# Delete and purge
multipass delete swa-server-01
multipass purge# Check service status
ansible swa_servers -i ansible/inventory/hosts.yml -a "sudo systemctl status swa-server"
ansible swa_agents -i ansible/inventory/hosts.yml -a "sudo systemctl status swa-agent"
# View logs
ansible swa_servers -i ansible/inventory/hosts.yml -a "sudo journalctl -u swa-server -n 50"
ansible swa_agents -i ansible/inventory/hosts.yml -a "sudo journalctl -u swa-agent -n 50"
# Restart services
ansible swa_servers -i ansible/inventory/hosts.yml -a "sudo systemctl restart swa-server"
ansible swa_agents -i ansible/inventory/hosts.yml -a "sudo systemctl restart swa-agent"# Fetch JWT token from agent (run on agent VM)
/opt/swa/bin/spire-agent api fetch jwt -audience test -socketPath /run/swa-agent/api.sock
# Check agent socket
ls -la /run/swa-agent/api.sockGenerate the SSH key:
ssh-keygen -t ed25519 -f ~/.ssh/swa_multipass -N "" -C "swa-multipass-vms"The deployment script will validate the key exists.
The deploy script is idempotent. To recreate:
./scripts/07_destroy-vms.sh
./scripts/01_deploy-vms.sh- Check VM status:
multipass list - Check IP address:
multipass info swa-server-01 - Test multipass shell:
multipass shell swa-server-01 - Verify SSH key permissions:
ls -la ~/.ssh/swa_multipass* chmod 600 ~/.ssh/swa_multipass
- Test SSH manually:
ssh -i ~/.ssh/swa_multipass ubuntu@<VM_IP>
Environment Variables Not Set:
# Check if variables are set
echo $TF_VAR_apikey
echo $TF_VAR_team_owner_email
# Set them if missing
export TF_VAR_apikey="your-api-key"
export TF_VAR_team_owner_email="[email protected]"Terraform State Issues:
cd terraform/firefly-deployment
terraform init -reconfigureAPI Key Invalid:
- Verify key in CyberArk UI: https://ui.venafi.cloud
- Generate new API key if needed
- Check account permissions
- Ensure Terraform setup completed:
ls terraform/firefly-deployment/terraform_outputs.json - Ensure connectivity:
./scripts/04_test-connectivity.sh - Check binaries exist:
ls -lh binaries/ - Verify group_vars:
cat ansible/group_vars/swa_servers.yml - Check for specific error in Ansible output
- Known issue:
/tmp/trust_bundles/*.pemerrors can be ignored
Check service status and logs:
# On the VM directly
multipass shell swa-server-01
sudo systemctl status swa-server
sudo journalctl -u swa-server -n 100
# Or via Ansible
ansible swa_servers -i ansible/inventory/hosts.yml -a "sudo systemctl status swa-server --no-pager"
ansible swa_servers -i ansible/inventory/hosts.yml -a "sudo journalctl -u swa-server -n 100 --no-pager"macOS:
brew install multipassLinux:
snap install multipassWindows: Download installer from https://multipass.run/install
macOS:
brew install ansibleLinux:
sudo apt-get install ansible # Debian/Ubuntu
sudo yum install ansible # RHEL/CentOSmacOS:
brew install terraformLinux:
# Download latest from https://www.terraform.io/downloads
wget https://releases.hashicorp.com/terraform/1.6.0/terraform_1.6.0_linux_amd64.zip
unzip terraform_1.6.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/Verify:
terraform version- VMs are configured with Ubuntu 22.04 LTS
- Python 3 is pre-installed for Ansible compatibility
- SSH keys are automatically injected via cloud-init
- VMs use Multipass default network (typically 192.168.64.0/24 on macOS)
- First run downloads the Ubuntu image (~500MB)
- The complete setup takes approximately 10-15 minutes
- Binaries must be downloaded separately and placed in
binaries/
-
Test JWT token fetch:
multipass shell swa-agent-01 /opt/swa/bin/spire-agent api fetch jwt -audience test -socketPath /run/swa-agent/api.sock -
Explore integration examples:
ls -la examples/
-
Configure OIDC federation:
- Follow instructions in
docs/for AWS, Azure, or Conjur integration
- Follow instructions in
-
Read the documentation:
CLAUDE.md- Project overview and commandsDEMO.md- Demo scenariosTROUBLESHOOTING.md- Common issues
For issues or questions:
- Check
TROUBLESHOOTING.mdin the project root - Review Ansible output for specific errors
- Check service logs via
journalctl - Verify configuration in
ansible/group_vars/