🌐 IPAM Serverless - IP Address Management System

Production-ready serverless IP Address Management (IPAM) system built with AWS Lambda, DynamoDB, and API Gateway. Features automated testing, comprehensive documentation, and infrastructure as code using Pulumi.

📋 Table of Contents

Features
Architecture
Quick Start
API Endpoints
Development
Testing
CI/CD Pipeline
Deployment
Cost Analysis
Project Structure

✨ Features

Core Functionality

Subnet Management: Create, read, update, delete (CRUD) operations for IP subnets
IP Allocation: Automatic IP address allocation and tracking within subnets
Subnet Calculator: Calculate subnet divisions and available IP ranges
Conflict Detection: Prevent overlapping subnet allocations
CIDR Validation: Validate CIDR notation and subnet masks

DevOps & Infrastructure

Infrastructure as Code: Full Pulumi deployment for AWS resources
Automated Testing: GitHub Actions runs tests on every push
Multi-Environment: Separate dev and production environments
Test Framework: Unit and integration test suite with pytest
Security Scanning: Automated security scans with Bandit
Code Quality: Linting with Pylint, formatting with Black

AWS Services

AWS Lambda: Serverless compute for all business logic
DynamoDB: NoSQL database for subnet and IP allocation data
API Gateway: RESTful API with authentication support
CloudWatch: Logging and monitoring

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        API Gateway                          │
│            https://api.example.com/v1/                      │
└────────────────────┬────────────────────────────────────────┘
                     │
    ┌────────────────┼────────────────┐
    │                │                │
    ▼                ▼                ▼
┌─────────┐    ┌──────────┐    ┌────────────┐
│ Subnet  │    │    IP    │    │  Calculate │
│ Manager │    │ Manager  │    │  Subnets   │
│ Lambda  │    │  Lambda  │    │   Lambda   │
└────┬────┘    └─────┬────┘    └──────┬─────┘
     │               │                 │
     └───────────────┼─────────────────┘
                     │
                     ▼
            ┌─────────────────┐
            │    DynamoDB     │
            │  Subnets Table  │
            │    IPs Table    │
            └─────────────────┘

Key Design Decisions

Serverless Architecture

No servers to manage or patch
Auto-scaling based on demand
Pay-per-use pricing model

DynamoDB for Storage

Single-digit millisecond latency
Automatic scaling
Built-in redundancy

API Gateway Integration

RESTful API design
Request validation
Rate limiting and throttling

🚀 Quick Start

Prerequisites

Python 3.9 or higher
AWS CLI configured with credentials
Pulumi CLI installed
Git

Installation

# Clone repository
git clone https://github.com/Sparty-5A/aws-ipam-serverless.git
cd aws-ipam-serverless

# Install dependencies
pip install -e ".[dev]"

# Initialize Pulumi
pulumi login --local
pulumi stack init dev

# Deploy to AWS
pulumi up

First API Call

# Get API Gateway URL
API_URL=$(pulumi stack output api_gateway_url)

# Create a subnet
curl -X POST $API_URL/subnets \
  -H "Content-Type: application/json" \
  -d '{
    "network": "192.168.1.0/24",
    "name": "production-subnet",
    "description": "Main production network"
  }'

# List all subnets
curl $API_URL/subnets

📡 API Endpoints

Subnet Management

Create Subnet

POST /subnets
Content-Type: application/json

{
  "network": "192.168.1.0/24",
  "name": "my-subnet",
  "description": "Optional description"
}

List Subnets

GET /subnets

Get Subnet

GET /subnets/{subnet_id}

Update Subnet

PUT /subnets/{subnet_id}
Content-Type: application/json

{
  "name": "updated-name",
  "description": "Updated description"
}

Delete Subnet

DELETE /subnets/{subnet_id}

IP Address Management

Allocate IP

POST /ips/allocate
Content-Type: application/json

{
  "subnet_id": "subnet-123",
  "hostname": "server01"
}

List IPs in Subnet

GET /ips?subnet_id=subnet-123

Release IP

DELETE /ips/{ip_address}

Subnet Calculator

Calculate Subnets

POST /calculate
Content-Type: application/json

{
  "parent_network": "192.168.0.0/16",
  "subnet_count": 256
}

Health Check

GET /health

💻 Development

Local Development Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black .
pylint lambda_functions infrastructure

# Run security scan
bandit -r lambda_functions infrastructure

Project Structure

aws-ipam-serverless/
├── infrastructure/          # Pulumi IaC code
│   ├── api.py              # API Gateway configuration
│   ├── compute.py          # Lambda function definitions
│   └── storage.py          # DynamoDB table definitions
├── lambda_functions/        # Lambda function code
│   ├── subnet_manager/     # Subnet CRUD operations
│   ├── ip_manager/         # IP allocation logic
│   └── shared/             # Shared utilities
├── tests/                   # Test suite
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests
├── .github/workflows/       # CI/CD pipelines
├── pyproject.toml          # Project configuration
└── README.md               # This file

