Provider Templates

Specialized templates for popular Terraform providers, automatically optimizing output for provider-specific resource types.

How Provider Templates Work

tfplan2md automatically detects resource types and applies specialized templates when available.

Template Resolution

When rendering a resource change, tfplan2md follows this resolution order:

  1. Provider-specific template — e.g., azurerm/firewall_network_rule_collection.sbn
  2. Default template — Generic rendering for all resource types

This ensures specialized templates are used when available, with graceful fallback to generic rendering.

Supported Providers

The following providers have specialized template support:

☁️

Azure (azurerm)

Implemented

Comprehensive support for Azure resources with inline diffing, resource ID formatting, and role assignment enhancements.

Specialized Resources

  • Firewall Network Rule Collections — Inline diff of rules (added/removed/unchanged)
  • Network Security Groups — Rule-level diffing with priority awareness
  • Role Assignments — Principal name mapping and readable scope display

Global Enhancements

  • Resource ID Formatting — Long Azure IDs broken into readable scopes
  • Semantic Icons — Visual indicators for IPs (🌐), ports (🔌), protocols (📨/🔗), principals (👤/👥/💻)
  • Boolean Formatting — ✅/❌ for true/false values
View Documentation See Examples
🔧

Azure DevOps

Partial Support

Specialized support for Azure DevOps variable groups with semantic diffing and secret protection.

Implemented Resources

  • Variable Groups — Variable-level diffing with secret value protection

Planned Resources

  • Projects and project settings
  • Build and release pipelines
  • Service connections

Status: Variable groups implemented. Additional resources in planning phase.

View Documentation
🔐

Azure AD (azuread)

Planned

Planned support for Azure Active Directory resources with emphasis on group memberships and application configurations.

Planned Resources

  • Groups and group memberships
  • Applications and service principals
  • Conditional access policies
  • Directory roles

Status: In planning phase. Contributions welcome!

View Documentation
📊

Microsoft Graph

Planned

Planned support for Microsoft Graph resources including users, groups, and policies.

Planned Resources

  • Users and user settings
  • Groups and group settings
  • Policies and policy assignments

Status: In planning phase. Contributions welcome!

View Documentation
💡

Your Provider

We Need You!

Need support for a different Terraform provider? We'd love to hear from you!

How to Help

  • Request a provider — Open an issue describing which provider you need
  • Contribute templates — Submit provider-specific templates for your use case
  • Share examples — Help us understand which resources need specialized rendering

Community-driven: Provider support grows based on user needs. Your input helps prioritize development!

Request Provider Contribute

Custom Templates

Create your own provider-specific templates using Scriban syntax.

Template Structure

Templates/
├── default.sbn           # Default template for all resources
├── summary.sbn           # Summary-only template
└── azurerm/              # Provider-specific templates
    ├── firewall_network_rule_collection.sbn
    ├── network_security_group.sbn
    └── role_assignment.sbn

Creating a Custom Template

  1. Create a directory structure: Templates/<provider>/
  2. Add a .sbn file named after the resource type (e.g., storage_account.sbn)
  3. Write Scriban template using available properties from the resource change
  4. Test with --template flag:
    docker run -v $(pwd)/Templates:/templates oocx/tfplan2md --template /templates/default.sbn

Example: Custom Firewall Rule Template

{{~ # Firewall Network Rule Collection Template ~}}
{{~ if change.action == "create" || change.action == "update" ~}}
### {{ change.address }}

{{~ if after.rule ~}}
**Rules:**
{{~ for rule in after.rule ~}}
- **{{ rule.name }}**: {{ rule.source_addresses | array.join ", " }} → {{ rule.destination_addresses | array.join ", " }} ({{ rule.protocols | array.join ", " }})
{{~ end ~}}
{{~ end ~}}
{{~ end ~}}

For complete template documentation, see Template Customization Guide.

Contributing Provider Templates

We welcome contributions of new provider templates!

🎯

Good Candidates for Templates

  • Resources with complex nested structures (rules, policies, configurations)
  • Resources where index-based diffs are confusing
  • Resources with long IDs or references that need formatting
  • Resources where semantic comparison adds value (e.g., firewall rules)
📋

Contribution Process

  1. Identify — Find a resource that could benefit from specialized rendering
  2. Design — Create a Scriban template that improves readability
  3. Test — Ensure it works with all actions (create, update, replace, delete)
  4. Document — Explain what improvements the template provides
  5. Submit — Follow the contribution guidelines
✨

Template Design Guidelines

  • Focus on showing what changed, not just the new state
  • Use inline diffing when appropriate (added/removed/unchanged)
  • Format complex values for readability (tables, lists, collapsible sections)
  • Add visual icons for common value types (IPs, ports, protocols)
  • Keep output concise; use collapsible sections for details
  • Test with real-world Terraform plans
Request Provider Support Contributing Guide