LazyMagic AWS PowerShell Deployment
Deploy and manage multi-tenant SaaS applications on AWS using PowerShell cmdlets with CloudFormation/SAM templates.
What This Skill Does
This skill helps you work with the LzAws PowerShell module for deploying AWS infrastructure, authentication systems, services, web applications, and tenant resources in a multi-tenant SaaS architecture.
Instructions
When working with LzAws module code or deployments:
1. Module Development Setup
**Loading the module for development:**
```powershell
Use the development import script
.\Import-LzAws.ps1
Or manually import with force reload
Import-Module ./LzAws.psd1 -Force
```
**Installing the module:**
```powershell
Install for current user
.\Install-LzAws.ps1 -Scope CurrentUser
Install for all users (requires admin)
.\Install-LzAws.ps1 -Scope AllUsers
```
2. Deployment Order
Execute deployments in this specific order:
```powershell
1. System infrastructure (core AWS resources)
Deploy-SystemAws
2. CloudFront and caching policies
Deploy-PoliciesAws
3. Permission policies
Deploy-PermsAws
4. Cognito authentication resources
Deploy-AuthsAws
5. Lambda functions and APIs (run from Service/AwsTemplates folder)
Deploy-ServiceAws -ServiceKey "myservice"
6. Frontend web application (run from App's solution folder)
Deploy-WebappAws
7. Static assets to S3 (run from Tenancies solution folder)
Deploy-AssetsAws
8. Tenant resources (run from Service/AwsTemplates folder)
Deploy-TenantsAws # All tenants
Deploy-TenantAws -TenantKey "tenant1" # Specific tenant
```
3. Module Architecture
**File Organization:**
`/Public/` - User-facing cmdlets (exported from module)`/Private/` - Internal helper functions (not exposed)`LzAws.psm1` - Main module file`LzAws.psd1` - Module manifest**Configuration:**
Uses `systemconfig.yaml` for system, tenant, and service configurationConfiguration discovered via `Find-FileUp` searching up directory treeCached in `$script:Config` after first loadAlways use `Get-SystemConfig` at start of functions**Module-Scoped Variables:**
`$script:LzAwsVerbosePreference` - Custom verbosity control`$script:awsModulesRemoved` - Tracks AWS module cleanup`$script:LzConfig` - Cached configuration`$script:ProfileName` - AWS profile name`$script:Region` - AWS region4. Error Handling Pattern
**Private Functions:**
```powershell
Create detailed error with here-string
$errorMessage = @"
Error: Brief description of what went wrong
Function: FunctionName
Hints:
- Check your AWS credentials
- Verify the systemconfig.yaml exists
- Ensure you have the necessary permissions
"@
throw $errorMessage
```
**Public Functions:**
```powershell
try {
# Operations here
return $true
}
catch {
Write-Host ($_.Exception.Message)
return $false
}
```
5. Function Development Guidelines
**Parameter Handling:**
```powershell
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[string]$TenantKey,
[ValidateSet('Development', 'Production')]
[string]$Environment = 'Development'
)
```
**AWS Service Integration:**
Always include `-ProfileName $script:ProfileName -Region $script:Region` on AWS cmdletsCheck resource existence before creation (idempotent operations)Handle "No changes to deploy" as non-errorUse SAM CLI for CloudFormation deployments**Verbose Logging:**
```powershell
Use custom verbose function (not Write-Verbose)
Write-LzAwsVerbose "Loading configuration from $configPath"
Enable verbose output
Set-LzAwsVerbosity -Preference "Continue"
```
**Output Patterns:**
`Write-Host` - User-facing messages and errors`Write-LzAwsVerbose` - Internal operations and debuggingReturn `$true`/`$false` for success/failureReturn data objects for Get- functions`Write-OutputDictionary` - Structured key-value output6. Naming Conventions
**Functions:**
Public: `Verb-NounAws` (e.g., `Deploy-SystemAws`)Private: `Verb-Noun` (e.g., `Get-SystemConfig`)Use approved PowerShell verbs only**Variables:**
Parameters: PascalCase (`$TenantKey`)Local variables: PascalCase (`$StackName`)Script-scoped: camelCase with prefix (`$script:profileName`)7. Adding New Functions
1. Create one file per function in `/Public` or `/Private`
2. Filename must match function name exactly
3. For public functions, add to `FunctionsToExport` in `LzAws.psd1`
4. Follow error handling pattern for function type
5. Include proper parameter validation
6. Add verbose logging for key operations
8. Configuration Management
**Configuration Hierarchy:**
System level → Tenant level → Subtenant levelStack outputs merged into parameters via `Get-StackOutputs`Use fallback pattern for optional values:```powershell
$Value = $DefaultValue
if($Config.ContainsKey('Property') -and ![string]::IsNullOrWhiteSpace($Config.Property)) {
$Value = $Config.Property
}
```
9. Testing
```powershell
Test error handling
Deploy-TestError
Get-TestError
View available commands
Get-AwsCommands
Get detailed help
Get-LzAwsHelp -CommandName "Deploy-SystemAws"
```
10. Required Dependencies
Module dependencies (auto-installed):
`powershell-yaml`: 0.4.2`AWS.Tools.Common`: 4.1.748`AWS.Tools.S3`: 4.1.748`AWS.Tools.CloudFormation`: 4.1.748`AWS.Tools.CloudFrontKeyValueStore`: 4.1.748`AWS.Tools.DynamoDBv2`: 4.1.136External requirements:
PowerShell 5.1 or higherSAM CLI installed and in PATHAWS credentials configured (SSO or standard)Constraints
Always validate configuration exists before using (`if ($null -eq $Config)`)Never use PowerShell's built-in `-Verbose` parameter - use module's custom systemDon't catch and re-throw errors in public functions - display and return falseDon't assume AWS resources exist - always check firstTest from different directories to ensure `Find-FileUp` works correctlyEnsure all AWS operations include profile and region parameters