Pulumi Factory - Local Backend

This directory contains the local backend workflow for the Pulumi Factory. The local backend workflow creates Pulumi projects without any cloud dependencies, using local file-based state storage. This is perfect for development, testing, and getting started with Pulumi.

Overview

The local backend workflow provides:

No AWS Dependencies: No cloud accounts or credentials required
Local State Storage: State files stored in local .pulumi/ directory
Rapid Development: Fast iteration without cloud API calls
Cost-Free Development: No charges for state storage or API usage
Educational: Great for learning Pulumi concepts
Migration Ready: Easy migration to cloud backends when needed

Quick Start

Example JSON Configuration

{
  "project_name": "my-app",
  "stack_name": "dev", 
  "pulumi_template": "python",
  "project_description": "My application infrastructure",
  "target_repo_url": "https://github.com/myorg/my-app.git",
  "target_github_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "create_documentation": true,
  "include_examples": true
}

JSON Formatting Notes

Important: Ensure your JSON is properly formatted:

All field names and string values must be in double quotes
Use commas between fields (but not after the last field)
Boolean values are true/false (lowercase, no quotes)
Project names with hyphens: "test-01" (hyphen inside quotes)

Common Mistakes:

❌ "project_name": "test"-01 (hyphen outside quotes)
✅ "project_name": "test-01" (hyphen inside quotes)
❌ "create_documentation": "true" (boolean in quotes)
✅ "create_documentation": true (boolean without quotes)

GitHub Actions Workflow

Navigate to your GitHub repository with the Pulumi Factory
Go to Actions → "Pulumi Project Factory - Initialize Local Backend Project"
Click "Run workflow"
Paste your JSON configuration
Click "Run workflow"

Note: The workflow file is located at .github/workflows/local-init.yml in the repository root, but it references scripts and configuration from the local-backend/ directory.

The workflow will:

Create a Pulumi project with local backend
Generate comprehensive documentation
Create example infrastructure code
Push to a new branch in your target repository

Directory Structure

local-backend/
├── scripts/
│   ├── configure_local_project.py  # Project configuration script
│   ├── generate_documentation.py   # Documentation generation script
│   └── create_examples.py          # Example code generation script
├── docs/
│   ├── COMPLETE_LOCAL_WALKTHROUGH.md  # Complete simulation
│   └── examples/
│       └── json-configs/           # Example JSON configurations
├── requirements.txt                # Python dependencies
└── README.md                      # This file

# Main workflow file (located in repository root)
/.github/workflows/local-init.yml       # GitHub Actions workflow

Configuration Reference

Required Parameters

Parameter	Type	Description	Example
`project_name`	string	Name of the Pulumi project	`"my-app"`
`stack_name`	string	Name of the Pulumi stack	`"dev"`
`target_repo_url`	string	Target GitHub repository URL	`"https://github.com/org/repo.git"`
`target_github_token`	string	GitHub personal access token	`"ghp_xxx..."`

Optional Parameters

Parameter	Type	Default	Description
`pulumi_template`	string	`"python"`	Pulumi template type
`project_description`	string	Auto-generated	Project description
`create_documentation`	boolean	`true`	Generate documentation files
`include_examples`	boolean	`true`	Include example infrastructure code

Supported Templates

python: Python with AWS provider
typescript: TypeScript/Node.js with AWS provider
go: Go with AWS provider
csharp: C#/.NET with AWS provider
yaml: YAML-based infrastructure definition

Generated Project Structure

The workflow creates a complete Pulumi project:

target-repo/
└── project-name/
    ├── .pulumi/                    # Local state storage (excluded from git)
    ├── scripts/                    # Development helper scripts
    │   ├── preview.py             # Preview infrastructure changes
    │   ├── deploy.py              # Deploy infrastructure
    │   └── destroy.py             # Destroy infrastructure
    ├── examples/                   # Additional example code (optional)
    ├── Pulumi.yaml                # Project configuration
    ├── Pulumi.stack-name.yaml     # Stack configuration
    ├── __main__.py                # Main infrastructure code (Python example)
    ├── requirements.txt           # Dependencies (Python example)
    ├── .gitignore                 # Git ignore rules
    ├── README.md                  # Project documentation
    ├── DEVELOPMENT.md             # Development guide
    ├── MIGRATION.md               # Cloud backend migration guide
    └── [template-specific files]  # Additional files based on template

Features

Local Backend Benefits

No External Dependencies: Works without any cloud accounts
Fast Iteration: No network calls for state operations
Complete Control: Direct access to state files
Cost-Free: No cloud charges for development
Offline Capable: Works without internet connection
Educational: Perfect for learning and experimentation

Generated Documentation

Each project includes comprehensive documentation:

README.md: Complete project overview and setup instructions
DEVELOPMENT.md: Detailed development workflow guide
MIGRATION.md: Step-by-step cloud backend migration guide

Development Tools

Generated projects include helpful scripts:

preview.py: Preview infrastructure changes
deploy.py: Deploy infrastructure
destroy.py: Destroy all resources (with confirmation)

Example Infrastructure

Projects include working examples of:

S3 buckets with encryption and versioning
IAM roles and policies
Security groups with common rules
CloudWatch log groups
SSM parameters for configuration
Additional examples in examples/ directory

Local Development Workflow

After project creation:

Clone the repository:

git clone <repository-url>
cd project-name

Install dependencies (template-specific):

# Python
pip install -r requirements.txt