🧪 Testing

Running Tests

# All tests
pytest

# Unit tests only
pytest tests/unit

# Integration tests only
pytest tests/integration

# With coverage report
pytest --cov=lambda_functions --cov=infrastructure --cov-report=html

# Specific test file
pytest tests/unit/test_subnet_calculator.py

# Specific test function
pytest tests/unit/test_subnet_calculator.py::test_calculate_subnets

Test Framework

The project includes a comprehensive test suite:

Unit tests for calculator functions and validators
Integration tests for API endpoints
Mock AWS services with moto for local testing
Parameterized tests for edge cases

🔄 CI/CD Pipeline

Current Implementation

Automated Testing via GitHub Actions:

✅ Tests run automatically on every push
✅ Multiple Python versions tested (3.9, 3.10, 3.11, 3.12)
✅ Code quality checks (Black, Pylint)
✅ Security scanning (Bandit)
✅ Test results uploaded as artifacts

Manual Deployment:

Deployment to AWS is performed manually using Pulumi CLI
This allows for controlled, reviewed deployments
See Deployment section below

GitHub Actions Workflows

Test Workflow (.github/workflows/test.yml)

Runs on every push and pull request
Tests against Python 3.9, 3.10, 3.11, 3.12
Runs code quality and security checks
Uploads test results as artifacts

🚢 Deployment

Deploy to Development

pulumi stack select dev
pulumi up

Deploy to Production

pulumi stack select prod
pulumi config set aws:region us-east-1
pulumi up

Multi-Region Deployment

# Deploy to multiple regions
for region in us-east-1 us-west-2 eu-west-1; do
  pulumi stack select prod-$region
  pulumi config set aws:region $region
  pulumi up --yes
done

Environment Variables

Configure per-stack settings in Pulumi.{stack}.yaml:

config:
  aws:region: us-east-1
  aws-ipam-serverless:environment: production
  aws-ipam-serverless:enableDetailedMetrics: "true"

💰 Cost Analysis

Monthly Cost Breakdown

Development Environment:

Lambda: $0.00 (within Free Tier: 1M requests/month)
DynamoDB: $0.00 (within Free Tier: 25 GB storage)
API Gateway: $0.00 (within Free Tier: 1M requests/month)
CloudWatch Logs: ~$0.50
Total: ~$0.50/month

Production Environment (estimated 10K requests/day):

Lambda: $0.20 (300K requests × $0.20/1M)
DynamoDB: $1.25 (on-demand pricing, minimal usage)
API Gateway: $3.50 (300K requests × $3.50/1M)
CloudWatch: $2.00 (logs + metrics)
Total: ~$7/month

Cost Optimization Tips

Use DynamoDB on-demand pricing for variable workloads
Enable Lambda reserved concurrency for predictable loads
Set CloudWatch log retention policies (7-30 days)
Use API Gateway caching for frequently accessed data

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (pytest)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Pulumi for Infrastructure as Code
Uses AWS Lambda for serverless compute
Testing with pytest and moto
CI/CD powered by GitHub Actions

📞 Contact

Author: Scott Penry
Email: scottpenry@comcast.net
GitHub: @Sparty-5A

⭐ Show Your Support

Give a ⭐️ if this project helped you!

Made with ❤️ using Python, AWS, and Pulumi

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
docs		docs
infrastructure		infrastructure
lambda_functions		lambda_functions
scripts		scripts
tests		tests
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
Pulumi.dev.yaml		Pulumi.dev.yaml
Pulumi.prod.yaml		Pulumi.prod.yaml
Pulumi.yaml		Pulumi.yaml
README.md		README.md
__main__.py		__main__.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

🌐 IPAM Serverless - IP Address Management System

📋 Table of Contents

✨ Features

Core Functionality

DevOps & Infrastructure

AWS Services

🏗️ Architecture

Key Design Decisions

🚀 Quick Start

Prerequisites

Installation

First API Call

📡 API Endpoints

Subnet Management

IP Address Management

Subnet Calculator

💻 Development

Local Development Setup

Project Structure

🧪 Testing

Running Tests

Test Framework

🔄 CI/CD Pipeline

Current Implementation

GitHub Actions Workflows

🚢 Deployment

Deploy to Development

Deploy to Production

Multi-Region Deployment

Environment Variables

💰 Cost Analysis

Monthly Cost Breakdown

Cost Optimization Tips

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Contact

⭐ Show Your Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages