samrenderer 0.1.1

A tool to render SAM templates locally with SAM config overrides

SAM Template Renderer

A lightweight Python tool to parse, resolve, and render AWS SAM and CloudFormation templates locally.

This tool is designed to help debug complex template logic—specifically Mappings, Conditions, and Substitutions—without needing to deploy to AWS. It resolves intrinsic functions locally and outputs the final "rendered" YAML.

Features

• Intrinsic Function Resolution: Evaluates Fn::FindInMap, Fn::If, Fn::Sub, Fn::Join, Fn::Select, Fn::Split, and more locally.
• Logic Handling: fully supports boolean logic (Fn::And, Fn::Or, Fn::Not, Fn::Equals) to correctly evaluate Condition blocks.
• SAM Config Support: Parses samconfig.toml to apply environment-specific parameter_overrides automatically.
• Custom YAML Tags: Handles short-form CloudFormation tags (e.g., !Ref, !Sub, !GetAtt) without parsing errors.
• Hybrid Resolution: Mocks runtime values (like Resource IDs) but can optionally fetch real Fn::ImportValue data from AWS if a profile is provided.
• Extended Syntax: Supports custom 4th-argument "DefaultValue" syntax for Fn::FindInMap.

Installation

This project is managed with uv.

# Clone the repository
git clone [e-mail]:ryanm101/samrenderer.git
cd samrenderer

# Install dependencies and sync environment
uv sync

Usage

Run the renderer against a template file. You can optionally specify a samconfig.toml environment or an AWS profile.

Basic Rendering

Resolves parameters using defaults defined in the template.uv run sam-render template.yaml

Using SAM Config (Recommended)

Applies parameters from [<env>.deploy.parameters] in samconfig.toml.

uv run sam-render examples/template.yaml --config examples/samconfig.toml --env dev

Fetching Real Exports

By default, Fn::ImportValue returns a mock string. Provide an AWS profile to fetch real values from CloudFormation exports.

uv run sam-render template.yaml --config samconfig.toml --env dev --profile my-aws-profile

Supported Functions

Category	Function	Status	Notes
Core	Ref	✅	Resolves Parameters/Pseudo-params; mocks Resources.
	Fn::GetAtt	⚠️	Returns mock string mock-resource-attr.
	Fn::ImportValue	✅	Fetches from AWS if --profile is set, otherwise mocks.
Logic	Fn::If	✅	Full support.
	Fn::Equals	✅	Full support.
	Fn::Not	✅	Full support.
	Fn::And / Or	✅	Full support.
	Condition	✅	Resolves Condition keys in dictionaries.
Maps	Fn::FindInMap	✅	Supports standard 3-arg and custom 4-arg (DefaultValue) syntax.
String	Fn::Sub	✅	Supports String and Key-Value map interpolation.
	Fn::Join	✅	Full support.
	Fn::Split	✅	Full support.
	Fn::Select	✅	Full support.
	Fn::Base64	⚠️	️Returns readable string [Base64: ...] instead of encoding.
	Fn::GetAZs	⚠️	Returns mock list based on Region (e.g., us-east-1a, 1b, 1c).

Development & Testing

Tests are written using pytest.

# Run all tests
uv run pytest