# TypeScript
npm install

# Go
go mod tidy

# C#
dotnet restore

Select the stack:
```
pulumi stack select stack-name
```

Preview infrastructure:

pulumi preview
# or
python scripts/preview.py

Deploy infrastructure:

pulumi up
# or  
python scripts/deploy.py

State Management

Local State Storage

State files stored in .pulumi/ directory
Each stack has its own state file
State is portable between machines
No automatic backup or versioning

State Backup

Regular backups recommended:

# Export state to backup file
pulumi stack export --file backup-$(date +%Y%m%d).json

# Store backups securely
mkdir -p ~/pulumi-backups
mv backup-*.json ~/pulumi-backups/

State Recovery

If state becomes corrupted:

# Import from backup
pulumi stack import --file backup-20231207.json

# Refresh state from actual infrastructure
pulumi refresh

Migration to Cloud Backends

When ready for production, migrate to cloud backends:

Pulumi Cloud (easiest):

pulumi login
pulumi stack init organization/project/stack
pulumi stack import --file state-backup.json

AWS S3 Backend:

pulumi login s3://my-pulumi-state-bucket
pulumi stack init stack-name
pulumi stack import --file state-backup.json

Other Backends: Azure Blob, Google Cloud Storage, etc.

See the generated MIGRATION.md in each project for detailed instructions.

Security Considerations

Local Backend Security

State files may contain sensitive resource information
Use disk encryption for additional security
Backup state files to secure, encrypted storage
Don't commit .pulumi/ directory to version control
Consider cloud backends for production workloads

Secrets Management

Use pulumi config set --secret for sensitive values
Secrets are encrypted in local state files
Consider external secret management for production

Troubleshooting

Common Issues

Template not supported: Check supported templates list
GitHub token issues: Ensure token has repository access
Pulumi CLI issues: Verify Pulumi CLI installation
State file corruption: Restore from backup

Getting Help

Review generated project documentation
Check Pulumi Documentation
Join Pulumi Community Slack
Open issues in Pulumi GitHub

Comparison with AWS Backend Workflow

Feature	Local Backend	AWS Backend
Setup Complexity	Simple	Moderate
AWS Credentials	Not required	Required
State Storage	Local files	S3 bucket
State Backup	Manual	Automatic
Collaboration	Single user	Multi-user
State Locking	None	Available
Cost	Free	S3/KMS charges
Migration	Easy to cloud	Already cloud
Use Cases	Dev, learning, testing	Production, teams

Example Configurations

Python Web Application

{
  "project_name": "webapp",
  "stack_name": "development", 
  "pulumi_template": "python",
  "project_description": "Web application infrastructure with S3, EC2, and RDS",
  "target_repo_url": "https://github.com/mycompany/webapp.git",
  "target_github_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "create_documentation": true,
  "include_examples": true
}

TypeScript Microservices

{
  "project_name": "microservices",
  "stack_name": "local",
  "pulumi_template": "typescript", 
  "project_description": "Microservices infrastructure with Lambda and API Gateway",
  "target_repo_url": "https://github.com/mycompany/microservices-infra.git",
  "target_github_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "create_documentation": true,
  "include_examples": true
}

Go Infrastructure

{
  "project_name": "infrastructure",
  "stack_name": "dev",
  "pulumi_template": "go",
  "project_description": "Core infrastructure components in Go",
  "target_repo_url": "https://github.com/mycompany/core-infrastructure.git", 
  "target_github_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "create_documentation": false,
  "include_examples": false
}

Best Practices

Development

Regular Backups: Export state daily during active development
Version Control: Commit infrastructure code, not state files
Configuration: Use Pulumi config for environment-specific values
Testing: Use preview before applying changes
Documentation: Keep project documentation updated

State Management

Backup Strategy: Automated daily state exports
Secure Storage: Encrypt backups and store securely
State Validation: Regular pulumi refresh operations
Clean Deployments: Avoid manual infrastructure changes

Migration Planning

Test Migration: Practice with project copies
Backup Everything: State, config, and code
Team Coordination: Plan migrations during low activity
Gradual Migration: Migrate non-critical projects first

Contributing

To contribute to the local backend workflow:

Fork the repository
Create a feature branch
Test with the provided examples
Submit a pull request

Support

For issues with the local backend workflow:

Check the generated project documentation
Review the complete walkthrough guide
Search existing GitHub issues
Open a new issue with detailed information

Pulumi Factory - Local Backend
Generated by Pulumi Factory

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/workflows		.github/workflows
local-backend		local-backend
.DS_Store		.DS_Store
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

License

iampzhao/pulumi-local-backend

Folders and files

Latest commit

History

Repository files navigation

Pulumi Factory - Local Backend

Overview

Quick Start

Example JSON Configuration

JSON Formatting Notes

GitHub Actions Workflow

Directory Structure

Configuration Reference

Required Parameters

Optional Parameters

Supported Templates

Generated Project Structure

Features

Local Backend Benefits

Generated Documentation

Development Tools

Example Infrastructure

Local Development Workflow

State Management

Local State Storage

State Backup

State Recovery

Migration to Cloud Backends

Security Considerations

Local Backend Security

Secrets Management

Troubleshooting

Common Issues

Getting Help

Comparison with AWS Backend Workflow

Example Configurations

Python Web Application

TypeScript Microservices

Go Infrastructure

Best Practices

Development

State Management

Migration Planning

Contributing

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages