samrenderer 0.2.0

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.
• Environment Diffing: Compare the rendered output of two different environments (e.g., dev vs prod) to visualize configuration differences.
• Dynamic References: Resolves {{resolve:secretsmanager:...}} patterns when an AWS profile is active.
• 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 values from AWS (Imports, Secrets) 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 template.yaml --config samconfig.toml --env dev

Comparing Environments

Generate a colored diff between two environments defined in samconfig.toml. This is useful for detecting drift or verifying configuration changes between stages.

uv run sam-render template.yaml --config samconfig.toml --env dev --env2 stag

AWS Integration (Imports & Secrets)

By default, Fn::ImportValue and {{resolve:secretsmanager:...}} return mock strings. Provide an AWS profile to fetch real values from your AWS account.

# Single Env, single acccout
uv run sam-render template.yaml --config samconfig.toml --env dev --profile my-aws-profile

# Compare Envs in a single account
uv run sam-render template.yaml --config samconfig.toml --env dev --env2 dev1 --profile my-aws-profile

# Compare Envs in different accounts
uv run sam-render template.yaml --config samconfig.toml --env dev --env2 dev1 --profile my-aws-profile --profile2 my-aws-profile2

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).
Dynamic	{{resolve:...}}	✅	Supports Secrets Manager lookups (JSON & String) with --profile.

Development & Testing

Makefile is used to provide consistency between local and remote builds.

make help

Tests are written using pytest.

make test